Update the documentation of VectorTools::project_boundary_values().

This had apparently confused a user on the mailing list earlier today, so structure the
documentation better.

diff --git a/include/deal.II/numerics/vector_tools.h b/include/deal.II/numerics/vector_tools.h
index 0f15f4c9788c958cde81205e6171e72acac7869f..5ca67a84f2103229be5d5aef090b590824565852 100644 (file)
--- a/include/deal.II/numerics/vector_tools.h
+++ b/include/deal.II/numerics/vector_tools.h
@@ -1103,48 +1103,51 @@ namespace VectorTools
 
 
   /**
-   * Project a function to the boundary
-   * of the domain, using the given
-   * quadrature formula for the faces. If
-   * the @p boundary_values contained
-   * values before, the new ones are
-   * added, or the old one overwritten if
-   * a node of the boundary part to be
-   * projected on already was in the
-   * variable.
-   *
-   * If @p component_mapping is empty, it
-   * is assumed that the number of
-   * components of @p boundary_function
-   * matches that of the finite element
-   * used by @p dof.
-   *
-   * In 1d, projection equals
-   * interpolation. Therefore,
-   * interpolate_boundary_values is
-   * called.
-   *
-   * @arg @p boundary_values: the result
-   * of this function, a map containing
-   * all indices of degrees of freedom at
-   * the boundary (as covered by the
-   * boundary parts in @p
-   * boundary_functions) and the computed
-   * dof value for this degree of
-   * freedom.
-   *
-   * @arg @p component_mapping: if the
-   * components in @p boundary_functions
-   * and @p dof do not coincide, this
-   * vector allows them to be
-   * remapped. If the vector is not
-   * empty, it has to have one entry for
-   * each component in @p dof. This entry
-   * is the component number in @p
-   * boundary_functions that should be
-   * used for this component in @p
-   * dof. By default, no remapping is
-   * applied.
+   * Project a function or a set of functions to the boundary
+   * of the domain. In other words, compute the solution of the following problem:
+   * Find $u_h \in V_h$ (where $V_h$ is the finite element space represented
+   * by the DoFHandler argument of this function) so that
+   * @f{align*}
+   *   \int_{\Gamma} \varphi_i u_h = \sum_{k \in {\cal K}} \int_{\Gamma_k} \varphi_i f_k,
+   *   \qquad \forall \varphi_i \in V_h
+   * @f}
+   * where $\Gamma = \bigcup_{k \in {\cal K}} \Gamma_k$, $\Gamma_k \subset \partial\Omega$,
+   * $\cal K$ is the set of indices and $f_k$ the corresponding boundary functions
+   * represented in the function map argument @p boundary_values to this
+   * function, and the integrals are evaluated by quadrature. This problem has a
+   * non-unique solution in the interior, but it is well defined for the degrees
+   * of freedom on the part of the boundary, $\Gamma$, for which we do the
+   * integration. The values of $u_h|_\Gamma$, i.e., the nodal values of the degrees
+   * of freedom of this function along the boundary, are then what is computed by
+   * this function.
+   *
+   * @param mapping The mapping that will be used in the transformations necessary to
+   *   integrate along the boundary.
+   * @param dof The DoFHandler that describes the finite element space and the numbering
+   *   of degrees of freedom.
+   * @param boundary_functions A map from boundary indicators to pointers to functions
+   *   that describe the desired values on those parts of the boundary marked
+   *   with this boundary indicator (see @GlossBoundaryIndicator "Boundary indicator").
+   *   The projection happens on only those parts of the boundary whose indicators
+   *   are represented in this map.
+   * @param q The face quadrature used in the integration necessary to compute the
+   *   mass matrix and right hand side of the projection.
+   * @param boundary_values The result of this function. It is a map containing
+   *   all indices of degrees of freedom at the boundary (as covered by the
+   *   boundary parts in @p boundary_functions) and the computed
+   *   dof value for this degree of freedom.  If @p boundary_values contained
+   *   values before, the new ones are added, or the old ones overwritten if
+   *   a node of the boundary part to be projected on was already in this
+   *   map.
+   * @param component_mapping It is sometimes convenient to project a vector-valued
+   *   function onto only parts of a finite element space (for example, to project
+   *   a function with <code>dim</code> components onto the velocity components of a
+   *   <code>dim+1</code> component DoFHandler for a Stokes problem). To allow for
+   *   this, this argument allows components to be remapped. If the vector is not
+   *   empty, it has to have one entry for each vector component of the finite element
+   *   used in @p dof. This entry is the component number in @p boundary_functions
+   *   that should be used for this component in @p dof. By default, no remapping is
+   *   applied.
    */
   template <int dim, int spacedim>
   void project_boundary_values (const Mapping<dim, spacedim>       &mapping,