]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
rewrap comments
authorheister <heister@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 1 Mar 2013 18:53:04 +0000 (18:53 +0000)
committerheister <heister@0785d39b-7218-0410-832d-ea1e28bc413d>
Fri, 1 Mar 2013 18:53:04 +0000 (18:53 +0000)
git-svn-id: https://svn.dealii.org/trunk@28703 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/include/deal.II/fe/fe_tools.h

index ea93077cedbadeff873144e6db3fa531e06e28c6..e15b23cfab89c037f97c1f47c790320c654d7767 100644 (file)
@@ -73,19 +73,12 @@ namespace PETScWrappers
 namespace FETools
 {
   /**
-   * A base class for factory
-   * objects creating finite
-   * elements of a given
-   * degree. Derived classes are
-   * called whenever one wants to
-   * have a transparent way to
-   * create a finite element
-   * object.
-   *
-   * This class is used in the
-   * FETools::get_fe_from_name()
-   * and FETools::add_fe_name()
-   * functions.
+   * A base class for factory objects creating finite elements of a given
+   * degree. Derived classes are called whenever one wants to have a
+   * transparent way to create a finite element object.
+   *
+   * This class is used in the FETools::get_fe_from_name() and
+   * FETools::add_fe_name() functions.
    *
    * @author Guido Kanschat, 2006
    */
@@ -94,42 +87,32 @@ namespace FETools
   {
   public:
     /**
-     * Create a FiniteElement and
-     * return a pointer to it.
+     * Create a FiniteElement and return a pointer to it.
      */
     virtual FiniteElement<dim,spacedim> *
     get (const unsigned int degree) const = 0;
 
     /**
-     * Create a FiniteElement from a
-     * quadrature formula (currently only
-     * implemented for FE_Q) and return a
-     * pointer to it.
+     * Create a FiniteElement from a quadrature formula (currently only
+     * implemented for FE_Q) and return a pointer to it.
      */
 
     virtual FiniteElement<dim,spacedim> *
     get (const Quadrature<1> &quad) const = 0;
     /**
-     * Virtual destructor doing
-     * nothing but making the
-     * compiler happy.
+     * Virtual destructor doing nothing but making the compiler happy.
      */
     virtual ~FEFactoryBase();
   };
 
   /**
-   * A concrete class for factory
-   * objects creating finite
-   * elements of a given degree.
-   *
-   * The class's get() function
-   * generates a finite element
-   * object of the type given as
-   * template argument, and with
-   * the degree (however the finite
-   * element class wishes to
-   * interpret this number) given
-   * as argument to get().
+   * A concrete class for factory objects creating finite elements of a given
+   * degree.
+   *
+   * The class's get() function generates a finite element object of the type
+   * given as template argument, and with the degree (however the finite
+   * element class wishes to interpret this number) given as argument to
+   * get().
    *
    * @author Guido Kanschat, 2006
    */
@@ -138,46 +121,33 @@ namespace FETools
   {
   public:
     /**
-     * Create a FiniteElement and
-     * return a pointer to it.
+     * Create a FiniteElement and return a pointer to it.
      */
     virtual FiniteElement<FE::dimension,FE::dimension> *
     get (const unsigned int degree) const;
 
     /**
-     * Create a FiniteElement from a
-     * quadrature formula (currently only
-     * implemented for FE_Q) and return a
-     * pointer to it.
+     * Create a FiniteElement from a quadrature formula (currently only
+     * implemented for FE_Q) and return a pointer to it.
      */
     virtual FiniteElement<FE::dimension,FE::dimension> *
     get (const Quadrature<1> &quad) const;
   };
 
   /**
-   * @warning In most cases, you
-   * will probably want to use
+   * @warning In most cases, you will probably want to use
    * compute_base_renumbering().
    *
-   * Compute the vector required to
-   * renumber the dofs of a cell by
-   * component. Furthermore,
-   * compute the vector storing the
-   * start indices of each
-   * component in the local block
-   * vector.
-   *
-   * The second vector is organized
-   * such that there is a vector
-   * for each base element
-   * containing the start index for
-   * each component served by this
-   * base element.
-   *
-   * While the first vector is
-   * checked to have the correct
-   * size, the second one is
-   * reinitialized for convenience.
+   * Compute the vector required to renumber the dofs of a cell by
+   * component. Furthermore, compute the vector storing the start indices of
+   * each component in the local block vector.
+   *
+   * The second vector is organized such that there is a vector for each base
+   * element containing the start index for each component served by this base
+   * element.
+   *
+   * While the first vector is checked to have the correct size, the second
+   * one is reinitialized for convenience.
    */
   template<int dim, int spacedim>
   void compute_component_wise(
@@ -186,22 +156,15 @@ namespace FETools
     std::vector<std::vector<unsigned int> > &start_indices);
 
   /**
-   * Compute the vector required to
-   * renumber the dofs of a cell by
-   * block. Furthermore, compute
-   * the vector storing either the
-   * start indices or the size of
-   * each local block vector.
-   *
-   * If the @p bool parameter is
-   * true, @p block_data is filled
-   * with the start indices of each
-   * local block. If it is false,
-   * then the block sizes are
+   * Compute the vector required to renumber the dofs of a cell by
+   * block. Furthermore, compute the vector storing either the start indices
+   * or the size of each local block vector.
+   *
+   * If the @p bool parameter is true, @p block_data is filled with the start
+   * indices of each local block. If it is false, then the block sizes are
    * returned.
    *
-   * @todo Which way does this
-   * vector map the numbers?
+   * @todo Which way does this vector map the numbers?
    */
   template<int dim, int spacedim>
   void compute_block_renumbering (
@@ -215,18 +178,13 @@ namespace FETools
    * @{
    */
   /**
-   * Gives the interpolation matrix
-   * that interpolates a @p fe1-
-   * function to a @p fe2-function on
-   * each cell. The interpolation_matrix
-   * needs to be of size
-   * <tt>(fe2.dofs_per_cell, fe1.dofs_per_cell)</tt>.
-   *
-   * Note, that if the finite element
-   * space @p fe1 is a subset of
-   * the finite element space
-   * @p fe2 then the @p interpolation_matrix
-   * is an embedding matrix.
+   * Gives the interpolation matrix that interpolates a @p fe1- function to a
+   * @p fe2-function on each cell. The interpolation_matrix needs to be of
+   * size <tt>(fe2.dofs_per_cell, fe1.dofs_per_cell)</tt>.
+   *
+   * Note, that if the finite element space @p fe1 is a subset of the finite
+   * element space @p fe2 then the @p interpolation_matrix is an embedding
+   * matrix.
    */
   template <int dim, typename number, int spacedim>
   void
@@ -235,22 +193,15 @@ namespace FETools
                            FullMatrix<number> &interpolation_matrix);
 
   /**
-   * Gives the interpolation matrix
-   * that interpolates a @p fe1-
-   * function to a @p fe2-function, and
-   * interpolates this to a second
-   * @p fe1-function on
-   * each cell. The interpolation_matrix
-   * needs to be of size
+   * Gives the interpolation matrix that interpolates a @p fe1- function to a
+   * @p fe2-function, and interpolates this to a second @p fe1-function on
+   * each cell. The interpolation_matrix needs to be of size
    * <tt>(fe1.dofs_per_cell, fe1.dofs_per_cell)</tt>.
    *
-   * Note, that this function only
-   * makes sense if the finite element
-   * space due to @p fe1 is not a subset of
-   * the finite element space due to
-   * @p fe2, as if it were a subset then
-   * the @p interpolation_matrix would be
-   * only the unit matrix.
+   * Note, that this function only makes sense if the finite element space due
+   * to @p fe1 is not a subset of the finite element space due to @p fe2, as
+   * if it were a subset then the @p interpolation_matrix would be only the
+   * unit matrix.
    */
   template <int dim, typename number, int spacedim>
   void
@@ -259,21 +210,14 @@ namespace FETools
                                 FullMatrix<number> &interpolation_matrix);
 
   /**
-   * Gives the unit matrix minus the
-   * back interpolation matrix.
-   * The @p difference_matrix
-   * needs to be of size
-   * <tt>(fe1.dofs_per_cell, fe1.dofs_per_cell)</tt>.
+   * Gives the unit matrix minus the back interpolation matrix.  The @p
+   * difference_matrix needs to be of size <tt>(fe1.dofs_per_cell,
+   * fe1.dofs_per_cell)</tt>.
    *
-   * This function gives
-   * the matrix that transforms a
-   * @p fe1 function $z$ to $z-I_hz$
-   * where $I_h$ denotes the interpolation
-   * operator from the @p fe1 space to
-   * the @p fe2 space. This matrix hence
-   * is useful to evaluate
-   * error-representations where $z$
-   * denotes the dual solution.
+   * This function gives the matrix that transforms a @p fe1 function $z$ to
+   * $z-I_hz$ where $I_h$ denotes the interpolation operator from the @p fe1
+   * space to the @p fe2 space. This matrix hence is useful to evaluate
+   * error-representations where $z$ denotes the dual solution.
    */
   template <int dim, typename number, int spacedim>
   void
@@ -282,9 +226,7 @@ namespace FETools
                                       FullMatrix<number> &difference_matrix);
 
   /**
-   * Compute the local
-   * $L^2$-projection matrix from
-   * fe1 to fe2.
+   * Compute the local $L^2$-projection matrix from fe1 to fe2.
    */
   template <int dim, typename number, int spacedim>
   void get_projection_matrix(const FiniteElement<dim,spacedim> &fe1,
@@ -292,123 +234,70 @@ namespace FETools
                              FullMatrix<number> &matrix);
 
   /**
-   * Compute the matrix of nodal
-   * values of a finite element
-   * applied to all its shape
-   * functions.
-   *
-   * This function is supposed to
-   * help building finite elements
-   * from polynomial spaces and
-   * should be called inside the
-   * constructor of an
-   * element. Applied to a
-   * completely initialized finite
-   * element, the result should be
-   * the unit matrix by definition
-   * of the node values.
-   *
-   * Using this matrix allows the
-   * construction of the basis of
-   * shape functions in two steps.
+   * Compute the matrix of nodal values of a finite element applied to all its
+   * shape functions.
+   *
+   * This function is supposed to help building finite elements from
+   * polynomial spaces and should be called inside the constructor of an
+   * element. Applied to a completely initialized finite element, the result
+   * should be the unit matrix by definition of the node values.
+   *
+   * Using this matrix allows the construction of the basis of shape functions
+   * in two steps.
+   *
    * <ol>
    *
-   * <li>Define the space of shape
-   * functions using an arbitrary
-   * basis <i>w<sub>j</sub></i> and
-   * compute the matrix <i>M</i> of
-   * node functionals
-   * <i>N<sub>i</sub></i> applied
-   * to these basis functions.
-   *
-   * <li>Compute the basis
-   * <i>v<sub>j</sub></i> of the
-   * finite element shape function
-   * space by applying
-   * <i>M<sup>-1</sup></i> to the
-   * basis <i>w<sub>j</sub></i>.
+   * <li>Define the space of shape functions using an arbitrary basis
+   * <i>w<sub>j</sub></i> and compute the matrix <i>M</i> of node functionals
+   * <i>N<sub>i</sub></i> applied to these basis functions.
+   *
+   * <li>Compute the basis <i>v<sub>j</sub></i> of the finite element shape
+   * function space by applying <i>M<sup>-1</sup></i> to the basis
+   * <i>w<sub>j</sub></i>.
+   *
    * </ol>
    *
-   * @note The FiniteElement must
-   * provide generalized support
-   * points and and interpolation
-   * functions.
+   * @note The FiniteElement must provide generalized support points and and
+   * interpolation functions.
    */
   template <int dim, int spacedim>
   void compute_node_matrix(FullMatrix<double> &M,
                            const FiniteElement<dim,spacedim> &fe);
 
   /**
-   * For all possible (isotropic
-   * and anisotropic) refinement
-   * cases compute the embedding
-   * matrices from a coarse cell to
-   * the child cells. Each column
-   * of the resulting matrices
-   * contains the representation of
-   * a coarse grid basis functon by
-   * the fine grid basis; the
-   * matrices are split such that
-   * there is one matrix for every
-   * child.
-   *
-   * This function computes the
-   * coarse grid function in a
-   * sufficiently large number of
-   * quadrature points and fits the
-   * fine grid functions using
-   * least squares
-   * approximation. Therefore, the
-   * use of this function is
-   * restricted to the case that
-   * the finite element spaces are
-   * actually nested.
-   *
-   * Note, that
-   * <code>matrices[refinement_case-1][child]</code>
-   * includes the embedding (or prolongation)
-   * matrix of child
-   * <code>child</code> for the
-   * RefinementCase
-   * <code>refinement_case</code>. Here,
-   * we use
-   * <code>refinement_case-1</code>
-   * instead of
-   * <code>refinement_case</code>
-   * as for
-   * RefinementCase::no_refinement(=0)
-   * there are no prolongation
-   * matrices available.
-   *
-   * Typically this function is
-   * called by the various
-   * implementations of
-   * FiniteElement classes in order
-   * to fill the respective
-   * FiniteElement::prolongation
+   * For all possible (isotropic and anisotropic) refinement cases compute the
+   * embedding matrices from a coarse cell to the child cells. Each column of
+   * the resulting matrices contains the representation of a coarse grid basis
+   * functon by the fine grid basis; the matrices are split such that there is
+   * one matrix for every child.
+   *
+   * This function computes the coarse grid function in a sufficiently large
+   * number of quadrature points and fits the fine grid functions using least
+   * squares approximation. Therefore, the use of this function is restricted
+   * to the case that the finite element spaces are actually nested.
+   *
+   * Note, that <code>matrices[refinement_case-1][child]</code> includes the
+   * embedding (or prolongation) matrix of child <code>child</code> for the
+   * RefinementCase <code>refinement_case</code>. Here, we use
+   * <code>refinement_case-1</code> instead of <code>refinement_case</code> as
+   * for RefinementCase::no_refinement(=0) there are no prolongation matrices
+   * available.
+   *
+   * Typically this function is called by the various implementations of
+   * FiniteElement classes in order to fill the respective
+   * FiniteElement::prolongation matrices.
+   *
+   * @param fe The finite element class for which we compute the embedding
    * matrices.
    *
-   * @param fe The finite element
-   * class for which we compute the
-   * embedding matrices.
-   *
-   * @param matrices A reference to
-   * RefinementCase<dim>::isotropic_refinement
-   * vectors of FullMatrix
-   * objects. Each vector
-   * corresponds to one
-   * RefinementCase @p
-   * refinement_case and is of the
-   * vector size
-   * GeometryInfo<dim>::n_children(refinement_case). This
-   * is the format used in
-   * FiniteElement, where we want
-   * to use this function mostly.
-   *
-   * @param isotropic_only Set
-   * to <code>true</code> if you only
-   * want to compute matrices for
-   * isotropic refinement.
+   * @param matrices A reference to RefinementCase<dim>::isotropic_refinement
+   * vectors of FullMatrix objects. Each vector corresponds to one
+   * RefinementCase @p refinement_case and is of the vector size
+   * GeometryInfo<dim>::n_children(refinement_case). This is the format used
+   * in FiniteElement, where we want to use this function mostly.
+   *
+   * @param isotropic_only Set to <code>true</code> if you only want to
+   * compute matrices for isotropic refinement.
    */
   template <int dim, typename number, int spacedim>
   void compute_embedding_matrices(const FiniteElement<dim,spacedim> &fe,
@@ -416,31 +305,17 @@ namespace FETools
                                   const bool isotropic_only = false);
 
   /**
-   * Compute the embedding matrices
-   * on faces needed for constraint
-   * matrices.
+   * Compute the embedding matrices on faces needed for constraint matrices.
+   *
+   * @param fe The finite element for which to compute these matrices.  @param
+   * matrices An array of <i>GeometryInfo<dim>::subfaces_per_face =
+   * 2<sup>dim-1</sup></i> FullMatrix objects,holding the embedding matrix for
+   * each subface.  @param face_coarse The number of the face on the coarse
+   * side of the face for which this is computed.  @param face_fine The number
+   * of the face on the refined side of the face for which this is computed.
    *
-   * @param fe The finite element
-   * for which to compute these
-   * matrices.  @param matrices An
-   * array of
-   * <i>GeometryInfo<dim>::subfaces_per_face
-   * = 2<sup>dim-1</sup></i>
-   * FullMatrix objects,holding the
-   * embedding matrix for each
-   * subface.  @param face_coarse
-   * The number of the face on the
-   * coarse side of the face for
-   * which this is computed.
-   * @param face_fine The number of
-   * the face on the refined side
-   * of the face for which this is
-   * computed.
-   *
-   * @warning This function will be
-   * used in computing constraint
-   * matrices. It is not
-   * sufficiently tested yet.
+   * @warning This function will be used in computing constraint matrices. It
+   * is not sufficiently tested yet.
    */
   template <int dim, typename number, int spacedim>
   void
@@ -450,57 +325,31 @@ namespace FETools
                                   const unsigned int face_fine);
 
   /**
-   * For all possible (isotropic
-   * and anisotropic) refinement
-   * cases compute the
-   * <i>L<sup>2</sup></i>-projection
-   * matrices from the children to
-   * a coarse cell.
-   *
-   * Note, that
-   * <code>matrices[refinement_case-1][child]</code>
-   * includes the projection (or restriction)
-   * matrix of child
-   * <code>child</code> for the
-   * RefinementCase
-   * <code>refinement_case</code>. Here,
-   * we use
-   * <code>refinement_case-1</code>
-   * instead of
-   * <code>refinement_case</code>
-   * as for
-   * RefinementCase::no_refinement(=0)
-   * there are no projection
-   * matrices available.
-   *
-   * Typically this function is
-   * called by the various
-   * implementations of
-   * FiniteElement classes in order
-   * to fill the respective
-   * FiniteElement::restriction
-   * matrices.
+   * For all possible (isotropic and anisotropic) refinement cases compute the
+   * <i>L<sup>2</sup></i>-projection matrices from the children to a coarse
+   * cell.
    *
-   * @arg fe The finite element
-   * class for which we compute the
-   * projection matrices.  @arg
-   * matrices A reference to
-   * <tt>RefinementCase<dim>::isotropic_refinement</tt>
-   * vectors of FullMatrix
-   * objects. Each vector
-   * corresponds to one
-   * RefinementCase @p
-   * refinement_case and is of the
-   * vector size
-   * <tt>GeometryInfo<dim>::n_children(refinement_case)</tt>. This
-   * is the format used in
-   * FiniteElement, where we want
-   * to use this function mostly.
-   *
-   * @arg isotropic_only Set
-   * to <code>true</code> if you only
-   * want to compute matrices for
-   * isotropic refinement.
+   * Note, that <code>matrices[refinement_case-1][child]</code> includes the
+   * projection (or restriction) matrix of child <code>child</code> for the
+   * RefinementCase <code>refinement_case</code>. Here, we use
+   * <code>refinement_case-1</code> instead of <code>refinement_case</code> as
+   * for RefinementCase::no_refinement(=0) there are no projection matrices
+   * available.
+   *
+   * Typically this function is called by the various implementations of
+   * FiniteElement classes in order to fill the respective
+   * FiniteElement::restriction matrices.
+   *
+   * @arg fe The finite element class for which we compute the projection
+   * matrices.  @arg matrices A reference to
+   * <tt>RefinementCase<dim>::isotropic_refinement</tt> vectors of FullMatrix
+   * objects. Each vector corresponds to one RefinementCase @p refinement_case
+   * and is of the vector size
+   * <tt>GeometryInfo<dim>::n_children(refinement_case)</tt>. This is the
+   * format used in FiniteElement, where we want to use this function mostly.
+   *
+   * @arg isotropic_only Set to <code>true</code> if you only want to compute
+   * matrices for isotropic refinement.
    */
   template <int dim, typename number, int spacedim>
   void compute_projection_matrices(
@@ -509,165 +358,89 @@ namespace FETools
     const bool isotropic_only = false);
 
   /**
-   * Projects scalar data defined in
-   * quadrature points to a finite element
+   * Projects scalar data defined in quadrature points to a finite element
    * space on a single cell.
    *
-   * What this function does is the
-   * following: assume that there is scalar
-   * data <tt>u<sub>q</sub>, 0 <= q <
-   * Q:=quadrature.size()</tt>
-   * defined at the quadrature points of a
-   * cell, with the points defined by the
-   * given <tt>rhs_quadrature</tt>
-   * object. We may then want to ask for
-   * that finite element function (on a
-   * single cell) <tt>v<sub>h</sub></tt> in
-   * the finite-dimensional space defined
-   * by the given FE object that is the
-   * projection of <tt>u</tt> in the
-   * following sense:
-   *
-   * Usually, the projection
-   * <tt>v<sub>h</sub></tt> is that
-   * function that satisfies
-   * <tt>(v<sub>h</sub>,w)=(u,w)</tt> for
-   * all discrete test functions
-   * <tt>w</tt>. In the present case, we
-   * can't evaluate the right hand side,
-   * since <tt>u</tt> is only defined in
-   * the quadrature points given by
-   * <tt>rhs_quadrature</tt>, so we replace
-   * it by a quadrature
-   * approximation. Likewise, the left hand
-   * side is approximated using the
-   * <tt>lhs_quadrature</tt> object; if
-   * this quadrature object is chosen
-   * appropriately, then the integration of
-   * the left hand side can be done
-   * exactly, without any
-   * approximation. The use of different
-   * quadrature objects is necessary if the
-   * quadrature object for the right hand
-   * side has too few quadrature points --
-   * for example, if data <tt>q</tt> is
-   * only defined at the cell center, then
-   * the corresponding one-point quadrature
-   * formula is obviously insufficient to
-   * approximate the scalar product on the
-   * left hand side by a definite form.
-   *
-   * After these quadrature approximations,
-   * we end up with a nodal representation
-   * <tt>V<sub>h</sub></tt> of
-   * <tt>v<sub>h</sub></tt> that satisfies
-   * the following system of linear
-   * equations: <tt>M V<sub>h</sub> = Q
-   * U</tt>, where
-   * <tt>M<sub>ij</sub>=(phi_i,phi_j)</tt>
-   * is the mass matrix approximated by
-   * <tt>lhs_quadrature</tt>, and
-   * <tt>Q</tt> is the matrix
-   * <tt>Q<sub>iq</sub>=phi<sub>i</sub>(x<sub>q</sub>)
-   * w<sub>q</sub></tt> where
-   * <tt>w<sub>q</sub></tt> are quadrature
-   * weights; <tt>U</tt> is the vector of
-   * quadrature point data
-   * <tt>u<sub>q</sub></tt>.
-   *
-   * In order to then get the nodal
-   * representation <tt>V<sub>h</sub></tt>
-   * of the projection of <tt>U</tt>, one
-   * computes <tt>V<sub>h</sub> = X U,
-   * X=M<sup>-1</sup> Q</tt>. The purpose
-   * of this function is to compute the
-   * matrix <tt>X</tt> and return it
-   * through the last argument of this
+   * What this function does is the following: assume that there is scalar
+   * data <tt>u<sub>q</sub>, 0 <= q < Q:=quadrature.size()</tt> defined at the
+   * quadrature points of a cell, with the points defined by the given
+   * <tt>rhs_quadrature</tt> object. We may then want to ask for that finite
+   * element function (on a single cell) <tt>v<sub>h</sub></tt> in the
+   * finite-dimensional space defined by the given FE object that is the
+   * projection of <tt>u</tt> in the following sense:
+   *
+   * Usually, the projection <tt>v<sub>h</sub></tt> is that function that
+   * satisfies <tt>(v<sub>h</sub>,w)=(u,w)</tt> for all discrete test
+   * functions <tt>w</tt>. In the present case, we can't evaluate the right
+   * hand side, since <tt>u</tt> is only defined in the quadrature points
+   * given by <tt>rhs_quadrature</tt>, so we replace it by a quadrature
+   * approximation. Likewise, the left hand side is approximated using the
+   * <tt>lhs_quadrature</tt> object; if this quadrature object is chosen
+   * appropriately, then the integration of the left hand side can be done
+   * exactly, without any approximation. The use of different quadrature
+   * objects is necessary if the quadrature object for the right hand side has
+   * too few quadrature points -- for example, if data <tt>q</tt> is only
+   * defined at the cell center, then the corresponding one-point quadrature
+   * formula is obviously insufficient to approximate the scalar product on
+   * the left hand side by a definite form.
+   *
+   * After these quadrature approximations, we end up with a nodal
+   * representation <tt>V<sub>h</sub></tt> of <tt>v<sub>h</sub></tt> that
+   * satisfies the following system of linear equations: <tt>M V<sub>h</sub> =
+   * Q U</tt>, where <tt>M<sub>ij</sub>=(phi_i,phi_j)</tt> is the mass matrix
+   * approximated by <tt>lhs_quadrature</tt>, and <tt>Q</tt> is the matrix
+   * <tt>Q<sub>iq</sub>=phi<sub>i</sub>(x<sub>q</sub>) w<sub>q</sub></tt>
+   * where <tt>w<sub>q</sub></tt> are quadrature weights; <tt>U</tt> is the
+   * vector of quadrature point data <tt>u<sub>q</sub></tt>.
+   *
+   * In order to then get the nodal representation <tt>V<sub>h</sub></tt> of
+   * the projection of <tt>U</tt>, one computes <tt>V<sub>h</sub> = X U,
+   * X=M<sup>-1</sup> Q</tt>. The purpose of this function is to compute the
+   * matrix <tt>X</tt> and return it through the last argument of this
    * function.
    *
-   * Note that this function presently only
-   * supports scalar data. An extension of
-   * the mass matrix is of course trivial,
-   * but one has to define the order of
-   * data in the vector <tt>U</tt> if it
-   * contains vector valued data in all
+   * Note that this function presently only supports scalar data. An extension
+   * of the mass matrix is of course trivial, but one has to define the order
+   * of data in the vector <tt>U</tt> if it contains vector valued data in all
    * quadrature points.
    *
-   * A use for this function is described
-   * in the introduction to the step-18
+   * A use for this function is described in the introduction to the step-18
    * example program.
    *
-   * The opposite of this function,
-   * interpolation of a finite element
-   * function onto quadrature points is
-   * essentially what the
-   * <tt>FEValues::get_function_values</tt>
-   * functions do; to make things a little
-   * simpler, the
+   * The opposite of this function, interpolation of a finite element function
+   * onto quadrature points is essentially what the
+   * <tt>FEValues::get_function_values</tt> functions do; to make things a
+   * little simpler, the
    * <tt>FETools::compute_interpolation_to_quadrature_points_matrix</tt>
    * provides the matrix form of this.
    *
-   * Note that this function works
-   * on a single cell, rather than
-   * an entire triangulation. In
-   * effect, it therefore doesn't
-   * matter if you use a continuous
-   * or discontinuous version of
-   * the finite element.
-   *
-   * It is worth noting that there
-   * are a few confusing cases of
-   * this function. The first one
-   * is that it really only makes
-   * sense to project onto a finite
-   * element that has at most as
-   * many degrees of freedom per
-   * cell as there are quadrature
-   * points; the projection of N
-   * quadrature point data into a
-   * space with M>N unknowns is
-   * well-defined, but often yields
-   * funny and non-intuitive
-   * results. Secondly, one would
-   * think that if the quadrature
-   * point data is defined in the
-   * support points of the finite
-   * element, i.e. the quadrature
-   * points of
-   * <tt>ths_quadrature</tt> equal
-   * <tt>fe.get_unit_support_points()</tt>,
-   * then the projection should be
-   * the identity, i.e. each degree
-   * of freedom of the finite
-   * element equals the value of
-   * the given data in the support
-   * point of the corresponding
-   * shape function. However, this
-   * is not generally the case:
-   * while the matrix <tt>Q</tt> in
-   * that case is the identity
-   * matrix, the mass matrix
-   * <tt>M</tt> is not equal to the
-   * identity matrix, except for
-   * the special case that the
-   * quadrature formula
-   * <tt>lhs_quadrature</tt> also
-   * has its quadrature points in
-   * the support points of the
-   * finite element.
-   *
-   * Finally, this function only defines a
-   * cell wise projection, while one
-   * frequently wants to apply it to all
-   * cells in a triangulation. However, if
-   * it is applied to one cell after the
-   * other, the results from later cells
-   * may overwrite nodal values computed
-   * already from previous cells if degrees
-   * of freedom live on the interfaces
-   * between cells. The function is
-   * therefore most useful for
-   * discontinuous elements.
+   * Note that this function works on a single cell, rather than an entire
+   * triangulation. In effect, it therefore doesn't matter if you use a
+   * continuous or discontinuous version of the finite element.
+   *
+   * It is worth noting that there are a few confusing cases of this
+   * function. The first one is that it really only makes sense to project
+   * onto a finite element that has at most as many degrees of freedom per
+   * cell as there are quadrature points; the projection of N quadrature point
+   * data into a space with M>N unknowns is well-defined, but often yields
+   * funny and non-intuitive results. Secondly, one would think that if the
+   * quadrature point data is defined in the support points of the finite
+   * element, i.e. the quadrature points of <tt>ths_quadrature</tt> equal
+   * <tt>fe.get_unit_support_points()</tt>, then the projection should be the
+   * identity, i.e. each degree of freedom of the finite element equals the
+   * value of the given data in the support point of the corresponding shape
+   * function. However, this is not generally the case: while the matrix
+   * <tt>Q</tt> in that case is the identity matrix, the mass matrix
+   * <tt>M</tt> is not equal to the identity matrix, except for the special
+   * case that the quadrature formula <tt>lhs_quadrature</tt> also has its
+   * quadrature points in the support points of the finite element.
+   *
+   * Finally, this function only defines a cell wise projection, while one
+   * frequently wants to apply it to all cells in a triangulation. However, if
+   * it is applied to one cell after the other, the results from later cells
+   * may overwrite nodal values computed already from previous cells if
+   * degrees of freedom live on the interfaces between cells. The function is
+   * therefore most useful for discontinuous elements.
    */
   template <int dim, int spacedim>
   void
@@ -677,15 +450,11 @@ namespace FETools
                                                     FullMatrix<double>       &X);
 
   /**
-   * Given a (scalar) local finite element
-   * function, compute the matrix that maps
-   * the vector of nodal values onto the
-   * vector of values of this function at
-   * quadrature points as given by the
-   * second argument. In a sense, this
-   * function does the opposite of the
-   * FETools::compute_projection_from_quadrature_points_matrix
-   * function.
+   * Given a (scalar) local finite element function, compute the matrix that
+   * maps the vector of nodal values onto the vector of values of this
+   * function at quadrature points as given by the second argument. In a
+   * sense, this function does the opposite of the
+   * FETools::compute_projection_from_quadrature_points_matrix function.
    */
   template <int dim, int spacedim>
   void
@@ -694,30 +463,17 @@ namespace FETools
                                                      FullMatrix<double>       &I_q);
 
   /**
-   * Computes the projection of tensorial
-   * (first-order tensor)
-   * data stored at the quadrature points
-   * @p vector_of_tensors_at_qp
-   * to data @p vector_of_tensors_at_nodes
-   * at the support points of the cell.
-   * The data in
-   * @p vector_of_tensors_at_qp
-   * is ordered sequentially following the
-   * quadrature point numbering.
-   * The size of
-   * @p vector_of_tensors_at_qp
-   * must correspond to the number of columns
-   * of @p projection_matrix.
-   * The size of @p vector_of_tensors_at_nodes
-   * must correspond to the number of rows of
-   * @p vector_of_tensors_at_nodes .
-   * The projection matrix
-   * @p projection_matrix desribes the
-   * projection of scalar data from the
-   * quadrature points and can be obtained
-   * from the
-   * FETools::compute_projection_from_quadrature_points_matrix
-   * function.
+   * Computes the projection of tensorial (first-order tensor) data stored at
+   * the quadrature points @p vector_of_tensors_at_qp to data @p
+   * vector_of_tensors_at_nodes at the support points of the cell.  The data
+   * in @p vector_of_tensors_at_qp is ordered sequentially following the
+   * quadrature point numbering.  The size of @p vector_of_tensors_at_qp must
+   * correspond to the number of columns of @p projection_matrix.  The size of
+   * @p vector_of_tensors_at_nodes must correspond to the number of rows of @p
+   * vector_of_tensors_at_nodes .  The projection matrix @p projection_matrix
+   * desribes the projection of scalar data from the quadrature points and can
+   * be obtained from the
+   * FETools::compute_projection_from_quadrature_points_matrix function.
    */
   template <int dim>
   void
@@ -729,8 +485,7 @@ namespace FETools
 
 
   /**
-   * same as last function but for a
-   * @p SymmetricTensor .
+   * same as last function but for a @p SymmetricTensor .
    */
   template <int dim>
   void
@@ -744,14 +499,12 @@ namespace FETools
 
   /**
    * This method implements the
-   * FETools::compute_projection_from_quadrature_points_matrix
-   * method for faces of a mesh.
-   * The matrix that it returns, X, is face specific
-   * and its size is fe.dofs_per_cell by
-   * rhs_quadrature.size().
-   * The dimension, dim must be larger than 1 for this class,
-   * since Quadrature<dim-1> objects are required. See the
-   * documentation on the Quadrature class for more information.
+   * FETools::compute_projection_from_quadrature_points_matrix method for
+   * faces of a mesh.  The matrix that it returns, X, is face specific and its
+   * size is fe.dofs_per_cell by rhs_quadrature.size().  The dimension, dim
+   * must be larger than 1 for this class, since Quadrature<dim-1> objects are
+   * required. See the documentation on the Quadrature class for more
+   * information.
    */
   template <int dim, int spacedim>
   void
@@ -770,61 +523,32 @@ namespace FETools
    */
   //@{
   /**
-   * Gives the interpolation of a the
-   * @p dof1-function @p u1 to a
-   * @p dof2-function @p u2. @p dof1 and
-   * @p dof2 need to be DoFHandlers
-   * based on the same triangulation.
-   *
-   * If the elements @p fe1 and @p fe2
-   * are either both continuous or
-   * both discontinuous then this
-   * interpolation is the usual point
-   * interpolation. The same is true
-   * if @p fe1 is a continuous and
-   * @p fe2 is a discontinuous finite
-   * element. For the case that @p fe1
-   * is a discontinuous and @p fe2 is
-   * a continuous finite element
-   * there is no point interpolation
-   * defined at the discontinuities.
-   * Therefore the meanvalue is taken
-   * at the DoF values on the
-   * discontinuities.
-   *
-   * Note that for continuous
-   * elements on grids with hanging
-   * nodes (i.e. locally refined
-   * grids) this function does not
-   * give the expected output.
-   * Indeed, the resulting output
-   * vector does not necessarily
-   * respect continuity
-   * requirements at hanging nodes:
-   * if, for example, you are
-   * interpolating a Q2 field to a
-   * Q1 field, then at hanging
-   * nodes the output field will
-   * have the function value of the
-   * input field, which however is
-   * not usually the mean value of
-   * the two adjacent nodes. It is
-   * thus not part of the Q1
-   * function space on the whole
-   * triangulation, although it is
-   * of course Q1 on each cell.
-   *
-   * For this case (continuous
-   * elements on grids with hanging
-   * nodes), please use the
-   * @p interpolate function with
-   * an additional
-   * @p ConstraintMatrix argument,
-   * see below, or make the field
-   * conforming yourself by calling
-   * the @p distribute function of
-   * your hanging node constraints
-   * object.
+   * Gives the interpolation of a the @p dof1-function @p u1 to a @p
+   * dof2-function @p u2. @p dof1 and @p dof2 need to be DoFHandlers based on
+   * the same triangulation.
+   *
+   * If the elements @p fe1 and @p fe2 are either both continuous or both
+   * discontinuous then this interpolation is the usual point
+   * interpolation. The same is true if @p fe1 is a continuous and @p fe2 is a
+   * discontinuous finite element. For the case that @p fe1 is a discontinuous
+   * and @p fe2 is a continuous finite element there is no point interpolation
+   * defined at the discontinuities.  Therefore the meanvalue is taken at the
+   * DoF values on the discontinuities.
+   *
+   * Note that for continuous elements on grids with hanging nodes
+   * (i.e. locally refined grids) this function does not give the expected
+   * output.  Indeed, the resulting output vector does not necessarily respect
+   * continuity requirements at hanging nodes: if, for example, you are
+   * interpolating a Q2 field to a Q1 field, then at hanging nodes the output
+   * field will have the function value of the input field, which however is
+   * not usually the mean value of the two adjacent nodes. It is thus not part
+   * of the Q1 function space on the whole triangulation, although it is of
+   * course Q1 on each cell.
+   *
+   * For this case (continuous elements on grids with hanging nodes), please
+   * use the @p interpolate function with an additional @p ConstraintMatrix
+   * argument, see below, or make the field conforming yourself by calling the
+   * @p distribute function of your hanging node constraints object.
    */
   template <int dim, int spacedim,
            template <int,int> class DH1,
@@ -837,37 +561,20 @@ namespace FETools
                OutVector               &u2);
 
   /**
-   * Gives the interpolation of a
-   * the @p dof1-function @p u1 to
-   * a @p dof2-function @p u2. @p
-   * dof1 and @p dof2 need to be
-   * DoFHandlers (or
-   * hp::DoFHandlers) based on the
-   * same triangulation.  @p
-   * constraints is a hanging node
-   * constraints object
-   * corresponding to @p dof2. This
-   * object is particular important
-   * when interpolating onto
-   * continuous elements on grids
-   * with hanging nodes (locally
-   * refined grids).
-   *
-   * If the elements @p fe1 and @p fe2
-   * are either both continuous or
-   * both discontinuous then this
-   * interpolation is the usual point
-   * interpolation. The same is true
-   * if @p fe1 is a continuous and
-   * @p fe2 is a discontinuous finite
-   * element. For the case that @p fe1
-   * is a discontinuous and @p fe2 is
-   * a continuous finite element
-   * there is no point interpolation
-   * defined at the discontinuities.
-   * Therefore the meanvalue is taken
-   * at the DoF values on the
-   * discontinuities.
+   * Gives the interpolation of a the @p dof1-function @p u1 to a @p
+   * dof2-function @p u2. @p dof1 and @p dof2 need to be DoFHandlers (or
+   * hp::DoFHandlers) based on the same triangulation.  @p constraints is a
+   * hanging node constraints object corresponding to @p dof2. This object is
+   * particular important when interpolating onto continuous elements on grids
+   * with hanging nodes (locally refined grids).
+   *
+   * If the elements @p fe1 and @p fe2 are either both continuous or both
+   * discontinuous then this interpolation is the usual point
+   * interpolation. The same is true if @p fe1 is a continuous and @p fe2 is a
+   * discontinuous finite element. For the case that @p fe1 is a discontinuous
+   * and @p fe2 is a continuous finite element there is no point interpolation
+   * defined at the discontinuities.  Therefore the meanvalue is taken at the
+   * DoF values on the discontinuities.
    */
   template <int dim, int spacedim,
            template <int, int> class DH1,
@@ -880,30 +587,17 @@ namespace FETools
                     OutVector                &u2);
 
   /**
-   * Gives the interpolation of the
-   * @p fe1-function @p u1 to a
-   * @p fe2-function, and
-   * interpolates this to a second
-   * @p fe1-function named
-   * @p u1_interpolated.
-   *
-   * Note, that this function does
-   * not work on continuous
-   * elements at hanging nodes. For
-   * that case use the
-   * @p back_interpolate function,
-   * below, that takes an
-   * additional
-   * @p ConstraintMatrix object.
-   *
-   * Furthermore note, that for the
-   * specific case when the finite
-   * element space corresponding to
-   * @p fe1 is a subset of the
-   * finite element space
-   * corresponding to @p fe2, this
-   * function is simply an identity
-   * mapping.
+   * Gives the interpolation of the @p fe1-function @p u1 to a @p
+   * fe2-function, and interpolates this to a second @p fe1-function named @p
+   * u1_interpolated.
+   *
+   * Note, that this function does not work on continuous elements at hanging
+   * nodes. For that case use the @p back_interpolate function, below, that
+   * takes an additional @p ConstraintMatrix object.
+   *
+   * Furthermore note, that for the specific case when the finite element
+   * space corresponding to @p fe1 is a subset of the finite element space
+   * corresponding to @p fe2, this function is simply an identity mapping.
    */
   template <int dim, class InVector, class OutVector, int spacedim>
   void back_interpolate (const DoFHandler<dim,spacedim>    &dof1,
@@ -912,10 +606,8 @@ namespace FETools
                          OutVector                &u1_interpolated);
 
   /**
-   * Same as last function, except
-   * that the dof handler objects
-   * might be of type
-   * @p hp::DoFHandler.
+   * Same as last function, except that the dof handler objects might be of
+   * type @p hp::DoFHandler.
    */
   template <int dim,
            template <int> class DH,
@@ -926,31 +618,17 @@ namespace FETools
                          OutVector                &u1_interpolated);
 
   /**
-   * Gives the interpolation of the
-   * @p dof1-function @p u1 to a
-   * @p dof2-function, and
-   * interpolates this to a second
-   * @p dof1-function named
-   * @p u1_interpolated.
-   * @p constraints1 and
-   * @p constraints2 are the
-   * hanging node constraints
-   * corresponding to @p dof1 and
-   * @p dof2, respectively. These
-   * objects are particular
-   * important when continuous
-   * elements on grids with hanging
-   * nodes (locally refined grids)
-   * are involved.
-   *
-   * Furthermore note, that for the
-   * specific case when the finite
-   * element space corresponding to
-   * @p dof1 is a subset of the
-   * finite element space
-   * corresponding to @p dof2, this
-   * function is simply an identity
-   * mapping.
+   * Gives the interpolation of the @p dof1-function @p u1 to a @p
+   * dof2-function, and interpolates this to a second @p dof1-function named
+   * @p u1_interpolated.  @p constraints1 and @p constraints2 are the hanging
+   * node constraints corresponding to @p dof1 and @p dof2,
+   * respectively. These objects are particular important when continuous
+   * elements on grids with hanging nodes (locally refined grids) are
+   * involved.
+   *
+   * Furthermore note, that for the specific case when the finite element
+   * space corresponding to @p dof1 is a subset of the finite element space
+   * corresponding to @p dof2, this function is simply an identity mapping.
    */
   template <int dim, class InVector, class OutVector, int spacedim>
   void back_interpolate (const DoFHandler<dim,spacedim> &dof1,
@@ -961,20 +639,13 @@ namespace FETools
                          OutVector              &u1_interpolated);
 
   /**
-   * Gives $(Id-I_h)z_1$ for a given
-   * @p dof1-function $z_1$, where $I_h$
-   * is the interpolation from @p fe1
-   * to @p fe2. The result $(Id-I_h)z_1$ is
+   * Gives $(Id-I_h)z_1$ for a given @p dof1-function $z_1$, where $I_h$ is
+   * the interpolation from @p fe1 to @p fe2. The result $(Id-I_h)z_1$ is
    * written into @p z1_difference.
    *
-   * Note, that this function does
-   * not work for continuous
-   * elements at hanging nodes. For
-   * that case use the
-   * @p interpolation_difference
-   * function, below, that takes an
-   * additional
-   * @p ConstraintMatrix object.
+   * Note, that this function does not work for continuous elements at hanging
+   * nodes. For that case use the @p interpolation_difference function, below,
+   * that takes an additional @p ConstraintMatrix object.
    */
   template <int dim, class InVector, class OutVector, int spacedim>
   void interpolation_difference(const DoFHandler<dim,spacedim> &dof1,
@@ -983,21 +654,13 @@ namespace FETools
                                 OutVector &z1_difference);
 
   /**
-   * Gives $(Id-I_h)z_1$ for a given
-   * @p dof1-function $z_1$, where $I_h$
-   * is the interpolation from @p fe1
-   * to @p fe2. The result $(Id-I_h)z_1$ is
-   * written into @p z1_difference.
-   * @p constraints1 and
-   * @p constraints2 are the
-   * hanging node constraints
-   * corresponding to @p dof1 and
-   * @p dof2, respectively. These
-   * objects are particular
-   * important when continuous
-   * elements on grids with hanging
-   * nodes (locally refined grids)
-   * are involved.
+   * Gives $(Id-I_h)z_1$ for a given @p dof1-function $z_1$, where $I_h$ is
+   * the interpolation from @p fe1 to @p fe2. The result $(Id-I_h)z_1$ is
+   * written into @p z1_difference.  @p constraints1 and @p constraints2 are
+   * the hanging node constraints corresponding to @p dof1 and @p dof2,
+   * respectively. These objects are particular important when continuous
+   * elements on grids with hanging nodes (locally refined grids) are
+   * involved.
    *
    * For parallel computations with PETSc, supply @p z1 with ghost elements
    * and @p z1_difference without ghost elements.
@@ -1013,18 +676,12 @@ namespace FETools
 
 
   /**
-   * $L^2$ projection for
-   * discontinuous
-   * elements. Operates the same
-   * direction as interpolate.
-   *
-   * The global projection can be
-   * computed by local matrices if
-   * the finite element spaces are
-   * discontinuous. With continuous
-   * elements, this is impossible,
-   * since a global mass matrix
-   * must be inverted.
+   * $L^2$ projection for discontinuous elements. Operates the same direction
+   * as interpolate.
+   *
+   * The global projection can be computed by local matrices if the finite
+   * element spaces are discontinuous. With continuous elements, this is
+   * impossible, since a global mass matrix must be inverted.
    */
   template <int dim, class InVector, class OutVector, int spacedim>
   void project_dg (const DoFHandler<dim,spacedim> &dof1,
@@ -1033,39 +690,23 @@ namespace FETools
                    OutVector             &u2);
 
   /**
-   * Gives the patchwise
-   * extrapolation of a @p dof1
-   * function @p z1 to a @p dof2
-   * function @p z2.  @p dof1 and
-   * @p dof2 need to be DoFHandler
-   * based on the same triangulation.
-   *
-   * This function is interesting
-   * for e.g. extrapolating
-   * patchwise a piecewise linear
-   * solution to a piecewise
-   * quadratic solution.
-   *
-   * Note that the resulting field
-   * does not satisfy continuity
-   * requirements of the given
-   * finite elements.
-   *
-   * When you use continuous
-   * elements on grids with hanging
-   * nodes, please use the
-   * @p extrapolate function with
-   * an additional
-   * ConstraintMatrix argument,
+   * Gives the patchwise extrapolation of a @p dof1 function @p z1 to a @p
+   * dof2 function @p z2.  @p dof1 and @p dof2 need to be DoFHandler based on
+   * the same triangulation.
+   *
+   * This function is interesting for e.g. extrapolating patchwise a piecewise
+   * linear solution to a piecewise quadratic solution.
+   *
+   * Note that the resulting field does not satisfy continuity requirements of
+   * the given finite elements.
+   *
+   * When you use continuous elements on grids with hanging nodes, please use
+   * the @p extrapolate function with an additional ConstraintMatrix argument,
    * see below.
    *
-   * Since this function operates
-   * on patches of cells, it is
-   * required that the underlying
-   * grid is refined at least once
-   * for every coarse grid cell. If
-   * this is not the case, an
-   * exception will be raised.
+   * Since this function operates on patches of cells, it is required that the
+   * underlying grid is refined at least once for every coarse grid cell. If
+   * this is not the case, an exception will be raised.
    */
   template <int dim, class InVector, class OutVector, int spacedim>
   void extrapolate (const DoFHandler<dim,spacedim> &dof1,
@@ -1074,24 +715,14 @@ namespace FETools
                     OutVector             &z2);
 
   /**
-   * Gives the patchwise
-   * extrapolation of a @p dof1
-   * function @p z1 to a @p dof2
-   * function @p z2.  @p dof1 and
-   * @p dof2 need to be DoFHandler
-   * based on the same triangulation.
-   * @p constraints is a hanging
-   * node constraints object
-   * corresponding to
-   * @p dof2. This object is
-   * particular important when
-   * interpolating onto continuous
-   * elements on grids with hanging
-   * nodes (locally refined grids).
-   *
-   * Otherwise, the same holds as
-   * for the other @p extrapolate
-   * function.
+   * Gives the patchwise extrapolation of a @p dof1 function @p z1 to a @p
+   * dof2 function @p z2.  @p dof1 and @p dof2 need to be DoFHandler based on
+   * the same triangulation.  @p constraints is a hanging node constraints
+   * object corresponding to @p dof2. This object is particular important when
+   * interpolating onto continuous elements on grids with hanging nodes
+   * (locally refined grids).
+   *
+   * Otherwise, the same holds as for the other @p extrapolate function.
    */
   template <int dim, class InVector, class OutVector, int spacedim>
   void extrapolate (const DoFHandler<dim,spacedim> &dof1,
@@ -1101,54 +732,27 @@ namespace FETools
                     OutVector              &z2);
   //@}
   /**
-   * The numbering of the degrees
-   * of freedom in continuous finite
-   * elements is hierarchic,
-   * i.e. in such a way that we
-   * first number the vertex dofs,
-   * in the order of the vertices
-   * as defined by the
-   * triangulation, then the line
-   * dofs in the order and
-   * respecting the direction of
-   * the lines, then the dofs on
-   * quads, etc. However, we could
-   * have, as well, numbered them
-   * in a lexicographic way,
-   * i.e. with indices first
-   * running in x-direction, then
-   * in y-direction and finally in
-   * z-direction. Discontinuous
-   * elements of class FE_DGQ()
-   * are numbered in this way, for
-   * example.
-   *
-   * This function constructs a
-   * table which lexicographic
-   * index each degree of freedom
-   * in the hierarchic numbering
-   * would have. It operates on the
-   * continuous finite element
-   * given as first argument, and
-   * outputs the lexicographic
-   * indices in the second.
-   *
-   * Note that since this function
-   * uses specifics of the
-   * continuous finite elements, it
-   * can only operate on
-   * FiniteElementData<dim> objects
-   * inherent in FE_Q(). However,
-   * this function does not take a
-   * FE_Q object as it is also
-   * invoked by the FE_Q()
-   * constructor.
-   *
-   * It is assumed that the size of
-   * the output argument already
-   * matches the correct size,
-   * which is equal to the number
-   * of degrees of freedom in the
+   * The numbering of the degrees of freedom in continuous finite elements is
+   * hierarchic, i.e. in such a way that we first number the vertex dofs, in
+   * the order of the vertices as defined by the triangulation, then the line
+   * dofs in the order and respecting the direction of the lines, then the
+   * dofs on quads, etc. However, we could have, as well, numbered them in a
+   * lexicographic way, i.e. with indices first running in x-direction, then
+   * in y-direction and finally in z-direction. Discontinuous elements of
+   * class FE_DGQ() are numbered in this way, for example.
+   *
+   * This function constructs a table which lexicographic index each degree of
+   * freedom in the hierarchic numbering would have. It operates on the
+   * continuous finite element given as first argument, and outputs the
+   * lexicographic indices in the second.
+   *
+   * Note that since this function uses specifics of the continuous finite
+   * elements, it can only operate on FiniteElementData<dim> objects inherent
+   * in FE_Q(). However, this function does not take a FE_Q object as it is
+   * also invoked by the FE_Q() constructor.
+   *
+   * It is assumed that the size of the output argument already matches the
+   * correct size, which is equal to the number of degrees of freedom in the
    * finite element.
    */
   template <int dim>
@@ -1157,23 +761,17 @@ namespace FETools
                                          std::vector<unsigned int>    &h2l);
 
   /**
-   * Like the previous function but
-   * instead of returning its
-   * result through the last
-   * argument return it as a value.
+   * Like the previous function but instead of returning its result through
+   * the last argument return it as a value.
    */
   template <int dim>
   std::vector<unsigned int>
   hierarchic_to_lexicographic_numbering (const FiniteElementData<dim> &fe_data);
 
   /**
-   * This is the reverse function
-   * to the above one, generating
-   * the map from the lexicographic
-   * to the hierarchical
-   * numbering. All the remarks
-   * made about the above function
-   * are also valid here.
+   * This is the reverse function to the above one, generating the map from
+   * the lexicographic to the hierarchical numbering. All the remarks made
+   * about the above function are also valid here.
    */
   template <int dim>
   void
@@ -1181,75 +779,44 @@ namespace FETools
                                          std::vector<unsigned int>    &l2h);
 
   /**
-   * Like the previous function but
-   * instead of returning its
-   * result through the last
-   * argument return it as a value.
+   * Like the previous function but instead of returning its result through
+   * the last argument return it as a value.
    */
   template <int dim>
   std::vector<unsigned int>
   lexicographic_to_hierarchic_numbering (const FiniteElementData<dim> &fe_data);
 
   /**
-   * Parse the name of a finite
-   * element and generate a finite
-   * element object accordingly.
-   *
-   * The name must be in the form which
-   * is returned by the
-   * FiniteElement::get_name
-   * function, where a few
-   * modifications are allowed:
-   *
-   * <ul><li> Dimension template
-   * parameters &lt;2&gt; etc. can
-   * be omitted. Alternatively, the
-   * explicit number can be
-   * replaced by <tt>dim</tt> or
-   * <tt>d</tt>. If a number is
-   * given, it <b>must</b> match
-   * the template parameter of this
-   * function.
+   * Parse the name of a finite element and generate a finite element object
+   * accordingly.
    *
-   * <li> The powers used for
-   * FESystem may either be numbers
-   * or can be
-   * replaced by <tt>dim</tt> or
-   * <tt>d</tt>.
-   * </ul>
-   *
-   * If no finite element can be
-   * reconstructed from this
-   * string, an exception of type
-   * @p FETools::ExcInvalidFEName
-   * is thrown.
-   *
-   * The function returns a pointer
-   * to a newly create finite
-   * element. It is in the caller's
-   * responsibility to destroy the
-   * object pointed to at an
+   * The name must be in the form which is returned by the
+   * FiniteElement::get_name function, where a few modifications are allowed:
+   *
+   * <ul><li> Dimension template parameters &lt;2&gt; etc. can be
+   * omitted. Alternatively, the explicit number can be replaced by
+   * <tt>dim</tt> or <tt>d</tt>. If a number is given, it <b>must</b> match
+   * the template parameter of this function.
+   *
+   * <li> The powers used for FESystem may either be numbers or can be
+   * replaced by <tt>dim</tt> or <tt>d</tt>.  </ul>
+   *
+   * If no finite element can be reconstructed from this string, an exception
+   * of type @p FETools::ExcInvalidFEName is thrown.
+   *
+   * The function returns a pointer to a newly create finite element. It is in
+   * the caller's responsibility to destroy the object pointed to at an
    * appropriate later time.
    *
-   * Since the value of the template
-   * argument can't be deduced from the
-   * (string) argument given to this
-   * function, you have to explicitly
-   * specify it when you call this
-   * function.
+   * Since the value of the template argument can't be deduced from the
+   * (string) argument given to this function, you have to explicitly specify
+   * it when you call this function.
    *
-   * This function knows about all
-   * the standard elements defined
-   * in the library. However, it
-   * doesn't by default know about
-   * elements that you may have
-   * defined in your program. To
-   * make your own elements known
-   * to this function, use the
-   * add_fe_name() function.
-   * This function does not work
-   * if one wants to get a codimension
-   * 1 finite element.
+   * This function knows about all the standard elements defined in the
+   * library. However, it doesn't by default know about elements that you may
+   * have defined in your program. To make your own elements known to this
+   * function, use the add_fe_name() function.  This function does not work if
+   * one wants to get a codimension 1 finite element.
    */
   template <int dim>
   FiniteElement<dim, dim> *
@@ -1257,102 +824,57 @@ namespace FETools
 
 
   /**
-   * Extend the list of finite
-   * elements that can be generated
-   * by get_fe_from_name() by the
-   * one given as @p name. If
-   * get_fe_from_name() is later
-   * called with this name, it will
-   * use the object given as second
-   * argument to create a finite
-   * element object.
-   *
-   * The format of the @p name
-   * parameter should include the
-   * name of a finite
-   * element. However, it is safe
-   * to use either the class name
-   * alone or to use the result of
-   * FiniteElement::get_name (which
-   * includes the space dimension
-   * as well as the polynomial
-   * degree), since everything
-   * after the first non-name
-   * character will be ignored.
-   *
-   * The FEFactory object should be
-   * an object newly created with
-   * <tt>new</tt>. FETools will
-   * take ownership of this object
-   * and delete it once it is not
-   * used anymore.
-   *
-   * In most cases, if you want
-   * objects of type
-   * <code>MyFE</code> be created
-   * whenever the name
-   * <code>my_fe</code> is given to
-   * get_fe_from_name, you will
-   * want the second argument to
-   * this function be of type
-   * FEFactory@<MyFE@>, but you can
-   * of course create your custom
-   * finite element factory class.
-   *
-   * This function takes over
-   * ownership of the object given
-   * as second argument, i.e. you
-   * should never attempt to
-   * destroy it later on. The
-   * object will be deleted at the
-   * end of the program's lifetime.
-   *
-   * If the name of the element
-   * is already in use, an exception
-   * is thrown. Thus, functionality
-   * of get_fe_from_name() can only
-   * be added, not changed.
-   *
-   * @note This function
-   * manipulates a global table
-   * (one table for each space
-   * dimension). It is thread safe
-   * in the sense that every access
-   * to this table is secured by a
-   * lock. Nevertheless, since each
-   * name can be added only once,
-   * user code has to make sure
-   * that only one thread adds a
-   * new element.
-   *
-   * Note also that this table
-   * exists once for each space
-   * dimension. If you have a
-   * program that works with finite
-   * elements in different space
-   * dimensions (for example, @ref
-   * step_4 "step-4" does something
-   * like this), then you should
-   * call this function for each
-   * space dimension for which you
-   * want your finite element added
-   * to the map.
+   * Extend the list of finite elements that can be generated by
+   * get_fe_from_name() by the one given as @p name. If get_fe_from_name() is
+   * later called with this name, it will use the object given as second
+   * argument to create a finite element object.
+   *
+   * The format of the @p name parameter should include the name of a finite
+   * element. However, it is safe to use either the class name alone or to use
+   * the result of FiniteElement::get_name (which includes the space dimension
+   * as well as the polynomial degree), since everything after the first
+   * non-name character will be ignored.
+   *
+   * The FEFactory object should be an object newly created with
+   * <tt>new</tt>. FETools will take ownership of this object and delete it
+   * once it is not used anymore.
+   *
+   * In most cases, if you want objects of type <code>MyFE</code> be created
+   * whenever the name <code>my_fe</code> is given to get_fe_from_name, you
+   * will want the second argument to this function be of type
+   * FEFactory@<MyFE@>, but you can of course create your custom finite
+   * element factory class.
+   *
+   * This function takes over ownership of the object given as second
+   * argument, i.e. you should never attempt to destroy it later on. The
+   * object will be deleted at the end of the program's lifetime.
+   *
+   * If the name of the element is already in use, an exception is
+   * thrown. Thus, functionality of get_fe_from_name() can only be added, not
+   * changed.
+   *
+   * @note This function manipulates a global table (one table for each space
+   * dimension). It is thread safe in the sense that every access to this
+   * table is secured by a lock. Nevertheless, since each name can be added
+   * only once, user code has to make sure that only one thread adds a new
+   * element.
+   *
+   * Note also that this table exists once for each space dimension. If you
+   * have a program that works with finite elements in different space
+   * dimensions (for example, @ref step_4 "step-4" does something like this),
+   * then you should call this function for each space dimension for which you
+   * want your finite element added to the map.
    */
   template <int dim, int spacedim>
   void add_fe_name (const std::string &name,
                     const FEFactoryBase<dim,spacedim> *factory);
 
   /**
-   * The string used for
-   * get_fe_from_name() cannot be
-   * translated to a finite
+   * The string used for get_fe_from_name() cannot be translated to a finite
    * element.
    *
-   * Either the string is badly
-   * formatted or you are using a
-   * custom element that must be
-   * added using add_fe_name()
-   * first.
+   * Either the string is badly formatted or you are using a custom element
+   * that must be added using add_fe_name() first.
    *
    * @ingroup Exceptions
    */
@@ -1362,21 +884,13 @@ namespace FETools
                   << arg1 << "'.");
 
   /**
-   * The string used for
-   * get_fe_from_name() cannot be
-   * translated to a finite
+   * The string used for get_fe_from_name() cannot be translated to a finite
    * element.
    *
-   * Dimension arguments in finite
-   * element names should be
-   * avoided. If they are there,
-   * the dimension should be
-   * <tt>dim</tt> or
-   * <tt>d</tt>. Here, you gave a
-   * numeric dimension argument,
-   * which does not match the
-   * template dimension of the
-   * finite element class.
+   * Dimension arguments in finite element names should be avoided. If they
+   * are there, the dimension should be <tt>dim</tt> or <tt>d</tt>. Here, you
+   * gave a numeric dimension argument, which does not match the template
+   * dimension of the finite element class.
    *
    * @ingroup Exceptions
    */
@@ -1395,8 +909,7 @@ namespace FETools
   DeclException0 (ExcInvalidFE);
 
   /**
-   * The finite element must be
-   * @ref GlossPrimitive "primitive".
+   * The finite element must be @ref GlossPrimitive "primitive".
    *
    * @ingroup Exceptions
    */
@@ -1409,10 +922,8 @@ namespace FETools
   DeclException0 (ExcTriangulationMismatch);
 
   /**
-   * A continuous element is used
-   * on a mesh with hanging nodes,
-   * but the constraint matrices
-   * are missing.
+   * A continuous element is used on a mesh with hanging nodes, but the
+   * constraint matrices are missing.
    *
    * @ingroup Exceptions
    */
@@ -1430,9 +941,7 @@ namespace FETools
    */
   DeclException0 (ExcGridNotRefinedAtLeastOnce);
   /**
-   * The dimensions of the matrix
-   * used did not match the
-   * expected dimensions.
+   * The dimensions of the matrix used did not match the expected dimensions.
    *
    * @ingroup Exceptions
    */
@@ -1442,9 +951,7 @@ namespace FETools
                   << "but should be a " << arg3 << "x" << arg4 << " matrix.");
 
   /**
-   * Exception thrown if an
-   * embedding matrix was computed
-   * inaccurately.
+   * Exception thrown if an embedding matrix was computed inaccurately.
    *
    * @ingroup Exceptions
    */
@@ -1452,8 +959,7 @@ namespace FETools
                  << "Least squares fit leaves a gap of " << arg1);
 
   /**
-   * Exception thrown if one variable
-   * may not be greater than another.
+   * Exception thrown if one variable may not be greater than another.
    *
    * @ingroup Exceptions
    */

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.