]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
reformat documentation to longer lines
authorkanschat <kanschat@0785d39b-7218-0410-832d-ea1e28bc413d>
Wed, 6 Nov 2013 10:25:28 +0000 (10:25 +0000)
committerkanschat <kanschat@0785d39b-7218-0410-832d-ea1e28bc413d>
Wed, 6 Nov 2013 10:25:28 +0000 (10:25 +0000)
git-svn-id: https://svn.dealii.org/trunk@31560 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/include/deal.II/dofs/dof_tools.h

index 9b391971049b0a8f283b4c85802e73f4060a83b2..f1a02d0fe92e465d98a230ad94ed2fe3aa7d0ad9 100644 (file)
@@ -185,28 +185,22 @@ namespace GridTools {template <typename CellIterator> struct PeriodicFacePair;}
 namespace DoFTools
 {
   /**
-   * The flags used in tables by certain
-   * <tt>make_*_pattern</tt> functions to
-   * describe whether two components of the
-   * solution couple in the bilinear forms
-   * corresponding to cell or face
-   * terms. An example of using these flags
-   * is shown in the introduction of
-   * step-46.
-   *
-   * In the descriptions of the individual
-   * elements below, remember that these
-   * flags are used as elements of tables
-   * of size FiniteElement::n_components
-   * times FiniteElement::n_components
-   * where each element indicates whether
-   * two components do or do not couple.
+   * The flags used in tables by certain <tt>make_*_pattern</tt>
+   * functions to describe whether two components of the solution
+   * couple in the bilinear forms corresponding to cell or face
+   * terms. An example of using these flags is shown in the
+   * introduction of step-46.
+   *
+   * In the descriptions of the individual elements below, remember
+   * that these flags are used as elements of tables of size
+   * FiniteElement::n_components times FiniteElement::n_components
+   * where each element indicates whether two components do or do not
+   * couple.
    */
   enum Coupling
   {
     /**
-     * Two components do not
-     * couple.
+     * Two components do not couple.
      */
     none,
     /**
@@ -214,12 +208,9 @@ namespace DoFTools
      */
     always,
     /**
-     * Two components couple only
-     * if their shape functions are
-     * both nonzero on a given
-     * face. This flag is only used
-     * when computing integrals over
-     * faces of cells.
+     * Two components couple only if their shape functions are both
+     * nonzero on a given face. This flag is only used when computing
+     * integrals over faces of cells.
      */
     nonzero
   };
@@ -229,8 +220,7 @@ namespace DoFTools
    * @{
    */
   /**
-   * Maximal number of degrees of
-   * freedom on a cell.
+   * Maximal number of degrees of freedom on a cell.
    *
    * @relates DoFHandler
    */
@@ -239,8 +229,7 @@ namespace DoFTools
   max_dofs_per_cell (const DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Maximal number of degrees of
-   * freedom on a cell.
+   * Maximal number of degrees of freedom on a cell.
    *
    * @relates hp::DoFHandler
    */
@@ -250,13 +239,10 @@ namespace DoFTools
 
 
   /**
-   * Maximal number of degrees of
-   * freedom on a face.
+   * Maximal number of degrees of freedom on a face.
    *
-   * This function exists for both non-hp
-   * and hp DoFHandlers, to allow for a
-   * uniform interface to query this
-   * property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow
+   * for a uniform interface to query this property.
    *
    * @relates DoFHandler
    */
@@ -265,13 +251,10 @@ namespace DoFTools
   max_dofs_per_face (const DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Maximal number of degrees of
-   * freedom on a face.
+   * Maximal number of degrees of freedom on a face.
    *
-   * This function exists for both non-hp
-   * and hp DoFHandlers, to allow for a
-   * uniform interface to query this
-   * property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow
+   * for a uniform interface to query this property.
    *
    * @relates hp::DoFHandler
    */
@@ -280,13 +263,10 @@ namespace DoFTools
   max_dofs_per_face (const hp::DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Maximal number of degrees of
-   * freedom on a vertex.
+   * Maximal number of degrees of freedom on a vertex.
    *
-   * This function exists for both non-hp
-   * and hp DoFHandlers, to allow for a
-   * uniform interface to query this
-   * property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow
+   * for a uniform interface to query this property.
    *
    * @relates DoFHandler
    */
@@ -295,13 +275,10 @@ namespace DoFTools
   max_dofs_per_vertex (const DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Maximal number of degrees of
-   * freedom on a vertex.
+   * Maximal number of degrees of freedom on a vertex.
    *
-   * This function exists for both non-hp
-   * and hp DoFHandlers, to allow for a
-   * uniform interface to query this
-   * property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow
+   * for a uniform interface to query this property.
    *
    * @relates hp::DoFHandler
    */
@@ -310,14 +287,11 @@ namespace DoFTools
   max_dofs_per_vertex (const hp::DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Number of vector components in the
-   * finite element object used by this
-   * DoFHandler.
+   * Number of vector components in the finite element object used by
+   * this DoFHandler.
    *
-   * This function exists for both non-hp
-   * and hp DoFHandlers, to allow for a
-   * uniform interface to query this
-   * property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow
+   * for a uniform interface to query this property.
    *
    * @relates DoFHandler
    */
@@ -326,14 +300,11 @@ namespace DoFTools
   n_components (const DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Number of vector components in the
-   * finite element object used by this
-   * DoFHandler.
+   * Number of vector components in the finite element object used by
+   * this DoFHandler.
    *
-   * This function exists for both non-hp
-   * and hp DoFHandlers, to allow for a
-   * uniform interface to query this
-   * property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow
+   * for a uniform interface to query this property.
    *
    * @relates hp::DoFHandler
    */
@@ -342,14 +313,11 @@ namespace DoFTools
   n_components (const hp::DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Find out whether the FiniteElement
-   * used by this DoFHandler is primitive
-   * or not.
+   * Find out whether the FiniteElement used by this DoFHandler is
+   * primitive or not.
    *
-   * This function exists for both non-hp
-   * and hp DoFHandlers, to allow for a
-   * uniform interface to query this
-   * property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow
+   * for a uniform interface to query this property.
    *
    * @relates DoFHandler
    */
@@ -358,14 +326,11 @@ namespace DoFTools
   fe_is_primitive (const DoFHandler<dim,spacedim> &dh);
 
   /**
-   * Find out whether the FiniteElement
-   * used by this DoFHandler is primitive
-   * or not.
+   * Find out whether the FiniteElement used by this DoFHandler is
+   * primitive or not.
    *
-   * This function exists for both non-hp
-   * and hp DoFHandlers, to allow for a
-   * uniform interface to query this
-   * property.
+   * This function exists for both non-hp and hp DoFHandlers, to allow
+   * for a uniform interface to query this property.
    *
    * @relates hp::DoFHandler
    */
@@ -383,117 +348,65 @@ namespace DoFTools
    */
 
   /**
-   * Locate non-zero entries of the
-   * system matrix.
-   *
-   * This function computes the
-   * possible positions of non-zero
-   * entries in the global system
-   * matrix. We assume that a
-   * certain finite element basis
-   * function is non-zero on a cell
-   * only if its degree of freedom
-   * is associated with the
-   * interior, a face, an edge or a
-   * vertex of this cell. As a
-   * result, the matrix entry
-   * between two basis functions
-   * can be non-zero only if they
-   * correspond to degrees of
-   * freedom of at least one common
-   * cell. Therefore,
-   * @p make_sparsity_pattern just
-   * loops over all cells and
-   * enters all couplings local to
-   * that cell. As the generation
-   * of the sparsity pattern is
-   * irrespective of the equation
-   * which is solved later on, the
-   * resulting sparsity pattern is
-   * symmetric.
-   *
-   * Remember using
-   * SparsityPattern::compress()
-   * after generating the pattern.
-   *
-   * The actual type of the
-   * sparsity pattern may be
-   * SparsityPattern,
-   * CompressedSparsityPattern,
-   * BlockSparsityPattern,
+   * Locate non-zero entries of the system matrix.
+   *
+   * This function computes the possible positions of non-zero entries
+   * in the global system matrix. We assume that a certain finite
+   * element basis function is non-zero on a cell only if its degree
+   * of freedom is associated with the interior, a face, an edge or a
+   * vertex of this cell. As a result, the matrix entry between two
+   * basis functions can be non-zero only if they correspond to
+   * degrees of freedom of at least one common cell. Therefore, @p
+   * make_sparsity_pattern just loops over all cells and enters all
+   * couplings local to that cell. As the generation of the sparsity
+   * pattern is irrespective of the equation which is solved later on,
+   * the resulting sparsity pattern is symmetric.
+   *
+   * Remember using SparsityPattern::compress() after generating the
+   * pattern.
+   *
+   * The actual type of the sparsity pattern may be SparsityPattern,
+   * CompressedSparsityPattern, BlockSparsityPattern,
    * BlockCompressedSparsityPattern,
    * BlockCompressedSetSparsityPattern,
-   * BlockCompressedSimpleSparsityPattern,
-   * or any other class that
-   * satisfies similar
-   * requirements. It is assumed
-   * that the size of the sparsity
-   * pattern matches the number of
-   * degrees of freedom and that
-   * enough unused nonzero entries
-   * are left to fill the sparsity
-   * pattern. The nonzero entries
-   * generated by this function are
-   * overlaid to possible previous
-   * content of the object, that is
-   * previously added entries are
-   * not deleted.
-   *
-   * Since this process is purely local,
-   * the sparsity pattern does not provide
-   * for entries introduced by the
-   * elimination of hanging nodes. They
-   * have to be taken care of by a call to
-   * ConstraintMatrix::condense()
-   * afterwards.
-   *
-   * Alternatively, the constraints on
-   * degrees of freedom can already be
-   * taken into account at the time of
-   * creating the sparsity pattern. For
-   * this, pass the ConstraintMatrix object
-   * as the third argument to the current
-   * function. No call to
-   * ConstraintMatrix::condense() is then
-   * necessary. This process is explained
-   * in step-27.
-   *
-   * In case the constraints are
-   * already taken care of in this
-   * function, it is possible to
-   * neglect off-diagonal entries
-   * in the sparsity pattern. When
-   * using
-   * ConstraintMatrix::distribute_local_to_global
-   * during assembling, no entries
-   * will ever be written into
-   * these matrix position, so that
-   * one can save some computing
-   * time in matrix-vector products
-   * by not even creating these
-   * elements. In that case, the
-   * variable
-   * <tt>keep_constrained_dofs</tt>
-   * needs to be set to
-   * <tt>false</tt>.
-   *
-   * If the @p subdomain_id parameter is
-   * given, the sparsity pattern is built
-   * only on cells that have a subdomain_id
-   * equal to the given argument. This is
-   * useful in parallel contexts where the
-   * matrix and sparsity pattern (for
-   * example a
-   * TrilinosWrappers::SparsityPattern) may
-   * be distributed and not every MPI
-   * process needs to build the entire
-   * sparsity pattern; in that case, it is
-   * sufficient if every process only
-   * builds that part of the sparsity
-   * pattern that corresponds to the
-   * subdomain_id for which it is
-   * responsible. This feature is
-   * used in step-32.
+   * BlockCompressedSimpleSparsityPattern, or any other class that
+   * satisfies similar requirements. It is assumed that the size of
+   * the sparsity pattern matches the number of degrees of freedom and
+   * that enough unused nonzero entries are left to fill the sparsity
+   * pattern. The nonzero entries generated by this function are
+   * overlaid to possible previous content of the object, that is
+   * previously added entries are not deleted.
+   *
+   * Since this process is purely local, the sparsity pattern does not
+   * provide for entries introduced by the elimination of hanging
+   * nodes. They have to be taken care of by a call to
+   * ConstraintMatrix::condense() afterwards.
+   *
+   * Alternatively, the constraints on degrees of freedom can already
+   * be taken into account at the time of creating the sparsity
+   * pattern. For this, pass the ConstraintMatrix object as the third
+   * argument to the current function. No call to
+   * ConstraintMatrix::condense() is then necessary. This process is
+   * explained in step-27.
+   *
+   * In case the constraints are already taken care of in this
+   * function, it is possible to neglect off-diagonal entries in the
+   * sparsity pattern. When using
+   * ConstraintMatrix::distribute_local_to_global during assembling,
+   * no entries will ever be written into these matrix position, so
+   * that one can save some computing time in matrix-vector products
+   * by not even creating these elements. In that case, the variable
+   * <tt>keep_constrained_dofs</tt> needs to be set to <tt>false</tt>.
+   *
+   * If the @p subdomain_id parameter is given, the sparsity pattern
+   * is built only on cells that have a subdomain_id equal to the
+   * given argument. This is useful in parallel contexts where the
+   * matrix and sparsity pattern (for example a
+   * TrilinosWrappers::SparsityPattern) may be distributed and not
+   * every MPI process needs to build the entire sparsity pattern; in
+   * that case, it is sufficient if every process only builds that
+   * part of the sparsity pattern that corresponds to the subdomain_id
+   * for which it is responsible. This feature is used in step-32.
    *
    * @ingroup constraints
    */
@@ -506,30 +419,22 @@ namespace DoFTools
                          const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
 
   /**
-   * Locate non-zero entries for
-   * vector valued finite elements.
-   * This function does mostly the
-   * same as the previous
-   * @p make_sparsity_pattern, but
-   * it is specialized for vector
-   * finite elements and allows to
-   * specify which variables couple
-   * in which equation. For
-   * example, if wanted to solve
-   * the Stokes equations,
+   * Locate non-zero entries for vector valued finite elements.  This
+   * function does mostly the same as the previous
+   * make_sparsity_pattern(), but it is specialized for vector finite
+   * elements and allows to specify which variables couple in which
+   * equation. For example, if wanted to solve the Stokes equations,
+   *
    * @f{align*}
    * -\Delta \mathbf u + \nabla p &= 0,\\
    * \text{div}\ u                    &= 0
    * @f}
-   * in two space dimensions,
-   * using stable Q2/Q1 mixed
-   * elements (using the FESystem
-   * class), then you don't want
-   * all degrees of freedom to
-   * couple in each equation. You
-   * rather may want to give the
-   * following pattern of
-   * couplings:
+   *
+   * in two space dimensions, using stable Q2/Q1 mixed elements (using
+   * the FESystem class), then you don't want all degrees of freedom
+   * to couple in each equation. You rather may want to give the
+   * following pattern of couplings:
+   *
    * @f[
    * \left[
    * \begin{array}{ccc}
@@ -539,122 +444,67 @@ namespace DoFTools
    * \end{array}
    * \right]
    * @f]
-   * where "1" indicates that two
-   * variables (i.e. components of
-   * the FESystem) couple in the
-   * respective equation, and a "0"
-   * means no coupling, in which
-   * case it is not necessary to
-   * allocate space in the matrix
-   * structure. Obviously, the mask
-   * refers to components of the
-   * composed FESystem, rather
-   * than to the degrees of freedom
+   *
+   * where "1" indicates that two variables (i.e. components of the
+   * FESystem) couple in the respective equation, and a "0" means no
+   * coupling, in which case it is not necessary to allocate space in
+   * the matrix structure. Obviously, the mask refers to components of
+   * the composed FESystem, rather than to the degrees of freedom
    * contained in there.
    *
-   * This function is designed to
-   * accept a coupling pattern, like the one
-   * shown above, through the
-   * @p couplings parameter, which
-   * contains values of type #Coupling. It
-   * builds the matrix structure
-   * just like the previous
-   * function, but does not create
-   * matrix elements if not
-   * specified by the coupling pattern. If the
-   * couplings are symmetric, then so
-   * will be the resulting sparsity
+   * This function is designed to accept a coupling pattern, like the
+   * one shown above, through the @p couplings parameter, which
+   * contains values of type #Coupling. It builds the matrix structure
+   * just like the previous function, but does not create matrix
+   * elements if not specified by the coupling pattern. If the
+   * couplings are symmetric, then so will be the resulting sparsity
    * pattern.
    *
-   * The actual type of the
-   * sparsity pattern may be
-   * SparsityPattern,
-   * CompressedSparsityPattern,
-   * BlockSparsityPattern,
+   * The actual type of the sparsity pattern may be SparsityPattern,
+   * CompressedSparsityPattern, BlockSparsityPattern,
    * BlockCompressedSparsityPattern,
-   * BlockCompressedSetSparsityPattern,
-   * or any other class that
-   * satisfies similar
-   * requirements.
-   *
-   * There is a complication if
-   * some or all of the shape
-   * functions of the finite
-   * element in use are non-zero in
-   * more than one component (in
-   * deal.II speak: they are
-   * non-primitive). In this case,
-   * the coupling element
-   * correspoding to the first
-   * non-zero component is taken
-   * and additional ones for this
-   * component are ignored.
-   *
-   * Not implemented for
-   * hp::DoFHandler.
+   * BlockCompressedSetSparsityPattern, or any other class that
+   * satisfies similar requirements.
+   *
+   * There is a complication if some or all of the shape functions of
+   * the finite element in use are non-zero in more than one component
+   * (in deal.II speak: they are non-primitive). In this case, the
+   * coupling element correspoding to the first non-zero component is
+   * taken and additional ones for this component are ignored.
    *
-   * As mentioned before, the
-   * creation of the sparsity
-   * pattern is a purely local
-   * process and the sparsity
-   * pattern does not provide for
-   * entries introduced by the
-   * elimination of hanging
-   * nodes. They have to be taken
-   * care of by a call to
-   * ConstraintMatrix::condense()
-   * afterwards.
-   *
-   * Alternatively, the constraints
-   * on degrees of freedom can
-   * already be taken into account
-   * at the time of creating the
-   * sparsity pattern. For this,
-   * pass the ConstraintMatrix
-   * object as the third argument
-   * to the current function. No
-   * call to
-   * ConstraintMatrix::condense()
-   * is then necessary. This
-   * process is explained in @ref
-   * step_27 "step-27".
-   *
-   * In case the constraints are
-   * already taken care of in this
-   * function, it is possible to
-   * neglect off-diagonal entries
-   * in the sparsity pattern. When
-   * using
-   * ConstraintMatrix::distribute_local_to_global
-   * during assembling, no entries
-   * will ever be written into
-   * these matrix position, so that
-   * one can save some computing
-   * time in matrix-vector products
-   * by not even creating these
-   * elements. In that case, the
-   * variable
-   * <tt>keep_constrained_dofs</tt>
-   * needs to be set to
-   * <tt>false</tt>.
-   *
-   * If the @p subdomain_id parameter is
-   * given, the sparsity pattern is built
-   * only on cells that have a subdomain_id
-   * equal to the given argument. This is
-   * useful in parallel contexts where the
-   * matrix and sparsity pattern (for
-   * example a
-   * TrilinosWrappers::SparsityPattern) may
-   * be distributed and not every MPI
-   * process needs to build the entire
-   * sparsity pattern; in that case, it is
-   * sufficient if every process only
-   * builds that part of the sparsity
-   * pattern that corresponds to the
-   * subdomain_id for which it is
-   * responsible. This feature is
-   * used in step-32.
+   * @todo Not implemented for hp::DoFHandler.
+   *
+   * As mentioned before, the creation of the sparsity pattern is a
+   * purely local process and the sparsity pattern does not provide
+   * for entries introduced by the elimination of hanging nodes. They
+   * have to be taken care of by a call to
+   * ConstraintMatrix::condense() afterwards.
+   *
+   * Alternatively, the constraints on degrees of freedom can already
+   * be taken into account at the time of creating the sparsity
+   * pattern. For this, pass the ConstraintMatrix object as the third
+   * argument to the current function. No call to
+   * ConstraintMatrix::condense() is then necessary. This process is
+   * explained in @ref step_27 "step-27".
+   *
+   * In case the constraints are already taken care of in this
+   * function, it is possible to neglect off-diagonal entries in the
+   * sparsity pattern. When using
+   * ConstraintMatrix::distribute_local_to_global during assembling,
+   * no entries will ever be written into these matrix position, so
+   * that one can save some computing time in matrix-vector products
+   * by not even creating these elements. In that case, the variable
+   * <tt>keep_constrained_dofs</tt> needs to be set to <tt>false</tt>.
+   *
+   * If the @p subdomain_id parameter is given, the sparsity pattern
+   * is built only on cells that have a subdomain_id equal to the
+   * given argument. This is useful in parallel contexts where the
+   * matrix and sparsity pattern (for example a
+   * TrilinosWrappers::SparsityPattern) may be distributed and not
+   * every MPI process needs to build the entire sparsity pattern; in
+   * that case, it is sufficient if every process only builds that
+   * part of the sparsity pattern that corresponds to the subdomain_id
+   * for which it is responsible. This feature is used in step-32.
    *
    * @ingroup constraints
    */
@@ -668,15 +518,10 @@ namespace DoFTools
                          const types::subdomain_id subdomain_id = numbers::invalid_subdomain_id);
 
   /**
-   * @deprecated This is the old
-   * form of the previous
-   * function. It generates a table
-   * of DoFTools::Coupling values
-   * (where a <code>true</code>
-   * value in the mask is
-   * translated into a
-   * Coupling::always value in the
-   * table) and calls the function
+   * @deprecated This is the old form of the previous function. It
+   * generates a table of DoFTools::Coupling values (where a
+   * <code>true</code> value in the mask is translated into a
+   * Coupling::always value in the table) and calls the function
    * above.
    */
   template <class DH, class SparsityPattern>
@@ -686,37 +531,25 @@ namespace DoFTools
                          SparsityPattern                       &sparsity_pattern) DEAL_II_DEPRECATED;
 
   /**
-   * Construct a sparsity pattern that
-   * allows coupling degrees of freedom on
-   * two different but related meshes.
-   *
-   * The idea is that if the two given
-   * DoFHandler objects correspond to two
-   * different meshes (and potentially to
-   * different finite elements used on
-   * these cells), but that if the two
-   * triangulations they are based on are
-   * derived from the same coarse mesh
-   * through hierarchical refinement, then
-   * one may set up a problem where one
-   * would like to test shape functions
-   * from one mesh against the shape
-   * functions from another mesh. In
-   * particular, this means that shape
-   * functions from a cell on the first
-   * mesh are tested against those on the
-   * second cell that are located on the
-   * corresponding cell; this
-   * correspondence is something that the
-   * IntergridMap class can determine.
-   *
-   * This function then constructs a
-   * sparsity pattern for which the degrees
-   * of freedom that represent the rows
-   * come from the first given DoFHandler,
-   * whereas the ones that correspond to
-   * columns come from the second
-   * DoFHandler.
+   * Construct a sparsity pattern that allows coupling degrees of
+   * freedom on two different but related meshes.
+   *
+   * The idea is that if the two given DoFHandler objects correspond
+   * to two different meshes (and potentially to different finite
+   * elements used on these cells), but that if the two triangulations
+   * they are based on are derived from the same coarse mesh through
+   * hierarchical refinement, then one may set up a problem where one
+   * would like to test shape functions from one mesh against the
+   * shape functions from another mesh. In particular, this means that
+   * shape functions from a cell on the first mesh are tested against
+   * those on the second cell that are located on the corresponding
+   * cell; this correspondence is something that the IntergridMap
+   * class can determine.
+   *
+   * This function then constructs a sparsity pattern for which the
+   * degrees of freedom that represent the rows come from the first
+   * given DoFHandler, whereas the ones that correspond to columns
+   * come from the second DoFHandler.
    */
   template <class DH, class SparsityPattern>
   void
@@ -725,21 +558,15 @@ namespace DoFTools
                          SparsityPattern &sparsity);
 
   /**
-   * Create the sparsity pattern for
-   * boundary matrices. See the general
-   * documentation of this class for more
-   * information.
+   * Create the sparsity pattern for boundary matrices. See the
+   * general documentation of this class for more information.
    *
-   * The actual type of the sparsity
-   * pattern may be SparsityPattern,
-   * CompressedSparsityPattern,
-   * BlockSparsityPattern,
+   * The actual type of the sparsity pattern may be SparsityPattern,
+   * CompressedSparsityPattern, BlockSparsityPattern,
    * BlockCompressedSparsityPattern,
-   * BlockCompressedSetSparsityPattern, or
-   * any other class that satisfies similar
-   * requirements. It is assumed that the
-   * size of the sparsity pattern is
-   * already correct.
+   * BlockCompressedSetSparsityPattern, or any other class that
+   * satisfies similar requirements. It is assumed that the size of
+   * the sparsity pattern is already correct.
    */
   template <class DH, class SparsityPattern>
   void
@@ -748,34 +575,22 @@ namespace DoFTools
                                   SparsityPattern                 &sparsity_pattern);
 
   /**
-   * Write the sparsity structure of the
-   * matrix composed of the basis functions
-   * on the boundary into the
-   * matrix structure. In contrast to the
-   * previous function, only those parts
-   * of the boundary are considered of which
-   * the boundary indicator is listed in the
-   * set of numbers passed to this function.
-   *
-   * In fact, rather than a @p set
-   * of boundary indicators, a
-   * @p map needs to be passed,
-   * since most of the functions
-   * handling with boundary
-   * indicators take a mapping of
-   * boundary indicators and the
-   * respective boundary
-   * functions. The boundary
-   * function, however, is ignored
-   * in this function.  If you have
-   * no functions at hand, but only
-   * the boundary indicators, set
-   * the function pointers to null
+   * Write the sparsity structure of the matrix composed of the basis
+   * functions on the boundary into the matrix structure. In contrast
+   * to the previous function, only those parts of the boundary are
+   * considered of which the boundary indicator is listed in the set
+   * of numbers passed to this function.
+   *
+   * In fact, rather than a @p set of boundary indicators, a @p map
+   * needs to be passed, since most of the functions handling with
+   * boundary indicators take a mapping of boundary indicators and the
+   * respective boundary functions. The boundary function, however, is
+   * ignored in this function.  If you have no functions at hand, but
+   * only the boundary indicators, set the function pointers to null
    * pointers.
    *
-   * For the type of the sparsity
-   * pattern, the same holds as
-   * said above.
+   * For the type of the sparsity pattern, the same holds as said
+   * above.
    */
   template <class DH, class SparsityPattern>
   void
@@ -785,20 +600,12 @@ namespace DoFTools
                                   SparsityPattern    &sparsity);
 
   /**
-   * Generate sparsity pattern for
-   * fluxes, i.e. formulations of
-   * the discrete problem with
-   * discontinuous elements which
-   * couple across faces of cells.
-   * This is a replacement of the
-   * function
-   * @p make_sparsity_pattern for
-   * discontinuous methods. Since
-   * the fluxes include couplings
-   * between neighboring elements,
-   * the normal couplings and these
-   * extra matrix entries are
-   * considered.
+   * Generate sparsity pattern for fluxes, i.e. formulations of the
+   * discrete problem with discontinuous elements which couple across
+   * faces of cells.  This is a replacement of the function @p
+   * make_sparsity_pattern for discontinuous methods. Since the fluxes
+   * include couplings between neighboring elements, the normal
+   * couplings and these extra matrix entries are considered.
    */
   template<class DH, class SparsityPattern>
   void
@@ -806,13 +613,9 @@ namespace DoFTools
                               SparsityPattern &sparsity_pattern);
 
   /**
-   * This function does the same as
-   * the other with the same name,
-   * but it gets a ConstraintMatrix
-   * additionally.
-   * This is for the case where you
-   * have fluxes but constraints as
-   * well.
+   * This function does the same as the other with the same name, but
+   * it gets a ConstraintMatrix additionally.  This is for the case
+   * where you have fluxes but constraints as well.
    *
    * @ingroup constraints
    */
@@ -825,24 +628,16 @@ namespace DoFTools
                               const types::subdomain_id  subdomain_id = numbers::invalid_unsigned_int);
 
   /**
-   * This function does the same as
-   * the other with the same name,
-   * but it gets two additional
-   * coefficient matrices. A matrix
-   * entry will only be generated
-   * for two basis functions, if
-   * there is a non-zero entry
-   * linking their associated
-   * components in the coefficient
+   * This function does the same as the other with the same name, but
+   * it gets two additional coefficient matrices. A matrix entry will
+   * only be generated for two basis functions, if there is a non-zero
+   * entry linking their associated components in the coefficient
    * matrix.
    *
-   * There is one matrix for
-   * couplings in a cell and one
-   * for the couplings occuring in
-   * fluxes.
+   * There is one matrix for couplings in a cell and one for the
+   * couplings occuring in fluxes.
    *
-   * Not implemented for
-   * hp::DoFHandler.
+   * @todo Not implemented for hp::DoFHandler.
    */
   template <class DH, class SparsityPattern>
   void
@@ -858,74 +653,43 @@ namespace DoFTools
    */
 
   /**
-   * Compute the constraints resulting from
-   * the presence of hanging nodes. Hanging
-   * nodes are best explained using a small
-   * picture:
+   * Compute the constraints resulting from the presence of hanging
+   * nodes. Hanging nodes are best explained using a small picture:
    *
    * @image html hanging_nodes.png
    *
-   * In order to make a finite element
-   * function globally continuous, we have
-   * to make sure that the dark red nodes
-   * have values that are compatible with
-   * the adjacent yellow nodes, so that the
-   * function has no jump when coming from
-   * the small cells to the large one at
-   * the top right. We therefore have to
-   * add conditions that constrain those
-   * "hanging nodes".
-   *
-   * The object into
-   * which these are inserted is
-   * later used to condense the
-   * global system matrix and right
-   * hand side, and to extend the
-   * solution vectors from the true
-   * degrees of freedom also to the
-   * constraint nodes. This
-   * function is explained in
-   * detail in the @ref step_6
-   * "step-6" tutorial program and
-   * is used in almost all
-   * following programs as well.
-   *
-   * This function does not clear
-   * the constraint matrix object
-   * before use, in order to allow
-   * adding constraints from
-   * different sources to the same
-   * object. You therefore need to
-   * make sure it contains only
-   * constraints you still want;
-   * otherwise call the
-   * ConstraintMatrix::clear()
-   * function.  Likewise, this
-   * function does not close the
-   * object since you may want to
-   * enter other constraints later
-   * on yourself.
-   *
-   * In the hp-case, i.e. when the
-   * argument is of type
-   * hp::DoFHandler, we consider
-   * constraints due to different
-   * finite elements used on two
-   * sides of a face between cells
-   * as hanging nodes as well. In
-   * other words, for hp finite
-   * elements, this function
-   * computes all constraints due
-   * to differing mesh sizes (h) or
-   * polynomial degrees (p) between
-   * adjacent cells.
-   *
-   * The template argument (and by
-   * consequence the type of the
-   * first argument to this
-   * function) can be either a
-   * ::DoFHandler, hp::DoFHandler,
-   * or MGDoFHandler.
+   * In order to make a finite element function globally continuous,
+   * we have to make sure that the dark red nodes have values that are
+   * compatible with the adjacent yellow nodes, so that the function
+   * has no jump when coming from the small cells to the large one at
+   * the top right. We therefore have to add conditions that constrain
+   * those "hanging nodes".
+   *
+   * The object into which these are inserted is later used to
+   * condense the global system matrix and right hand side, and to
+   * extend the solution vectors from the true degrees of freedom also
+   * to the constraint nodes. This function is explained in detail in
+   * the @ref step_6 "step-6" tutorial program and is used in almost
+   * all following programs as well.
+   *
+   * This function does not clear the constraint matrix object before
+   * use, in order to allow adding constraints from different sources
+   * to the same object. You therefore need to make sure it contains
+   * only constraints you still want; otherwise call the
+   * ConstraintMatrix::clear() function.  Likewise, this function does
+   * not close the object since you may want to enter other
+   * constraints later on yourself.
+   *
+   * In the hp-case, i.e. when the argument is of type hp::DoFHandler,
+   * we consider constraints due to different finite elements used on
+   * two sides of a face between cells as hanging nodes as well. In
+   * other words, for hp finite elements, this function computes all
+   * constraints due to differing mesh sizes (h) or polynomial degrees
+   * (p) between adjacent cells.
+   *
+   * The template argument (and by consequence the type of the first
+   * argument to this function) can be either ::DoFHandler or
+   * hp::DoFHandler.
    *
    * @ingroup constraints
    */
@@ -1270,58 +1034,35 @@ namespace DoFTools
 
 
   /**
-   * Take a vector of values which live on
-   * cells (e.g. an error per cell) and
-   * distribute it to the dofs in such a
-   * way that a finite element field
-   * results, which can then be further
-   * processed, e.g. for output. You should
-   * note that the resulting field will not
-   * be continuous at hanging nodes. This
-   * can, however, easily be arranged by
-   * calling the appropriate @p distribute
-   * function of a ConstraintMatrix
-   * object created for this
-   * DoFHandler object, after the
-   * vector has been fully assembled.
-   *
-   * It is assumed that the number
-   * of elements in @p cell_data
-   * equals the number of active
-   * cells and that the number of
-   * elements in @p dof_data equals
-   * <tt>dof_handler.n_dofs()</tt>.
-   *
-   * Note that the input vector may
-   * be a vector of any data type
-   * as long as it is convertible
-   * to @p double.  The output
-   * vector, being a data vector on
-   * a DoF handler, always consists of
-   * elements of type @p double.
-   *
-   * In case the finite element
-   * used by this DoFHandler
-   * consists of more than one
-   * component, you need to specify
-   * which component in the output
-   * vector should be used to store
-   * the finite element field in;
-   * the default is zero (no other
-   * value is allowed if the finite
-   * element consists only of one
-   * component). All other
-   * components of the vector
-   * remain untouched, i.e. their
-   * contents are not changed.
-   *
-   * This function cannot be used
-   * if the finite element in use
-   * has shape functions that are
-   * non-zero in more than one
-   * vector component (in deal.II
-   * speak: they are
-   * non-primitive).
+   * Take a vector of values which live on cells (e.g. an error per
+   * cell) and distribute it to the dofs in such a way that a finite
+   * element field results, which can then be further processed,
+   * e.g. for output. You should note that the resulting field will
+   * not be continuous at hanging nodes. This can, however, easily be
+   * arranged by calling the appropriate @p distribute function of a
+   * ConstraintMatrix object created for this DoFHandler object, after
+   * the vector has been fully assembled.
+   *
+   * It is assumed that the number of elements in @p cell_data equals
+   * the number of active cells and that the number of elements in @p
+   * dof_data equals <tt>dof_handler.n_dofs()</tt>.
+   *
+   * Note that the input vector may be a vector of any data type as
+   * long as it is convertible to @p double.  The output vector, being
+   * a data vector on a DoF handler, always consists of elements of
+   * type @p double.
+   *
+   * In case the finite element used by this DoFHandler consists of
+   * more than one component, you need to specify which component in
+   * the output vector should be used to store the finite element
+   * field in; the default is zero (no other value is allowed if the
+   * finite element consists only of one component). All other
+   * components of the vector remain untouched, i.e. their contents
+   * are not changed.
+   *
+   * This function cannot be used if the finite element in use has
+   * shape functions that are non-zero in more than one vector
+   * component (in deal.II speak: they are non-primitive).
    */
   template <class DH, typename Number>
   void
@@ -1331,50 +1072,30 @@ namespace DoFTools
                                  const unsigned int     component = 0);
 
   /**
-   * Extract the indices of the
-   * degrees of freedom belonging
-   * to certain vector components
-   * of
-   * a vector-valued finite
-   * element. The @p component_mask
-   * defines which
-   * components or blocks of an
-   * FESystem are to be extracted
-   * from the DoFHandler @p
-   * dof. The entries in the output array @p
-   * selected_dofs corresponding to
-   * degrees of freedom belonging
-   * to these components are then
-   * flagged @p true, while all
-   * others are set to @p false.
-   *
-   * The size of @p component_mask must
-   * be compatible with the number of components
-   * in the FiniteElement
-   * used by @p dof. The size of
-   * @p selected_dofs must equal
-   * DoFHandler::n_dofs(). Previous
-   * contents of this array are
-   * overwritten.
+   * Extract the indices of the degrees of freedom belonging to
+   * certain vector components of a vector-valued finite element. The
+   * @p component_mask defines which components or blocks of an
+   * FESystem are to be extracted from the DoFHandler @p dof. The
+   * entries in the output array @p selected_dofs corresponding to
+   * degrees of freedom belonging to these components are then flagged
+   * @p true, while all others are set to @p false.
+   *
+   * The size of @p component_mask must be compatible with the number
+   * of components in the FiniteElement used by @p dof. The size of @p
+   * selected_dofs must equal DoFHandler::n_dofs(). Previous contents
+   * of this array are overwritten.
    *
-   * If the finite element under
-   * consideration is not primitive, i.e.,
-   * some or all of its shape functions are
-   * non-zero in more than one vector
-   * component (which holds, for example, for
-   * FE_Nedelec or FE_RaviartThomas
-   * elements), then shape functions cannot
-   * be associated with a single vector
-   * component. In this case, if <em>one</em>
-   * shape vector component of this element
-   * is flagged in @p component_mask (see
-   * @ref GlossComponentMask), then this is
-   * equivalent to selecting <em>all</em>
-   * vector components corresponding to this
-   * non-primitive base element.
-   *
-   * @note If the @p blocks argument is
-   * true,
+   * If the finite element under consideration is not primitive, i.e.,
+   * some or all of its shape functions are non-zero in more than one
+   * vector component (which holds, for example, for FE_Nedelec or
+   * FE_RaviartThomas elements), then shape functions cannot be
+   * associated with a single vector component. In this case, if
+   * <em>one</em> shape vector component of this element is flagged in
+   * @p component_mask (see @ref GlossComponentMask), then this is
+   * equivalent to selecting <em>all</em> vector components
+   * corresponding to this non-primitive base element.
+   *
+   * @note If the @p blocks argument is true,
    */
   template <int dim, int spacedim>
   void
@@ -1383,8 +1104,7 @@ namespace DoFTools
                 std::vector<bool>       &selected_dofs);
 
   /**
-   * The same function as above,
-   * but for a hp::DoFHandler.
+   * The same function as above, but for a hp::DoFHandler.
    */
   template <int dim, int spacedim>
   void
@@ -1412,8 +1132,7 @@ namespace DoFTools
                 std::vector<bool>       &selected_dofs);
 
   /**
-   * The same function as above,
-   * but for a hp::DoFHandler.
+   * The same function as above, but for a hp::DoFHandler.
    */
   template <int dim, int spacedim>
   void
@@ -1422,9 +1141,8 @@ namespace DoFTools
                 std::vector<bool>       &selected_dofs);
 
   /**
-   * Do the same thing as the corresponding
-   * extract_dofs() function for one level
-   * of a multi-grid DoF numbering.
+   * Do the same thing as the corresponding extract_dofs() function
+   * for one level of a multi-grid DoF numbering.
    */
   template <class DH>
   void
@@ -1434,9 +1152,8 @@ namespace DoFTools
                       std::vector<bool>       &selected_dofs);
 
   /**
-   * Do the same thing as the corresponding
-   * extract_dofs() function for one level
-   * of a multi-grid DoF numbering.
+   * Do the same thing as the corresponding extract_dofs() function
+   * for one level of a multi-grid DoF numbering.
    */
   template <class DH>
   void
@@ -1446,66 +1163,38 @@ namespace DoFTools
                       std::vector<bool>       &selected_dofs);
 
   /**
-   * Extract all degrees of freedom
-   * which are at the boundary and
-   * belong to specified components
-   * of the solution. The function
-   * returns its results in the
-   * last non-default-valued
-   * parameter which contains
-   * @p true if a degree of
-   * freedom is at the boundary and
-   * belongs to one of the selected
-   * components, and @p false
+   * Extract all degrees of freedom which are at the boundary and
+   * belong to specified components of the solution. The function
+   * returns its results in the last non-default-valued parameter
+   * which contains @p true if a degree of freedom is at the boundary
+   * and belongs to one of the selected components, and @p false
    * otherwise. The function is used in step-15.
    *
-   * By specifying the
-   * @p boundary_indicator
-   * variable, you can select which
-   * boundary indicators the faces
-   * have to have on which the
-   * degrees of freedom are located
-   * that shall be extracted. If it
-   * is an empty list, then all
-   * boundary indicators are
-   * accepted.
-   *
-   * The size of @p component_mask (see @ref GlossComponentMask)
-   * shall equal the number of
-   * components in the finite
-   * element used by @p dof. The
-   * size of @p selected_dofs shall
-   * equal
-   * <tt>dof_handler.n_dofs()</tt>. Previous
-   * contents of this array or
+   * By specifying the @p boundary_indicator variable, you can select
+   * which boundary indicators the faces have to have on which the
+   * degrees of freedom are located that shall be extracted. If it is
+   * an empty list, then all boundary indicators are accepted.
+   *
+   * The size of @p component_mask (see @ref GlossComponentMask) shall
+   * equal the number of components in the finite element used by @p
+   * dof. The size of @p selected_dofs shall equal
+   * <tt>dof_handler.n_dofs()</tt>. Previous contents of this array or
    * overwritten.
    *
-   * Using the usual convention, if
-   * a shape function is non-zero
-   * in more than one component
-   * (i.e. it is non-primitive),
-   * then the element in the
-   * component mask is used that
-   * corresponds to the first
-   * non-zero components. Elements
-   * in the mask corresponding to
+   * Using the usual convention, if a shape function is non-zero in
+   * more than one component (i.e. it is non-primitive), then the
+   * element in the component mask is used that corresponds to the
+   * first non-zero components. Elements in the mask corresponding to
    * later components are ignored.
    *
-   * @note This function will not work
-   * for DoFHandler objects that are
-   * built on a
-   * parallel::distributed::Triangulation
-   * object. The reasons is that the
-   * output argument @p selected_dofs
-   * has to have a length equal to <i>all</i>
-   * global degrees of freedom.
-   * Consequently, this does not scale
-   * to very large problems. If you
-   * need the functionality of this
-   * function for parallel triangulations,
-   * then you need to use the other
-   * DoFTools::extract_boundary_dofs
-   * function.
+   * @note This function will not work for DoFHandler objects that are
+   * built on a parallel::distributed::Triangulation object. The
+   * reasons is that the output argument @p selected_dofs has to have
+   * a length equal to <i>all</i> global degrees of freedom.
+   * Consequently, this does not scale to very large problems. If you
+   * need the functionality of this function for parallel
+   * triangulations, then you need to use the other
+   * DoFTools::extract_boundary_dofs function.
    *
    * @param dof_handler The object that describes which degrees of freedom
    *          live on which cell
@@ -1572,34 +1261,19 @@ namespace DoFTools
                          const std::set<types::boundary_id> &boundary_indicators = std::set<types::boundary_id>());
 
   /**
-   * This function is similar to
-   * the extract_boundary_dofs()
-   * function but it extracts those
-   * degrees of freedom whose shape
-   * functions are nonzero on at
-   * least part of the selected
-   * boundary. For continuous
-   * elements, this is exactly the
-   * set of shape functions whose
-   * degrees of freedom are defined
-   * on boundary faces. On the
-   * other hand, if the finite
-   * element in used is a
-   * discontinuous element, all
-   * degrees of freedom are defined
-   * in the inside of cells and
-   * consequently none would be
-   * boundary degrees of
-   * freedom. Several of those
-   * would have shape functions
-   * that are nonzero on the
-   * boundary, however. This
-   * function therefore extracts
-   * all those for which the
-   * FiniteElement::has_support_on_face
-   * function says that it is
-   * nonzero on any face on one of
-   * the selected boundary parts.
+   * This function is similar to the extract_boundary_dofs() function
+   * but it extracts those degrees of freedom whose shape functions
+   * are nonzero on at least part of the selected boundary. For
+   * continuous elements, this is exactly the set of shape functions
+   * whose degrees of freedom are defined on boundary faces. On the
+   * other hand, if the finite element in used is a discontinuous
+   * element, all degrees of freedom are defined in the inside of
+   * cells and consequently none would be boundary degrees of
+   * freedom. Several of those would have shape functions that are
+   * nonzero on the boundary, however. This function therefore
+   * extracts all those for which the
+   * FiniteElement::has_support_on_face function says that it is
+   * nonzero on any face on one of the selected boundary parts.
    *
    * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
    */
@@ -1616,15 +1290,11 @@ namespace DoFTools
    */
 
   /**
-   * Select all dofs that will be
-   * constrained by interface
-   * constraints, i.e. all hanging
-   * nodes.
+   * Select all dofs that will be constrained by interface
+   * constraints, i.e. all hanging nodes.
    *
-   * The size of @p selected_dofs
-   * shall equal
-   * <tt>dof_handler.n_dofs()</tt>. Previous
-   * contents of this array or
+   * The size of @p selected_dofs shall equal
+   * <tt>dof_handler.n_dofs()</tt>. Previous contents of this array or
    * overwritten.
    */
   template <int dim, int spacedim>
@@ -1638,22 +1308,13 @@ namespace DoFTools
    * @{
    */
   /**
-   * Flag all those degrees of
-   * freedom which are on cells
-   * with the given subdomain
-   * id. Note that DoFs on faces
-   * can belong to cells with
-   * differing subdomain ids, so
-   * the sets of flagged degrees of
-   * freedom are not mutually
-   * exclusive for different
-   * subdomain ids.
-   *
-   * If you want to get a unique
-   * association of degree of freedom with
-   * subdomains, use the
-   * @p get_subdomain_association
-   * function.
+   * Flag all those degrees of freedom which are on cells with the
+   * given subdomain id. Note that DoFs on faces can belong to cells
+   * with differing subdomain ids, so the sets of flagged degrees of
+   * freedom are not mutually exclusive for different subdomain ids.
+   *
+   * If you want to get a unique association of degree of freedom with
+   * subdomains, use the @p get_subdomain_association function.
    */
   template <class DH>
   void
@@ -1663,15 +1324,10 @@ namespace DoFTools
 
 
   /**
-   * Extract the set of global DoF
-   * indices that are owned by the
-   * current processor. For regular
-   * DoFHandler objects, this set
-   * is the complete set with all
-   * DoF indices. In either case,
-   * it equals what
-   * DoFHandler::locally_owned_dofs()
-   * returns.
+   * Extract the set of global DoF indices that are owned by the
+   * current processor. For regular DoFHandler objects, this set is
+   * the complete set with all DoF indices. In either case, it equals
+   * what DoFHandler::locally_owned_dofs() returns.
    */
   template <class DH>
   void
@@ -1680,32 +1336,19 @@ namespace DoFTools
 
 
   /**
-   * Extract the set of global DoF
-   * indices that are active on the
-   * current DoFHandler. For
-   * regular DoFHandlers, these are
-   * all DoF indices, but for
-   * DoFHandler objects built on
-   * parallel::distributed::Triangulation
-   * this set is a superset of
-   * DoFHandler::locally_owned_dofs()
-   * and contains all DoF indices
-   * that live on all locally owned
-   * cells (including on the
-   * interface to ghost
-   * cells). However, it does not
-   * contain the DoF indices that
-   * are exclusively defined on
-   * ghost or artificial cells (see
-   * @ref GlossArtificialCell "the
-   * glossary").
-   *
-   * The degrees of freedom identified by
-   * this function equal those obtained
-   * from the
-   * dof_indices_with_subdomain_association()
-   * function when called with the locally
-   * owned subdomain id.
+   * Extract the set of global DoF indices that are active on the
+   * current DoFHandler. For regular DoFHandlers, these are all DoF
+   * indices, but for DoFHandler objects built on
+   * parallel::distributed::Triangulation this set is a superset of
+   * DoFHandler::locally_owned_dofs() and contains all DoF indices
+   * that live on all locally owned cells (including on the interface
+   * to ghost cells). However, it does not contain the DoF indices
+   * that are exclusively defined on ghost or artificial cells (see
+   * @ref GlossArtificialCell "the glossary").
+   *
+   * The degrees of freedom identified by this function equal those
+   * obtained from the dof_indices_with_subdomain_association()
+   * function when called with the locally owned subdomain id.
    */
   template <class DH>
   void
@@ -1713,20 +1356,13 @@ namespace DoFTools
                                IndexSet &dof_set);
 
   /**
-   * Extract the set of global DoF
-   * indices that are active on the
-   * current DoFHandler. For
-   * regular DoFHandlers, these are
-   * all DoF indices, but for
-   * DoFHandler objects built on
-   * parallel::distributed::Triangulation
-   * this set is the union of
-   * DoFHandler::locally_owned_dofs()
-   * and the DoF indices on all
-   * ghost cells. In essence, it is
-   * the DoF indices on all cells
-   * that are not artificial (see
-   * @ref GlossArtificialCell "the glossary").
+   * Extract the set of global DoF indices that are active on the
+   * current DoFHandler. For regular DoFHandlers, these are all DoF
+   * indices, but for DoFHandler objects built on
+   * parallel::distributed::Triangulation this set is the union of
+   * DoFHandler::locally_owned_dofs() and the DoF indices on all ghost
+   * cells. In essence, it is the DoF indices on all cells that are
+   * not artificial (see @ref GlossArtificialCell "the glossary").
    */
   template <class DH>
   void
@@ -1734,57 +1370,36 @@ namespace DoFTools
                                  IndexSet &dof_set);
 
   /**
-   * For each DoF, return in the output
-   * array to which subdomain (as given by
-   * the <tt>cell->subdomain_id()</tt> function)
-   * it belongs. The output array is
-   * supposed to have the right size
+   * For each DoF, return in the output array to which subdomain (as
+   * given by the <tt>cell->subdomain_id()</tt> function) it
+   * belongs. The output array is supposed to have the right size
    * already when calling this function.
    *
-   * Note that degrees of freedom
-   * associated with faces, edges, and
-   * vertices may be associated with
-   * multiple subdomains if they are
-   * sitting on partition boundaries. In
-   * these cases, we put them into one of
-   * the associated partitions in an
-   * undefined way. This may sometimes lead
-   * to different numbers of degrees of
-   * freedom in partitions, even if the
-   * number of cells is perfectly
-   * equidistributed. While this is
-   * regrettable, it is not a problem in
-   * practice since the number of degrees
-   * of freedom on partition boundaries is
-   * asymptotically vanishing as we refine
-   * the mesh as long as the number of
-   * partitions is kept constant.
-   *
-   * This function returns the association
-   * of each DoF with one subdomain. If you
-   * are looking for the association of
-   * each @em cell with a subdomain, either
-   * query the
-   * <tt>cell->subdomain_id()</tt>
-   * function, or use the
-   * <tt>GridTools::get_subdomain_association</tt>
-   * function.
-   *
-   * Note that this function is of
-   * questionable use for DoFHandler objects built on
-   * parallel::distributed::Triangulation
-   * since in that case ownership of
-   * individual degrees of freedom by MPI
-   * processes is controlled by the DoF
-   * handler object, not based on some
-   * geometric algorithm in conjunction
-   * with subdomain id. In particular, the
-   * degrees of freedom identified by the
-   * functions in this namespace as
-   * associated with a subdomain are not
-   * the same the
-   * DoFHandler class
-   * identifies as those it owns.
+   * Note that degrees of freedom associated with faces, edges, and
+   * vertices may be associated with multiple subdomains if they are
+   * sitting on partition boundaries. In these cases, we put them into
+   * one of the associated partitions in an undefined way. This may
+   * sometimes lead to different numbers of degrees of freedom in
+   * partitions, even if the number of cells is perfectly
+   * equidistributed. While this is regrettable, it is not a problem
+   * in practice since the number of degrees of freedom on partition
+   * boundaries is asymptotically vanishing as we refine the mesh as
+   * long as the number of partitions is kept constant.
+   *
+   * This function returns the association of each DoF with one
+   * subdomain. If you are looking for the association of each @em
+   * cell with a subdomain, either query the
+   * <tt>cell->subdomain_id()</tt> function, or use the
+   * <tt>GridTools::get_subdomain_association</tt> function.
+   *
+   * Note that this function is of questionable use for DoFHandler
+   * objects built on parallel::distributed::Triangulation since in
+   * that case ownership of individual degrees of freedom by MPI
+   * processes is controlled by the DoF handler object, not based on
+   * some geometric algorithm in conjunction with subdomain id. In
+   * particular, the degrees of freedom identified by the functions in
+   * this namespace as associated with a subdomain are not the same
+   * the DoFHandler class identifies as those it owns.
    */
   template <class DH>
   void
@@ -1792,43 +1407,31 @@ namespace DoFTools
                              std::vector<types::subdomain_id> &subdomain);
 
   /**
-   * Count how many degrees of freedom are
-   * uniquely associated with the given
-   * @p subdomain index.
+   * Count how many degrees of freedom are uniquely associated with
+   * the given @p subdomain index.
    *
-   * Note that there may be rare cases
-   * where cells with the given @p
-   * subdomain index exist, but none of its
-   * degrees of freedom are actually
-   * associated with it. In that case, the
-   * returned value will be zero.
+   * Note that there may be rare cases where cells with the given @p
+   * subdomain index exist, but none of its degrees of freedom are
+   * actually associated with it. In that case, the returned value
+   * will be zero.
    *
-   * This function will generate an
-   * exception if there are no cells with
-   * the given @p subdomain index.
+   * This function will generate an exception if there are no cells
+   * with the given @p subdomain index.
    *
-   * This function returns the number of
-   * DoFs associated with one subdomain. If
-   * you are looking for the association of
-   * @em cells with this subdomain, use the
+   * This function returns the number of DoFs associated with one
+   * subdomain. If you are looking for the association of @em cells
+   * with this subdomain, use the
    * <tt>GridTools::count_cells_with_subdomain_association</tt>
    * function.
    *
-   * Note that this function is of
-   * questionable use for DoFHandler objects built on
-   * parallel::distributed::Triangulation
-   * since in that case ownership of
-   * individual degrees of freedom by MPI
-   * processes is controlled by the DoF
-   * handler object, not based on some
-   * geometric algorithm in conjunction
-   * with subdomain id. In particular, the
-   * degrees of freedom identified by the
-   * functions in this namespace as
-   * associated with a subdomain are not
-   * the same the
-   * DoFHandler class
-   * identifies as those it owns.
+   * Note that this function is of questionable use for DoFHandler
+   * objects built on parallel::distributed::Triangulation since in
+   * that case ownership of individual degrees of freedom by MPI
+   * processes is controlled by the DoF handler object, not based on
+   * some geometric algorithm in conjunction with subdomain id. In
+   * particular, the degrees of freedom identified by the functions in
+   * this namespace as associated with a subdomain are not the same
+   * the DoFHandler class identifies as those it owns.
    */
   template <class DH>
   unsigned int
@@ -1836,36 +1439,24 @@ namespace DoFTools
                                          const types::subdomain_id subdomain);
 
   /**
-   * Count how many degrees of freedom are
-   * uniquely associated with the given
-   * @p subdomain index.
-   *
-   * This function does what the previous
-   * one does except that it splits the
-   * result among the vector components of
-   * the finite element in use by the
-   * DoFHandler object. The last argument
-   * (which must have a length equal to the
-   * number of vector components) will
-   * therefore store how many degrees of
-   * freedom of each vector component are
-   * associated with the given subdomain.
-   *
-   * Note that this function is of
-   * questionable use for DoFHandler objects built on
-   * parallel::distributed::Triangulation
-   * since in that case ownership of
-   * individual degrees of freedom by MPI
-   * processes is controlled by the DoF
-   * handler object, not based on some
-   * geometric algorithm in conjunction
-   * with subdomain id. In particular, the
-   * degrees of freedom identified by the
-   * functions in this namespace as
-   * associated with a subdomain are not
-   * the same the
-   * DoFHandler class
-   * identifies as those it owns.
+   * Count how many degrees of freedom are uniquely associated with
+   * the given @p subdomain index.
+   *
+   * This function does what the previous one does except that it
+   * splits the result among the vector components of the finite
+   * element in use by the DoFHandler object. The last argument (which
+   * must have a length equal to the number of vector components) will
+   * therefore store how many degrees of freedom of each vector
+   * component are associated with the given subdomain.
+   *
+   * Note that this function is of questionable use for DoFHandler
+   * objects built on parallel::distributed::Triangulation since in
+   * that case ownership of individual degrees of freedom by MPI
+   * processes is controlled by the DoF handler object, not based on
+   * some geometric algorithm in conjunction with subdomain id. In
+   * particular, the degrees of freedom identified by the functions in
+   * this namespace as associated with a subdomain are not the same
+   * the DoFHandler class identifies as those it owns.
    */
   template <class DH>
   void
@@ -1874,40 +1465,26 @@ namespace DoFTools
                                          std::vector<unsigned int> &n_dofs_on_subdomain);
 
   /**
-   * Return a set of indices that denotes
-   * the degrees of freedom that live on
-   * the given subdomain, i.e. that are on
-   * cells owned by the current
-   * processor. Note that this includes the
-   * ones that this subdomain "owns"
-   * (i.e. the ones for which
-   * get_subdomain_association() returns a
-   * value equal to the subdomain given
-   * here and that are selected by the
-   * extract_locally_owned() function) but
-   * also all of those that sit on the
-   * boundary between the given subdomain
-   * and other subdomain. In essence,
-   * degrees of freedom that sit on
-   * boundaries between subdomain will be
-   * in the index sets returned by this
+   * Return a set of indices that denotes the degrees of freedom that
+   * live on the given subdomain, i.e. that are on cells owned by the
+   * current processor. Note that this includes the ones that this
+   * subdomain "owns" (i.e. the ones for which
+   * get_subdomain_association() returns a value equal to the
+   * subdomain given here and that are selected by the
+   * extract_locally_owned() function) but also all of those that sit
+   * on the boundary between the given subdomain and other
+   * subdomain. In essence, degrees of freedom that sit on boundaries
+   * between subdomain will be in the index sets returned by this
    * function for more than one subdomain.
    *
-   * Note that this function is of
-   * questionable use for DoFHandler objects built on
-   * parallel::distributed::Triangulation
-   * since in that case ownership of
-   * individual degrees of freedom by MPI
-   * processes is controlled by the DoF
-   * handler object, not based on some
-   * geometric algorithm in conjunction
-   * with subdomain id. In particular, the
-   * degrees of freedom identified by the
-   * functions in this namespace as
-   * associated with a subdomain are not
-   * the same the
-   * DoFHandler class
-   * identifies as those it owns.
+   * Note that this function is of questionable use for DoFHandler
+   * objects built on parallel::distributed::Triangulation since in
+   * that case ownership of individual degrees of freedom by MPI
+   * processes is controlled by the DoF handler object, not based on
+   * some geometric algorithm in conjunction with subdomain id. In
+   * particular, the degrees of freedom identified by the functions in
+   * this namespace as associated with a subdomain are not the same
+   * the DoFHandler class identifies as those it owns.
    */
   template <class DH>
   IndexSet
@@ -1917,37 +1494,24 @@ namespace DoFTools
   /**
    * @name Dof indices for patches
    *
-   * Create structures containing a
-   * large set of degrees of freedom
-   * for small patches of cells. The
-   * resulting objects can be used in
-   * RelaxationBlockSOR and related
-   * classes to implement Schwarz
-   * preconditioners and smoothers,
-   * where the subdomains consist of
+   * Create structures containing a large set of degrees of freedom
+   * for small patches of cells. The resulting objects can be used in
+   * RelaxationBlockSOR and related classes to implement Schwarz
+   * preconditioners and smoothers, where the subdomains consist of
    * small numbers of cells only.
    */
   //@{
   /**
-   * Create an incidence matrix that
-   * for every cell on a given level
-   * of a multilevel DoFHandler flags
-   * which degrees of freedom are
-   * associated with the
-   * corresponding cell. This data
-   * structure is matrix with as many
-   * rows as there are cells on a
-   * given level, as many rows as
-   * there are degrees of freedom on
-   * this level, and entries that are
-   * either true or false. This data
-   * structure is conveniently
-   * represented by a SparsityPattern
-   * object.
-   *
-   * @note The ordering of rows
-   * (cells) follows the ordering of
-   * the standard cell iterators.
+   * Create an incidence matrix that for every cell on a given level
+   * of a multilevel DoFHandler flags which degrees of freedom are
+   * associated with the corresponding cell. This data structure is
+   * matrix with as many rows as there are cells on a given level, as
+   * many rows as there are degrees of freedom on this level, and
+   * entries that are either true or false. This data structure is
+   * conveniently represented by a SparsityPattern object.
+   *
+   * @note The ordering of rows (cells) follows the ordering of the
+   * standard cell iterators.
    */
   template <class DH, class Sparsity>
   void make_cell_patches(Sparsity &block_list,
@@ -1957,73 +1521,45 @@ namespace DoFTools
                          types::global_dof_index offset = 0);
 
   /**
-   * Create an incidence matrix that
-   * for every vertex on a given level
-   * of a multilevel DoFHandler flags
-   * which degrees of freedom are
-   * associated with the
-   * adjacent cells. This data
-   * structure is matrix with as many
-   * rows as there are vertices on a
-   * given level, as many rows as
-   * there are degrees of freedom on
-   * this level, and entries that are
-   * either true or false. This data
-   * structure is conveniently
-   * represented by a SparsityPattern
-   * object.
-   * The sparsity pattern
-   * may be empty when entering this
-   * function and will be
-   * reinitialized to the correct
-   * size.
-   *
-   * The function has some boolean
-   * arguments (listed below)
-   * controlling details of the
-   * generated patches. The default
-   * settings are those for
-   * Arnold-Falk-Winther type
-   * smoothers for divergence and
-   * curl conforming finite elements
-   * with essential boundary
-   * conditions. Other applications
-   * are possible, in particular
-   * changing
-   * <tt>boundary_patches</tt> for
-   * non-essential boundary conditions.
-   *
-   * @arg <tt>block_list</tt>: the
-   * SparsityPattern into which the
+   * Create an incidence matrix that for every vertex on a given level
+   * of a multilevel DoFHandler flags which degrees of freedom are
+   * associated with the adjacent cells. This data structure is matrix
+   * with as many rows as there are vertices on a given level, as many
+   * rows as there are degrees of freedom on this level, and entries
+   * that are either true or false. This data structure is
+   * conveniently represented by a SparsityPattern object.  The
+   * sparsity pattern may be empty when entering this function and
+   * will be reinitialized to the correct size.
+   *
+   * The function has some boolean arguments (listed below)
+   * controlling details of the generated patches. The default
+   * settings are those for Arnold-Falk-Winther type smoothers for
+   * divergence and curl conforming finite elements with essential
+   * boundary conditions. Other applications are possible, in
+   * particular changing <tt>boundary_patches</tt> for non-essential
+   * boundary conditions.
+   *
+   * @arg <tt>block_list</tt>: the SparsityPattern into which the
    * patches will be stored.
-   * @arg <tt>dof_handler</tt>: The
-   * multilevel dof handler
-   * providing the topology operated
-   * on.
-   * @arg
-   * <tt>interior_dofs_only</tt>:
-   * for each patch of cells around
-   * a vertex, collect only the
-   * interior degrees of freedom of
-   * the patch and disregard those
-   * on the boundary of the
-   * patch. This is for instance the
-   * setting for smoothers of
-   * Arnold-Falk-Winther type.
-   * @arg <tt>boundary_patches</tt>:
-   * include patches around vertices
-   * at the boundary of the
-   * domain. If not, only patches
-   * around interior vertices will
-   * be generated.
-   * @arg
-   * <tt>level_boundary_patches</tt>:
-   * same for refinement edges
+   *
+   * @arg <tt>dof_handler</tt>: The multilevel dof handler providing
+   * the topology operated on.
+   *
+   * @arg <tt>interior_dofs_only</tt>: for each patch of cells around
+   * a vertex, collect only the interior degrees of freedom of the
+   * patch and disregard those on the boundary of the patch. This is
+   * for instance the setting for smoothers of Arnold-Falk-Winther
+   * type.
+   *
+   * @arg <tt>boundary_patches</tt>: include patches around vertices
+   * at the boundary of the domain. If not, only patches around
+   * interior vertices will be generated.
+   *
+   * @arg <tt>level_boundary_patches</tt>: same for refinement edges
    * towards coarser cells.
-   * @arg
-   * <tt>single_cell_patches</tt>:
-   * if not true, patches containing
-   * a single cell are eliminated.
+   *
+   * @arg <tt>single_cell_patches</tt>: if not true, patches
+   * containing a single cell are eliminated.
    */
   template <class DH>
   void make_vertex_patches(SparsityPattern &block_list,
@@ -2035,71 +1571,42 @@ namespace DoFTools
                            const bool single_cell_patches = false);
 
   /**
-   * Create an incidence matrix that
-   * for every cell on a given level
-   * of a multilevel DoFHandler flags
-   * which degrees of freedom are
-   * associated with children of this
-   * cell. This data
-   * structure is conveniently
-   * represented by a SparsityPattern
-   * object.
-
-   * Create a sparsity pattern which
-   * in each row lists the degrees of
-   * freedom associated to the
-   * cells which are the children of
-   * the same cell. The
-   * sparsity pattern may be empty
-   * when entering this function and
-   * will be reinitialized to the
-   * correct size.
-   *
-   * The function has some boolean
-   * arguments (lsited below)
-   * controlling details of the
-   * generated patches. The default
-   * settings are those for
-   * Arnold-Falk-Winther type
-   * smoothers for divergence and
-   * curl conforming finite elements
-   * with essential boundary
-   * conditions. Other applications
-   * are possible, in particular
-   * changing
-   * <tt>boundary_dofs</tt> for
-   * non-essential boundary
-   * conditions.
-   *
-   * Since the patches are defined
-   * through refinement, th
-   *
-   * @arg <tt>block_list</tt>: the
-   * SparsityPattern into which the
+   * Create an incidence matrix that for every cell on a given level
+   * of a multilevel DoFHandler flags which degrees of freedom are
+   * associated with children of this cell. This data structure is
+   * conveniently represented by a SparsityPattern object.
+
+   * Create a sparsity pattern which in each row lists the degrees of
+   * freedom associated to the cells which are the children of the
+   * same cell. The sparsity pattern may be empty when entering this
+   * function and will be reinitialized to the correct size.
+   *
+   * The function has some boolean arguments (listed below)
+   * controlling details of the generated patches. The default
+   * settings are those for Arnold-Falk-Winther type smoothers for
+   * divergence and curl conforming finite elements with essential
+   * boundary conditions. Other applications are possible, in
+   * particular changing <tt>boundary_dofs</tt> for non-essential
+   * boundary conditions.
+   *
+   * Since the patches are defined through refinement, th
+   *
+   * @arg <tt>block_list</tt>: the SparsityPattern into which the
    * patches will be stored.
-   * @arg <tt>dof_handler</tt>: The
-   * multilevel dof handler
-   * providing the topology operated
-   * on.
-   * @arg
-   * <tt>interior_dofs_only</tt>:
-   * for each patch of cells around
-   * a vertex, collect only the
-   * interior degrees of freedom of
-   * the patch and disregard those
-   * on the boundary of the
-   * patch. This is for instance the
-   * setting for smoothers of
-   * Arnold-Falk-Winther type.
-   * @arg <tt>boundary_dofs</tt>:
-   * include degrees of freedom,
-   * which would have excluded by
-   * <tt>interior_dofs_only</tt>,
-   * but are lying on the boundary
-   * of the domain, and thus need
-   * smoothing. This parameter has
-   * no effect if
-   * <tt>interior_dofs_only</tt> is false.
+   *
+   * @arg <tt>dof_handler</tt>: The multilevel dof handler providing
+   * the topology operated on.
+   *
+   * @arg <tt>interior_dofs_only</tt>: for each patch of cells around
+   * a vertex, collect only the interior degrees of freedom of the
+   * patch and disregard those on the boundary of the patch. This is
+   * for instance the setting for smoothers of Arnold-Falk-Winther
+   * type.
+   *
+   * @arg <tt>boundary_dofs</tt>: include degrees of freedom, which
+   * would have excluded by <tt>interior_dofs_only</tt>, but are lying
+   * on the boundary of the domain, and thus need smoothing. This
+   * parameter has no effect if <tt>interior_dofs_only</tt> is false.
    */
   template <class DH>
   void make_child_patches(SparsityPattern &block_list,
@@ -2109,30 +1616,23 @@ namespace DoFTools
                           const bool boundary_dofs = false);
 
   /**
-   * Create a block list with only a
-   * single patch, which in turn
-   * contains all degrees of freedom
-   * on the given level.
+   * Create a block list with only a single patch, which in turn
+   * contains all degrees of freedom on the given level.
    *
-   * This function is mostly a
-   * closure on level 0 for functions
-   * like make_child_patches() and
-   * make_vertex_patches(), which may
-   * produce an empty patch list.
+   * This function is mostly a closure on level 0 for functions like
+   * make_child_patches() and make_vertex_patches(), which may produce
+   * an empty patch list.
    *
-   * @arg <tt>block_list</tt>: the
-   * SparsityPattern into which the
+   * @arg <tt>block_list</tt>: the SparsityPattern into which the
    * patches will be stored.
-   * @arg <tt>dof_handler</tt>: The
-   * multilevel dof handler
-   * providing the topology operated
-   * on.
-   * @arg <tt>level</tt> The grid
-   * level used for building the list.
-   * @arg
-   * <tt>interior_dofs_only</tt>:
-   * if true, exclude degrees of freedom on
-   * the boundary of the domain.
+   *
+   * @arg <tt>dof_handler</tt>: The multilevel dof handler providing
+   * the topology operated on.
+   *
+   * @arg <tt>level</tt> The grid level used for building the list.
+   *
+   * @arg <tt>interior_dofs_only</tt>: if true, exclude degrees of
+   * freedom on the boundary of the domain.
    */
   template <class DH>
   void make_single_patch(SparsityPattern &block_list,
@@ -2142,49 +1642,32 @@ namespace DoFTools
 
   //@}
   /**
-   * Extract a vector that represents the
-   * constant modes of the DoFHandler for the
-   * components chosen by
-   * <tt>component_mask</tt> (see @ref
-   * GlossComponentMask).  The constant modes
-   * on a discretization are the null space
-   * of a Laplace operator on the selected
-   * components with Neumann boundary
-   * conditions applied. The null space is a
-   * necessary ingredient for obtaining a
-   * good AMG preconditioner when using the
-   * class TrilinosWrappers::PreconditionAMG.
-   * Since the ML AMG package only works on
-   * algebraic properties of the respective
-   * matrix, it has no chance to detect
-   * whether the matrix comes from a scalar
-   * or a vector valued problem. However, a
-   * near null space supplies exactly the
-   * needed information about these
-   * components.  The null space will consist
-   * of as many vectors as there are true
-   * arguments in <tt>component_mask</tt>
-   * (see @ref GlossComponentMask), each of
-   * which will be one in one vector
-   * component and zero in all others. We
-   * store this object in a vector of
-   * vectors, where the outer vector is of
-   * the size of the number of selected
-   * components, and each inner vector has as
-   * many components as there are (locally
-   * owned) degrees of freedom in the
-   * selected components. Note that any
-   * matrix associated with this null space
-   * must have been constructed using the
-   * same <tt>component_mask</tt> argument,
-   * since the numbering of DoFs is done
-   * relative to the selected dofs, not to
-   * all dofs.
-   *
-   * The main reason for this
-   * program is the use of the
-   * null space with the
-   * AMG preconditioner.
+   * Extract a vector that represents the constant modes of the
+   * DoFHandler for the components chosen by <tt>component_mask</tt>
+   * (see @ref GlossComponentMask).  The constant modes on a
+   * discretization are the null space of a Laplace operator on the
+   * selected components with Neumann boundary conditions applied. The
+   * null space is a necessary ingredient for obtaining a good AMG
+   * preconditioner when using the class
+   * TrilinosWrappers::PreconditionAMG.  Since the ML AMG package only
+   * works on algebraic properties of the respective matrix, it has no
+   * chance to detect whether the matrix comes from a scalar or a
+   * vector valued problem. However, a near null space supplies
+   * exactly the needed information about these components.  The null
+   * space will consist of as many vectors as there are true arguments
+   * in <tt>component_mask</tt> (see @ref GlossComponentMask), each of
+   * which will be one in one vector component and zero in all
+   * others. We store this object in a vector of vectors, where the
+   * outer vector is of the size of the number of selected components,
+   * and each inner vector has as many components as there are
+   * (locally owned) degrees of freedom in the selected
+   * components. Note that any matrix associated with this null space
+   * must have been constructed using the same <tt>component_mask</tt>
+   * argument, since the numbering of DoFs is done relative to the
+   * selected dofs, not to all dofs.
+   *
+   * The main reason for this program is the use of the null space
+   * with the AMG preconditioner.
    */
   template <class DH>
   void
@@ -2193,18 +1676,14 @@ namespace DoFTools
                           std::vector<std::vector<bool> > &constant_modes);
 
   /**
-   * For each active cell of a DoFHandler
-   * or hp::DoFHandler, extract the active
-   * finite element index and fill the
-   * vector given as second argument. This
-   * vector is assumed to have as many
-   * entries as there are active cells.
+   * For each active cell of a DoFHandler or hp::DoFHandler, extract
+   * the active finite element index and fill the vector given as
+   * second argument. This vector is assumed to have as many entries
+   * as there are active cells.
    *
-   * For non-hp DoFHandler objects given as
-   * first argument, the returned vector
-   * will consist of only zeros, indicating
-   * that all cells use the same finite
-   * element. For a hp::DoFHandler, the
+   * For non-hp DoFHandler objects given as first argument, the
+   * returned vector will consist of only zeros, indicating that all
+   * cells use the same finite element. For a hp::DoFHandler, the
    * values may be different, though.
    */
   template <class DH>
@@ -2213,81 +1692,42 @@ namespace DoFTools
                          std::vector<unsigned int> &active_fe_indices);
 
   /**
-   * Count how many degrees of
-   * freedom out of the total
-   * number belong to each
-   * component. If the number of
-   * components the finite element
-   * has is one (i.e. you only have
-   * one scalar variable), then the
-   * number in this component
-   * obviously equals the total
-   * number of degrees of
-   * freedom. Otherwise, the sum of
-   * the DoFs in all the components
-   * needs to equal the total
-   * number.
-   *
-   * However, the last statement
-   * does not hold true if the
-   * finite element is not
-   * primitive, i.e. some or all of
-   * its shape functions are
-   * non-zero in more than one
-   * vector component. This
-   * applies, for example, to the
-   * Nedelec or Raviart-Thomas
-   * elements. In this case, a
-   * degree of freedom is counted
-   * in each component in which it
-   * is non-zero, so that the sum
-   * mentioned above is greater
-   * than the total number of
-   * degrees of freedom.
-   *
-   * This behavior can be switched
-   * off by the optional parameter
-   * <tt>vector_valued_once</tt>. If
-   * this is <tt>true</tt>, the
-   * number of components of a
-   * nonprimitive vector valued
-   * element is collected only in
-   * the first component. All other
-   * components will have a count
-   * of zero.
-   *
-   * The additional optional
-   * argument @p target_component
-   * allows for a re-sorting and
-   * grouping of components. To
-   * this end, it contains for each
-   * component the component number
-   * it shall be counted as. Having
-   * the same number entered
-   * several times sums up several
-   * components as the same. One of
-   * the applications of this
-   * argument is when you want to
-   * form block matrices and
-   * vectors, but want to pack
-   * several components into the
-   * same block (for example, when
-   * you have @p dim velocities
-   * and one pressure, to put all
-   * velocities into one block, and
-   * the pressure into another).
-   *
-   * The result is returned in @p
-   * dofs_per_component. Note that
-   * the size of @p
-   * dofs_per_component needs to be
-   * enough to hold all the indices
-   * specified in @p
-   * target_component. If this is
-   * not the case, an assertion is
-   * thrown. The indices not
-   * targeted by target_components
-   * are left untouched.
+   * Count how many degrees of freedom out of the total number belong
+   * to each component. If the number of components the finite element
+   * has is one (i.e. you only have one scalar variable), then the
+   * number in this component obviously equals the total number of
+   * degrees of freedom. Otherwise, the sum of the DoFs in all the
+   * components needs to equal the total number.
+   *
+   * However, the last statement does not hold true if the finite
+   * element is not primitive, i.e. some or all of its shape functions
+   * are non-zero in more than one vector component. This applies, for
+   * example, to the Nedelec or Raviart-Thomas elements. In this case,
+   * a degree of freedom is counted in each component in which it is
+   * non-zero, so that the sum mentioned above is greater than the
+   * total number of degrees of freedom.
+   *
+   * This behavior can be switched off by the optional parameter
+   * <tt>vector_valued_once</tt>. If this is <tt>true</tt>, the number
+   * of components of a nonprimitive vector valued element is
+   * collected only in the first component. All other components will
+   * have a count of zero.
+   *
+   * The additional optional argument @p target_component allows for a
+   * re-sorting and grouping of components. To this end, it contains
+   * for each component the component number it shall be counted
+   * as. Having the same number entered several times sums up several
+   * components as the same. One of the applications of this argument
+   * is when you want to form block matrices and vectors, but want to
+   * pack several components into the same block (for example, when
+   * you have @p dim velocities and one pressure, to put all
+   * velocities into one block, and the pressure into another).
+   *
+   * The result is returned in @p dofs_per_component. Note that the
+   * size of @p dofs_per_component needs to be enough to hold all the
+   * indices specified in @p target_component. If this is not the
+   * case, an assertion is thrown. The indices not targeted by
+   * target_components are left untouched.
    */
   template <class DH>
   void
@@ -2298,35 +1738,20 @@ namespace DoFTools
                             = std::vector<unsigned int>());
 
   /**
-   * Count the degrees of freedom
-   * in each block. This function
-   * is similar to
-   * count_dofs_per_component(),
-   * with the difference that the
-   * counting is done by
-   * blocks. See @ref GlossBlock
-   * "blocks" in the glossary for
-   * details. Again the vectors are
-   * assumed to have the correct
-   * size before calling this
-   * function. If this is not the
+   * Count the degrees of freedom in each block. This function is
+   * similar to count_dofs_per_component(), with the difference that
+   * the counting is done by blocks. See @ref GlossBlock "blocks" in
+   * the glossary for details. Again the vectors are assumed to have
+   * the correct size before calling this function. If this is not the
    * case, an assertion is thrown.
    *
-   * This function is used in the
-   * step-22,
-   * step-31, and
-   * step-32 tutorial
-   * programs.
-   *
-   * @pre The dofs_per_block
-   * variable has as many
-   * components as the finite
-   * element used by the
-   * dof_handler argument has
-   * blocks, or alternatively as
-   * many blocks as are enumerated
-   * in the target_blocks argument
-   * if given.
+   * This function is used in the step-22, step-31, and step-32
+   * tutorial programs.
+   *
+   * @pre The dofs_per_block variable has as many components as the
+   * finite element used by the dof_handler argument has blocks, or
+   * alternatively as many blocks as are enumerated in the
+   * target_blocks argument if given.
    */
   template <class DH>
   void
@@ -2336,11 +1761,8 @@ namespace DoFTools
                         = std::vector<unsigned int>());
 
   /**
-   * @deprecated See the previous
-   * function with the same name
-   * for a description. This
-   * function exists for
-   * compatibility with older
+   * @deprecated See the previous function with the same name for a
+   * description. This function exists for compatibility with older
    * versions only.
    */
   template <int dim, int spacedim>
@@ -2350,218 +1772,102 @@ namespace DoFTools
                             std::vector<unsigned int>  target_component) DEAL_II_DEPRECATED;
 
   /**
-   * This function can be used when
-   * different variables shall be
-   * discretized on different
-   * grids, where one grid is
-   * coarser than the other. This
-   * idea might seem nonsensical at
-   * first, but has reasonable
-   * applications in inverse
-   * (parameter estimation)
-   * problems, where there might
-   * not be enough information to
-   * recover the parameter on the
-   * same grid as the state
-   * variable; furthermore, the
-   * smoothness properties of state
-   * variable and parameter might
-   * not be too much related, so
-   * using different grids might be
-   * an alternative to using
-   * stronger regularization of the
+   * This function can be used when different variables shall be
+   * discretized on different grids, where one grid is coarser than
+   * the other. This idea might seem nonsensical at first, but has
+   * reasonable applications in inverse (parameter estimation)
+   * problems, where there might not be enough information to recover
+   * the parameter on the same grid as the state variable;
+   * furthermore, the smoothness properties of state variable and
+   * parameter might not be too much related, so using different grids
+   * might be an alternative to using stronger regularization of the
    * problem.
    *
-   * The basic idea of this
-   * function is explained in the
-   * following. Let us, for
-   * convenience, denote by
-   * ``parameter grid'' the coarser
-   * of the two grids, and by
-   * ``state grid'' the finer of
-   * the two. We furthermore assume
-   * that the finer grid can be
-   * obtained by refinement of the
-   * coarser one, i.e. the fine
-   * grid is at least as much
-   * refined as the coarse grid at
-   * each point of the
-   * domain. Then, each shape
-   * function on the coarse grid
-   * can be represented as a linear
-   * combination of shape functions
-   * on the fine grid (assuming
-   * identical ansatz
-   * spaces). Thus, if we
-   * discretize as usual, using
-   * shape functions on the fine
-   * grid, we can consider the
-   * restriction that the parameter
-   * variable shall in fact be
-   * discretized by shape functions
-   * on the coarse grid as a
-   * constraint. These constraints
-   * are linear and happen to have
-   * the form managed by the
-   * ``ConstraintMatrix'' class.
-   *
-   * The construction of these
-   * constraints is done as
-   * follows: for each of the
-   * degrees of freedom (i.e. shape
-   * functions) on the coarse grid,
-   * we compute its representation
-   * on the fine grid, i.e. how the
-   * linear combination of shape
-   * functions on the fine grid
-   * looks like that resembles the
-   * shape function on the coarse
-   * grid. From this information,
-   * we can then compute the
-   * constraints which have to hold
-   * if a solution of a linear
-   * equation on the fine grid
-   * shall be representable on the
-   * coarse grid. The exact
-   * algorithm how these
-   * constraints can be computed is
-   * rather complicated and is best
-   * understood by reading the
-   * source code, which contains
-   * many comments.
-   *
-   * Before explaining the use of
-   * this function, we would like
-   * to state that the total number
-   * of degrees of freedom used for
-   * the discretization is not
-   * reduced by the use of this
-   * function, i.e. even though we
-   * discretize one variable on a
-   * coarser grid, the total number
-   * of degrees of freedom is that
-   * of the fine grid. This seems
-   * to be counter-productive,
-   * since it does not give us a
-   * benefit from using a coarser
-   * grid. The reason why it may be
-   * useful to choose this approach
-   * nonetheless is three-fold:
-   * first, as stated above, there
-   * might not be enough
-   * information to recover a
-   * parameter on a fine grid,
-   * i.e. we chose to discretize it
-   * on the coarse grid not to save
-   * DoFs, but for other
-   * reasons. Second, the
-   * ``ConstraintMatrix'' includes
-   * the constraints into the
-   * linear system of equations, by
-   * which constrained nodes become
-   * dummy nodes; we may therefore
-   * exclude them from the linear
-   * algebra, for example by
-   * sorting them to the back of
-   * the DoF numbers and simply
-   * calling the solver for the
-   * upper left block of the matrix
-   * which works on the
-   * non-constrained nodes only,
-   * thus actually realizing the
-   * savings in numerical effort
-   * from the reduced number of
-   * actual degrees of freedom. The
-   * third reason is that for some
-   * or other reason we have chosen
-   * to use two different grids, it
-   * may be actually quite
-   * difficult to write a function
-   * that assembles the system
-   * matrix for finite element
-   * spaces on different grids;
-   * using the approach of
-   * constraints as with this
-   * function allows to use
-   * standard techniques when
-   * discretizing on only one grid
-   * (the finer one) without having
-   * to take care of the fact that
-   * one or several of the variable
-   * actually belong to different
-   * grids.
-   *
-   * The use of this function is as
-   * follows: it accepts as
-   * parameters two DoF Handlers,
-   * the first of which refers to
-   * the coarse grid and the second
-   * of which is the fine grid. On
-   * both, a finite element is
-   * represented by the DoF handler
-   * objects, which will usually
-   * have several components, which
-   * may belong to different finite
-   * elements. The second and
-   * fourth parameter of this
-   * function therefore state which
-   * variable on the coarse grid
-   * shall be used to restrict the
-   * stated component on the fine
-   * grid. Of course, the finite
-   * elements used for the
-   * respective components on the
-   * two grids need to be the
-   * same. An example may clarify
-   * this: consider the parameter
-   * estimation mentioned briefly
-   * above; there, on the fine grid
-   * the whole discretization is
-   * done, thus the variables are
-   * ``u'', ``q'', and the Lagrange
-   * multiplier ``lambda'', which
-   * are discretized using
-   * continuous linear, piecewise
-   * constant discontinuous, and
-   * continuous linear elements,
-   * respectively. Only the
-   * parameter ``q'' shall be
-   * represented on the coarse
-   * grid, thus the DoFHandler
-   * object on the coarse grid
-   * represents only one variable,
-   * discretized using piecewise
-   * constant discontinuous
-   * elements. Then, the parameter
-   * denoting the component on the
-   * coarse grid would be zero (the
-   * only possible choice, since
-   * the variable on the coarse
-   * grid is scalar), and one on
-   * the fine grid (corresponding
-   * to the variable ``q''; zero
-   * would be ``u'', two would be
-   * ``lambda''). Furthermore, an
-   * object of type IntergridMap
-   * is needed; this could in
-   * principle be generated by the
-   * function itself from the two
-   * DoFHandler objects, but since
-   * it is probably available
-   * anyway in programs that use
-   * this function, we shall use it
-   * instead of re-generating
-   * it. Finally, the computed
-   * constraints are entered into a
-   * variable of type
-   * ConstraintMatrix; the
-   * constraints are added,
-   * i.e. previous contents which
-   * may have, for example, be
-   * obtained from hanging nodes,
-   * are not deleted, so that you
-   * only need one object of this
-   * type.
+   * The basic idea of this function is explained in the
+   * following. Let us, for convenience, denote by ``parameter grid''
+   * the coarser of the two grids, and by ``state grid'' the finer of
+   * the two. We furthermore assume that the finer grid can be
+   * obtained by refinement of the coarser one, i.e. the fine grid is
+   * at least as much refined as the coarse grid at each point of the
+   * domain. Then, each shape function on the coarse grid can be
+   * represented as a linear combination of shape functions on the
+   * fine grid (assuming identical ansatz spaces). Thus, if we
+   * discretize as usual, using shape functions on the fine grid, we
+   * can consider the restriction that the parameter variable shall in
+   * fact be discretized by shape functions on the coarse grid as a
+   * constraint. These constraints are linear and happen to have the
+   * form managed by the ``ConstraintMatrix'' class.
+   *
+   * The construction of these constraints is done as follows: for
+   * each of the degrees of freedom (i.e. shape functions) on the
+   * coarse grid, we compute its representation on the fine grid,
+   * i.e. how the linear combination of shape functions on the fine
+   * grid looks like that resembles the shape function on the coarse
+   * grid. From this information, we can then compute the constraints
+   * which have to hold if a solution of a linear equation on the fine
+   * grid shall be representable on the coarse grid. The exact
+   * algorithm how these constraints can be computed is rather
+   * complicated and is best understood by reading the source code,
+   * which contains many comments.
+   *
+   * Before explaining the use of this function, we would like to
+   * state that the total number of degrees of freedom used for the
+   * discretization is not reduced by the use of this function,
+   * i.e. even though we discretize one variable on a coarser grid,
+   * the total number of degrees of freedom is that of the fine
+   * grid. This seems to be counter-productive, since it does not give
+   * us a benefit from using a coarser grid. The reason why it may be
+   * useful to choose this approach nonetheless is three-fold: first,
+   * as stated above, there might not be enough information to recover
+   * a parameter on a fine grid, i.e. we chose to discretize it on the
+   * coarse grid not to save DoFs, but for other reasons. Second, the
+   * ``ConstraintMatrix'' includes the constraints into the linear
+   * system of equations, by which constrained nodes become dummy
+   * nodes; we may therefore exclude them from the linear algebra, for
+   * example by sorting them to the back of the DoF numbers and simply
+   * calling the solver for the upper left block of the matrix which
+   * works on the non-constrained nodes only, thus actually realizing
+   * the savings in numerical effort from the reduced number of actual
+   * degrees of freedom. The third reason is that for some or other
+   * reason we have chosen to use two different grids, it may be
+   * actually quite difficult to write a function that assembles the
+   * system matrix for finite element spaces on different grids; using
+   * the approach of constraints as with this function allows to use
+   * standard techniques when discretizing on only one grid (the finer
+   * one) without having to take care of the fact that one or several
+   * of the variable actually belong to different grids.
+   *
+   * The use of this function is as follows: it accepts as parameters
+   * two DoF Handlers, the first of which refers to the coarse grid
+   * and the second of which is the fine grid. On both, a finite
+   * element is represented by the DoF handler objects, which will
+   * usually have several components, which may belong to different
+   * finite elements. The second and fourth parameter of this function
+   * therefore state which variable on the coarse grid shall be used
+   * to restrict the stated component on the fine grid. Of course, the
+   * finite elements used for the respective components on the two
+   * grids need to be the same. An example may clarify this: consider
+   * the parameter estimation mentioned briefly above; there, on the
+   * fine grid the whole discretization is done, thus the variables
+   * are ``u'', ``q'', and the Lagrange multiplier ``lambda'', which
+   * are discretized using continuous linear, piecewise constant
+   * discontinuous, and continuous linear elements, respectively. Only
+   * the parameter ``q'' shall be represented on the coarse grid, thus
+   * the DoFHandler object on the coarse grid represents only one
+   * variable, discretized using piecewise constant discontinuous
+   * elements. Then, the parameter denoting the component on the
+   * coarse grid would be zero (the only possible choice, since the
+   * variable on the coarse grid is scalar), and one on the fine grid
+   * (corresponding to the variable ``q''; zero would be ``u'', two
+   * would be ``lambda''). Furthermore, an object of type IntergridMap
+   * is needed; this could in principle be generated by the function
+   * itself from the two DoFHandler objects, but since it is probably
+   * available anyway in programs that use this function, we shall use
+   * it instead of re-generating it. Finally, the computed constraints
+   * are entered into a variable of type ConstraintMatrix; the
+   * constraints are added, i.e. previous contents which may have, for
+   * example, be obtained from hanging nodes, are not deleted, so that
+   * you only need one object of this type.
    */
   template <int dim, int spacedim>
   void
@@ -2574,26 +1880,16 @@ namespace DoFTools
 
 
   /**
-   * This function generates a
-   * matrix such that when a vector
-   * of data with as many elements
-   * as there are degrees of
-   * freedom of this component on
-   * the coarse grid is multiplied
-   * to this matrix, we obtain a
-   * vector with as many elements
-   * are there are global degrees
-   * of freedom on the fine
-   * grid. All the elements of the
-   * other components of the finite
-   * element fields on the fine
-   * grid are not touched.
-   *
-   * The output of this function is
-   * a compressed format that can
-   * be given to the @p reinit
-   * functions of the
-   * SparsityPattern ad
+   * This function generates a matrix such that when a vector of data
+   * with as many elements as there are degrees of freedom of this
+   * component on the coarse grid is multiplied to this matrix, we
+   * obtain a vector with as many elements are there are global
+   * degrees of freedom on the fine grid. All the elements of the
+   * other components of the finite element fields on the fine grid
+   * are not touched.
+   *
+   * The output of this function is a compressed format that can be
+   * given to the @p reinit functions of the SparsityPattern ad
    * SparseMatrix classes.
    */
   template <int dim, int spacedim>
@@ -2606,31 +1902,18 @@ namespace DoFTools
                                              std::vector<std::map<types::global_dof_index, float> > &transfer_representation);
 
   /**
-   * Create a mapping from degree
-   * of freedom indices to the
-   * index of that degree of
-   * freedom on the boundary. After
-   * this operation, <tt>mapping[dof]</tt>
-   * gives the index of the
-   * degree of freedom with global
-   * number @p dof in the list of
-   * degrees of freedom on the
-   * boundary.  If the degree of
-   * freedom requested is not on
-   * the boundary, the value of
-   * <tt>mapping[dof]</tt> is
-   * @p invalid_dof_index. This
-   * function is mainly used when
-   * setting up matrices and
-   * vectors on the boundary from
-   * the trial functions, which
-   * have global numbers, while the
-   * matrices and vectors use
-   * numbers of the trial functions
-   * local to the boundary.
-   *
-   * Prior content of @p mapping
-   * is deleted.
+   * Create a mapping from degree of freedom indices to the index of
+   * that degree of freedom on the boundary. After this operation,
+   * <tt>mapping[dof]</tt> gives the index of the degree of freedom
+   * with global number @p dof in the list of degrees of freedom on
+   * the boundary.  If the degree of freedom requested is not on the
+   * boundary, the value of <tt>mapping[dof]</tt> is @p
+   * invalid_dof_index. This function is mainly used when setting up
+   * matrices and vectors on the boundary from the trial functions,
+   * which have global numbers, while the matrices and vectors use
+   * numbers of the trial functions local to the boundary.
+   *
+   * Prior content of @p mapping is deleted.
    */
   template <class DH>
   void
@@ -2638,15 +1921,11 @@ namespace DoFTools
                                std::vector<types::global_dof_index>  &mapping);
 
   /**
-   * Same as the previous function,
-   * except that only those parts
-   * of the boundary are considered
-   * for which the boundary
-   * indicator is listed in the
-   * second argument.
+   * Same as the previous function, except that only those parts of
+   * the boundary are considered for which the boundary indicator is
+   * listed in the second argument.
    *
-   * See the general doc of this
-   * class for more information.
+   * See the general doc of this class for more information.
    *
    * @see @ref GlossBoundaryIndicator "Glossary entry on boundary indicators"
    */
@@ -2657,33 +1936,22 @@ namespace DoFTools
                                std::vector<types::global_dof_index>     &mapping);
 
   /**
-   * Return a list of support
-   * points (see this
-   * @ref GlossSupport "glossary entry")
-   * for all the degrees of
-   * freedom handled by this DoF
-   * handler object. This function,
-   * of course, only works if the
-   * finite element object used by
-   * the DoF handler object
-   * actually provides support
-   * points, i.e. no edge elements
-   * or the like. Otherwise, an
-   * exception is thrown.
-   *
-   * @pre The given array must have a
-   * length of as many elements as
+   * Return a list of support points (see this @ref GlossSupport
+   * "glossary entry") for all the degrees of freedom handled by this
+   * DoF handler object. This function, of course, only works if the
+   * finite element object used by the DoF handler object actually
+   * provides support points, i.e. no edge elements or the
+   * like. Otherwise, an exception is thrown.
+   *
+   * @pre The given array must have a length of as many elements as
    * there are degrees of freedom.
    *
-   * @note The precondition to this function
-   * that the output argument needs to have
-   * size equal to the total number of degrees
-   * of freedom makes this function
-   * unsuitable for the case that the given
-   * DoFHandler object derives from a
-   * parallel::distributed::Triangulation object.
-   * Consequently, this function will produce an
-   * error if called with such a DoFHandler.
+   * @note The precondition to this function that the output argument
+   * needs to have size equal to the total number of degrees of
+   * freedom makes this function unsuitable for the case that the
+   * given DoFHandler object derives from a
+   * parallel::distributed::Triangulation object.  Consequently, this
+   * function will produce an error if called with such a DoFHandler.
    */
   template <int dim, int spacedim>
   void
@@ -2745,33 +2013,20 @@ namespace DoFTools
 
 
   /**
-   * This is the opposite function
-   * to the one above. It generates
-   * a map where the keys are the
-   * support points of the degrees
-   * of freedom, while the values
-   * are the DoF indices. For a definition
-   * of support points, see this
-   * @ref GlossSupport "glossary entry".
-   *
-   * Since there is no natural
-   * order in the space of points
-   * (except for the 1d case), you
-   * have to provide a map with an
-   * explicitly specified
-   * comparator object. This
-   * function is therefore
-   * templatized on the comparator
-   * object. Previous content of
-   * the map object is deleted in
-   * this function.
-   *
-   * Just as with the function
-   * above, it is assumed that the
-   * finite element in use here
-   * actually supports the notion
-   * of support points of all its
-   * components.
+   * This is the opposite function to the one above. It generates a
+   * map where the keys are the support points of the degrees of
+   * freedom, while the values are the DoF indices. For a definition
+   * of support points, see this @ref GlossSupport "glossary entry".
+   *
+   * Since there is no natural order in the space of points (except
+   * for the 1d case), you have to provide a map with an explicitly
+   * specified comparator object. This function is therefore
+   * templatized on the comparator object. Previous content of the map
+   * object is deleted in this function.
+   *
+   * Just as with the function above, it is assumed that the finite
+   * element in use here actually supports the notion of support
+   * points of all its components.
    */
   template <class DH, class Comp>
   void
@@ -2780,19 +2035,13 @@ namespace DoFTools
                               std::map<Point<DH::space_dimension>, types::global_dof_index, Comp> &point_to_index_map);
 
   /**
-   * Map a coupling table from the
-   * user friendly organization by
-   * components to the organization
-   * by blocks. Specializations of
-   * this function for DoFHandler
-   * and hp::DoFHandler are
-   * required due to the different
-   * results of their finite
-   * element access.
+   * Map a coupling table from the user friendly organization by
+   * components to the organization by blocks. Specializations of this
+   * function for DoFHandler and hp::DoFHandler are required due to
+   * the different results of their finite element access.
    *
-   * The return vector will be
-   * initialized to the correct
-   * length inside this function.
+   * The return vector will be initialized to the correct length
+   * inside this function.
    */
   template <int dim, int spacedim>
   void
@@ -2801,16 +2050,14 @@ namespace DoFTools
                                std::vector<Table<2,Coupling> > &tables_by_block);
 
   /**
-   * Make a constraint matrix for the
-   * constraints that result from zero
-   * boundary values on the given boundary indicator.
+   * Make a constraint matrix for the constraints that result from
+   * zero boundary values on the given boundary indicator.
    *
-   * This function constrains all
-   * degrees of freedom on the given part of the
-   * boundary.
+   * This function constrains all degrees of freedom on the given part
+   * of the boundary.
    *
-   * A variant of this function with different arguments is used
-   * in step-36.
+   * A variant of this function with different arguments is used in
+   * step-36.
    *
    * @param dof The DoFHandler to work on.
    * @param boundary_indicator The indicator of that part of the boundary
@@ -2867,19 +2114,13 @@ namespace DoFTools
 
 
   /**
-   * Map a coupling table from the
-   * user friendly organization by
-   * components to the organization
-   * by blocks. Specializations of
-   * this function for DoFHandler
-   * and hp::DoFHandler are
-   * required due to the different
-   * results of their finite
-   * element access.
+   * Map a coupling table from the user friendly organization by
+   * components to the organization by blocks. Specializations of this
+   * function for DoFHandler and hp::DoFHandler are required due to
+   * the different results of their finite element access.
    *
-   * The return vector will be
-   * initialized to the correct
-   * length inside this function.
+   * The return vector will be initialized to the correct length
+   * inside this function.
    */
   template <int dim, int spacedim>
   void
@@ -2888,12 +2129,10 @@ namespace DoFTools
                                std::vector<Table<2,Coupling> > &tables_by_block);
 
   /**
-   * Given a finite element and a table how
-   * the vector components of it couple
-   * with each other, compute and return a
-   * table that describes how the
-   * individual shape functions couple with
-   * each other.
+   * Given a finite element and a table how the vector components of
+   * it couple with each other, compute and return a table that
+   * describes how the individual shape functions couple with each
+   * other.
    */
   template <int dim, int spacedim>
   Table<2,Coupling>
@@ -2901,40 +2140,45 @@ namespace DoFTools
                                           const Table<2,Coupling> &component_couplings);
 
   /**
-   * Same function as above for a
-   * collection of finite elements,
+   * Same function as above for a collection of finite elements,
    * returning a collection of tables.
    *
-   * The function currently treats
-   * DoFTools::Couplings::nonzero the same
-   * as DoFTools::Couplings::always .
+   * The function currently treats DoFTools::Couplings::nonzero the
+   * same as DoFTools::Couplings::always .
    */
   template <int dim, int spacedim>
   std::vector<Table<2,Coupling> >
   dof_couplings_from_component_couplings (const hp::FECollection<dim,spacedim> &fe,
                                           const Table<2,Coupling> &component_couplings);
   /**
-   * Exception
+   * @todo Write description
+   *
    * @ingroup Exceptions
    */
   DeclException0 (ExcFiniteElementsDontMatch);
   /**
-   * Exception
+   * @todo Write description
+   *
    * @ingroup Exceptions
    */
   DeclException0 (ExcGridNotCoarser);
   /**
+   * @todo Write description
+   *
    * Exception
    * @ingroup Exceptions
    */
   DeclException0 (ExcGridsDontMatch);
   /**
-   * Exception
+   * The ::DoFHandler or hp::DoFHandler was not initialized with a
+   * finite element. Please call DoFHandler::distribute_dofs() etc. first.
+   *
    * @ingroup Exceptions
    */
   DeclException0 (ExcNoFESelected);
   /**
-   * Exception
+   * @todo Write description
+   *
    * @ingroup Exceptions
    */
   DeclException0 (ExcInvalidBoundaryIndicator);

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.