From: bangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Date: Fri, 19 Jul 2013 16:04:26 +0000 (+0000)
Subject: Augment documentation.
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b47755f98708e882f1f4e3d2b62b450f4fb64da9;p=dealii-svn.git

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 ac781134dd..9e990e154e 100644
--- 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 41c2558ad3..c15be6032f 100644
--- 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;