Update documentation.

diff --git a/include/deal.II/base/derivative_form.h b/include/deal.II/base/derivative_form.h
index b74fa9eb760861376bc0f4d00addbecfdd994e4a..bf79b842f09837e77cd034ab3e834cc211b700ac 100644 (file)
--- a/include/deal.II/base/derivative_form.h
+++ b/include/deal.II/base/derivative_form.h
@@ -24,13 +24,33 @@ DEAL_II_NAMESPACE_OPEN
  * This class represents the (tangential) derivatives of a function $ f:
  * {\mathbb R}^{\text{dim}} \rightarrow {\mathbb R}^{\text{spacedim}}$. Such
  * functions are always used to map the reference dim-dimensional cell into
- * spacedim-dimensional space. For such objects, the first  derivative of the
- * function is a linear map from ${\mathbb R}^{\text{dim}}$  to ${\mathbb
- * R}^{\text{spacedim}}$, the second derivative a bilinear map from  ${\mathbb
+ * spacedim-dimensional space. For such objects, the first derivative of the
+ * function is a linear map from ${\mathbb R}^{\text{dim}}$ to ${\mathbb
+ * R}^{\text{spacedim}}$, i.e., it can be represented as a matrix
+ * in ${\mathbb R}^{\text{spacedim}\times \text{dim}}. This makes sense
+ * since one would represent the first derivative, $\nabla f(\mathbf x)$
+ * with $\mathbf x\in {\mathbb R}^{\text{dim}}$, in such a way that the
+ * directional derivative in direction $\mathbf d\in {\mathbb R}^{\text{dim}}$
+ * so that
+ * @f{align*}
+ *   \nabla f(\mathbf x) \mathbf d
+ *   = \lim_{\varepsilon\rightarrow 0}
+ *     \frac{f(\mathbf x + \varepsilon \mathbf d) - f(\mathbf x)}{\varepsilon},
+ * @f}
+ * i.e., one needs to be able to multiply the matrix $\nabla f(\mathbf x)$ by
+ * a vector in ${\mathbb R}^{\text{dim}}$, and the result is a difference
+ * of function values, which are in ${\mathbb R}^{\text{spacedim}}. Consequently,
+ * the matrix must be of size $\text{spacedim}\times\text{dim}$.
+ *
+ * Similarly, the second derivative is a bilinear map from  ${\mathbb
  * R}^{\text{dim}} \times  {\mathbb R}^{\text{dim}}$ to ${\mathbb
- * R}^{\text{spacedim}}$ and so on.  In deal.II we represent these derivatives
- * using objects of type DerivativeForm<1,dim,spacedim,Number>,
- * DerivativeForm<2,dim,spacedim,Number> and so on.
+ * R}^{\text{spacedim}}$, which one can think of a rank-3 object of size
+ * $\text{spacedim}\times\text{dim}\times\text{dim}$.
+ *
+ * In deal.II we represent these derivatives
+ * using objects of type DerivativeForm@<1,dim,spacedim,Number@>,
+ * DerivativeForm@<2,dim,spacedim,Number@> and so on.
+ *
  * @author Sebastian Pauletti, 2011, Luca Heltai, 2015
  */
 template <int order, int dim, int spacedim, typename Number=double>