Better explain the purpose of the L-singularity function.

diff --git a/include/deal.II/base/function_lib.h b/include/deal.II/base/function_lib.h
index e4b9a83c60e125facf64be185efef535a099ccb4..589a2fd654d982308e37fe10a943056499eb3866 100644 (file)
--- a/include/deal.II/base/function_lib.h
+++ b/include/deal.II/base/function_lib.h
@@ -381,11 +381,29 @@ namespace Functions
 
 
   /**
-   * Harmonic singularity on the L-shaped domain in 2D.
+   * A function that solves the Laplace equation (with specific
+   * boundary values but zero right hand side) and that has a
+   * singularity at the center of the L-shaped domain in 2D (i.e.,
+   * at the location of the re-entrant corner of this non-convex
+   * domain).
    *
    * The function is given in polar coordinates by $r^{\frac{2}{3}}
-   * \sin(\frac{2}{3} \phi)$ with a singularity at the origin and should be
-   * used with GridGenerator::hyper_L().
+   * \sin(\frac{2}{3} \phi)$ with a singularity at the origin and
+   * should be used with GridGenerator::hyper_L(). Here, $\phi$ is
+   * defined as the *clockwise* angle against the positive $x$-axis.
+   *
+   * This function is often used to illustrate that the solutions of the Laplace
+   * equation
+   * @f[
+   *   -\Delta u = 0
+   * @f]
+   * can be singular even if the boundary values are smooth. (Here, if the
+   * domain is the L-shaped domain $(-1,1)^2 \backslash [0,1]^2$, the
+   * boundary values for $u$ are zero on the two line segments adjacent to the
+   * origin, and equal to $r^{\frac{2}{3}} \sin(\frac{2}{3} \phi)$ on the
+   * remaining parts of the boundary.) The function itself remains bounded on
+   * the domain, but its gradient is of the form $r^{-1/3}$ in the vicinity of
+   * the origin and consequently diverges as one approaches the origin.
    *
    * @ingroup functions
    */