Update documentation a bit.

Reading through the documentation of some of the functions in DoFTools, there are a number of functions for which I can't quite figure out what exactly they do. This updates a couple of places, but more work remains. In particular, I have no idea from the description of what DoFTools::make_single_patch() does.

diff --git a/include/deal.II/dofs/dof_tools.h b/include/deal.II/dofs/dof_tools.h
index 23c785612fd88cbd4ac28e794976f046382a89a5..a6eff61964212b7333ca53a5bb3df731985afcaf 100644 (file)
--- a/include/deal.II/dofs/dof_tools.h
+++ b/include/deal.II/dofs/dof_tools.h
@@ -1660,9 +1660,9 @@ namespace DoFTools
   /**
    * 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
+   * associated with the corresponding cell. This data structure is a
    * 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
+   * many columns 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.
    *
@@ -1679,9 +1679,9 @@ namespace DoFTools
   /**
    * 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
+   * associated with the adjacent cells. This data structure is a 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
+   * columns 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
@@ -1731,10 +1731,13 @@ namespace DoFTools
    * 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
+   *
+   * The function thus creates a sparsity pattern which in each row
+   * (with rows corresponding to the cells on this level) lists the degrees of
+   * freedom associated to the cells that are the children of this
+   * cell. The DoF indices used here are level dof indices of a multilevel
+   * hierarchy, i.e., they may be associated with children that are
+   * not themselves active. 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)

diff --git a/source/dofs/dof_tools.cc b/source/dofs/dof_tools.cc
index 9015c86d69a77f5b614f8bbed5dae99fcccf04cf..6d089d45861782554c443681e4a32aa45930042f 100644 (file)
--- a/source/dofs/dof_tools.cc
+++ b/source/dofs/dof_tools.cc
@@ -1943,7 +1943,6 @@ namespace DoFTools
     Assert(level > 0 && level < dof_handler.get_tria().n_levels(),
            ExcIndexRange(level, 1, dof_handler.get_tria().n_levels()));
 
-    typename DH::level_cell_iterator cell;
     typename DH::level_cell_iterator pcell = dof_handler.begin(level-1);
     typename DH::level_cell_iterator endc = dof_handler.end(level-1);
 
@@ -1952,10 +1951,12 @@ namespace DoFTools
 
     for (unsigned int block = 0; pcell != endc; ++pcell)
       {
-        if (!pcell->has_children()) continue;
+        if (!pcell->has_children())
+          continue;
+
         for (unsigned int child=0; child<pcell->n_children(); ++child)
           {
-            cell = pcell->child(child);
+            const typename DH::level_cell_iterator cell = pcell->child(child);
 
             // For hp, only this line here would have to be replaced.
             const FiniteElement<DH::dimension> &fe = dof_handler.get_fe();