Better document a constructor of FE_Q.

diff --git a/include/deal.II/fe/fe_q.h b/include/deal.II/fe/fe_q.h
index 34ebe53e6c1f9b1db5ded1854f7142bb1f9860e5..967c26a9026a3faa4fe744248586e9dee9d9dfe8 100644 (file)
--- a/include/deal.II/fe/fe_q.h
+++ b/include/deal.II/fe/fe_q.h
@@ -564,6 +564,34 @@ public:
    * constructor that specifies the polynomial degree only. For selecting
    * equidistant nodes at <tt>fe_degree > 2</tt>, construct
    * <tt>FE_Q<dim>(QIterated<1>(QTrapezoid<1>(),fe_degree))</tt>.
+   *
+   * The *space* created by this constructor is the
+   * same as if you had called `FE_Q<dim>(points.size()-1)`, but what *is*
+   * different are the basis functions of this space. This is useful in
+   * contexts where one wants to achieve certain properties of the matrices
+   * that result from integrating bilinear forms of these shape functions.
+   * For example, when computing the mass matrix on cell $K$,
+   * @f[
+   *   M_{ij}^K = \int_K \varphi_i(\mathbf x) \varphi_j(\mathbf x) \; dx
+   * @f]
+   * one generally applies a quadrature formula and approximates the real
+   * mass matrix by the following:
+   * @f[
+   *   M_{ij}^K = \sum_q \varphi_i(\mathbf x_q) \varphi_j(\mathbf x_q) w_q,
+   * @f]
+   * where the locations of the quadrature points $\mathbf x_q$ and the
+   * weights $w_q$ depend on the cell $K$. If the quadrature formula used
+   * to define these points $\mathbf x_q$ is the same as the one passed
+   * to this constructor (or, in higher dimensions, is generated by a
+   * tensor product of the one used to the constructor), then
+   * $\varphi_i(\mathbf x_q) = \delta_{iq}$, and the matrix reduces to
+   * @f[
+   *   M_{ij}^K = \sum_q \delta_{iq} \delta_{jq} w_q = \delta_{ij} w_i,
+   * @f]
+   * i.e., a diagonal matrix with the weights $w_i$ on the diagonal. Such
+   * constructions are quite useful when using explicit time stepping
+   * methods because, for example, one then only has to invert a diagonal
+   * mass matrix in each time step when solving the linear system.
    */
   FE_Q(const Quadrature<1> &points);