Augment documentation.

git-svn-id: https://svn.dealii.org/trunk@30060 0785d39b-7218-0410-832d-ea1e28bc413d

diff --git a/deal.II/include/deal.II/dofs/dof_handler.h b/deal.II/include/deal.II/dofs/dof_handler.h
index ac781134dd7d2b6c1121e4c0cf2b3a7ecedcfb77..9e990e154e8538055504cc79ffae30ce64bd28cf 100644 (file)
--- a/deal.II/include/deal.II/dofs/dof_handler.h
+++ b/deal.II/include/deal.II/dofs/dof_handler.h
@@ -516,8 +516,16 @@ public:
   cell_iterator        begin       (const unsigned int level = 0) const;
 
   /**
-   * Iterator to the first active
-   * cell on level @p level.
+   *  Iterator to the first active cell on level @p level. If the
+   *  given level does not contain any active cells (i.e., all cells
+   *  on this level are further refined, then this function returns
+   *  <code>end_active(level)</code> so that loops of the kind
+   *  @code
+   *    for (cell=dof_handler.begin_active(level); cell!=dof_handler.end_active(level); ++cell)
+   *      ...
+   *  @endcode
+   *  have zero iterations, as may be expected if there are no active
+   *  cells on this level.
    */
   active_cell_iterator begin_active(const unsigned int level = 0) const;
 
@@ -539,10 +547,8 @@ public:
   cell_iterator end (const unsigned int level) const;
 
   /**
-   * Return an active iterator
-   * which is the first iterator
-   * not on level. If @p level is
-   * the last level, then this
+   * Return an active iterator which is the first active iterator not
+   * on the given level. If @p level is the last level, then this
    * returns <tt>end()</tt>.
    */
   active_cell_iterator end_active (const unsigned int level) const;

diff --git a/deal.II/include/deal.II/grid/tria.h b/deal.II/include/deal.II/grid/tria.h
index 41c2558ad334b969d37775b204721c679b1bdd4b..c15be6032f00b5f14127e4ce48c0f61b30284fec 100644 (file)
--- a/deal.II/include/deal.II/grid/tria.h
+++ b/deal.II/include/deal.II/grid/tria.h
@@ -2612,8 +2612,16 @@ public:
   cell_iterator        begin       (const unsigned int level = 0) const;
 
   /**
-   *  Iterator to the first active
-   *  cell on level @p level.
+   *  Iterator to the first active cell on level @p level. If the
+   *  given level does not contain any active cells (i.e., all cells
+   *  on this level are further refined, then this function returns
+   *  <code>end_active(level)</code> so that loops of the kind
+   *  @code
+   *    for (cell=tria.begin_active(level); cell!=tria.end_active(level); ++cell)
+   *      ...
+   *  @endcode
+   *  have zero iterations, as may be expected if there are no active
+   *  cells on this level.
    */
   active_cell_iterator begin_active(const unsigned int level = 0) const;
 
@@ -2634,10 +2642,9 @@ public:
   cell_iterator        end (const unsigned int level) const;
 
   /**
-   * Return an active iterator which is the
-   * first iterator not on level. If @p level
-   * is the last level, then this returns
-   * <tt>end()</tt>.
+   * Return an active iterator which is the first active iterator not
+   * on the given level. If @p level is the last level, then this
+   * returns <tt>end()</tt>.
    */
   active_cell_iterator end_active (const unsigned int level) const;