Better document another batch of iterators.

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

diff --git a/deal.II/include/deal.II/distributed/tria.h b/deal.II/include/deal.II/distributed/tria.h
index 794846d24820de7e04f2311a3f7614019fabc311..e48384738c25ab0fb659f1b6e75d3e832776bc8e 100644 (file)
--- a/deal.II/include/deal.II/distributed/tria.h
+++ b/deal.II/include/deal.II/distributed/tria.h
@@ -331,7 +331,7 @@ namespace parallel
 
       /**
        * A typedef that is used to to identify
-       * see @ref GlossActive "active cell iterators". The
+       * @ref GlossActive "active cell iterators". The
        * concept of iterators is discussed at length in the
        * @ref Iterators "iterators documentation module".
        *

diff --git a/deal.II/include/deal.II/dofs/dof_handler.h b/deal.II/include/deal.II/dofs/dof_handler.h
index 5feae64959c235e8221713b4f92b64d8bbd633d8..7901770fea118488f9965cb4571773451b945c51 100644 (file)
--- a/deal.II/include/deal.II/dofs/dof_handler.h
+++ b/deal.II/include/deal.II/dofs/dof_handler.h
@@ -197,8 +197,57 @@ public:
   typedef typename ActiveSelector::hex_iterator         hex_iterator;
   typedef typename ActiveSelector::active_hex_iterator  active_hex_iterator;
 
+  /**
+   * A typedef that is used to to identify
+   * @ref GlossActive "active cell iterators". The
+   * concept of iterators is discussed at length in the
+   * @ref Iterators "iterators documentation module".
+   *
+   * The current typedef identifies active cells in a DoFHandler object.
+   * While the actual data type of the typedef is hidden behind a few layers
+   * of (unfortunately necessary) indirections, it is in essence
+   * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator
+   * class works like a pointer to active objects that when you
+   * dereference it yields an object of type DoFCellAccessor.
+   * DoFCellAccessor is a class that identifies properties that
+   * are specific to cells in a DoFHandler, but it is derived
+   * (and consequently inherits) from both DoFAccessor, TriaCellAccessor
+   * and TriaAccessor that describe
+   * what you can ask of more general objects (lines, faces, as
+   * well as cells) in a triangulation and DoFHandler objects.
+   *
+   * @ingroup Iterators
+   */
   typedef typename ActiveSelector::active_cell_iterator active_cell_iterator;
 
+  /**
+   * A typedef that is used to to identify cell iterators. The
+   * concept of iterators is discussed at length in the
+   * @ref Iterators "iterators documentation module".
+   *
+   * The current typedef identifies cells in a DoFHandler object. Some
+   * of these cells may in fact be active (see @ref GlossActive "active cell iterators")
+   * in which case they can in fact be asked for the degrees of freedom
+   * that live on them. On the other hand, if the cell is not active,
+   * any such query will result in an error. Note that this is what distinguishes
+   * this typedef from the level_cell_iterator typedef.
+   *
+   * While the actual data type of the typedef is hidden behind a few layers
+   * of (unfortunately necessary) indirections, it is in essence
+   * TriaIterator<DoFCellAccessor>. The TriaIterator
+   * class works like a pointer to objects that when you
+   * dereference it yields an object of type DoFCellAccessor.
+   * DoFCellAccessor is a class that identifies properties that
+   * are specific to cells in a DoFHandler, but it is derived
+   * (and consequently inherits) from both DoFAccessor, TriaCellAccessor
+   * and TriaAccessor that describe
+   * what you can ask of more general objects (lines, faces, as
+   * well as cells) in a triangulation and DoFHandler objects.
+   *
+   * @ingroup Iterators
+   */
+  typedef typename ActiveSelector::cell_iterator        cell_iterator;
+
   typedef typename ActiveSelector::face_iterator        face_iterator;
   typedef typename ActiveSelector::active_face_iterator active_face_iterator;
 
@@ -208,7 +257,6 @@ public:
   typedef typename LevelSelector::cell_iterator         level_cell_iterator;
   typedef typename LevelSelector::face_iterator         level_face_iterator;
 
-  typedef typename ActiveSelector::cell_iterator        cell_iterator;
 
   /**
    * Alias the @p FunctionMap type

diff --git a/deal.II/include/deal.II/hp/dof_handler.h b/deal.II/include/deal.II/hp/dof_handler.h
index 8b0c2b1ace78a288f534d71d405a0194316e2a9c..e044edfa931ded176972e31b2e3c6e911eb55347 100644 (file)
--- a/deal.II/include/deal.II/hp/dof_handler.h
+++ b/deal.II/include/deal.II/hp/dof_handler.h
@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------
 // $Id$
 //
-// Copyright (C) 2005 - 2013 by the deal.II authors
+// Copyright (C) 2005 - 2014 by the deal.II authors
 //
 // This file is part of the deal.II library.
 //
@@ -95,19 +95,67 @@ namespace hp
     typedef typename ActiveSelector::hex_iterator         hex_iterator;
     typedef typename ActiveSelector::active_hex_iterator  active_hex_iterator;
 
+    /**
+     * A typedef that is used to to identify
+     * @ref GlossActive "active cell iterators". The
+     * concept of iterators is discussed at length in the
+     * @ref Iterators "iterators documentation module".
+     *
+     * The current typedef identifies active cells in a hp::DoFHandler object.
+     * While the actual data type of the typedef is hidden behind a few layers
+     * of (unfortunately necessary) indirections, it is in essence
+     * TriaActiveIterator<DoFCellAccessor>. The TriaActiveIterator
+     * class works like a pointer to active objects that when you
+     * dereference it yields an object of type DoFCellAccessor.
+     * DoFCellAccessor is a class that identifies properties that
+     * are specific to cells in a DoFHandler, but it is derived
+     * (and consequently inherits) from both DoFAccessor, TriaCellAccessor
+     * and TriaAccessor that describe
+     * what you can ask of more general objects (lines, faces, as
+     * well as cells) in a triangulation and hp::DoFHandler objects.
+     *
+     * @ingroup Iterators
+     */
     typedef typename ActiveSelector::active_cell_iterator active_cell_iterator;
 
+    typedef typename LevelSelector::cell_iterator         level_cell_iterator;
+
+    /**
+     * A typedef that is used to to identify cell iterators. The
+     * concept of iterators is discussed at length in the
+     * @ref Iterators "iterators documentation module".
+     *
+     * The current typedef identifies cells in a DoFHandler object. Some
+     * of these cells may in fact be active (see @ref GlossActive "active cell iterators")
+     * in which case they can in fact be asked for the degrees of freedom
+     * that live on them. On the other hand, if the cell is not active,
+     * any such query will result in an error. Note that this is what distinguishes
+     * this typedef from the level_cell_iterator typedef.
+     *
+     * While the actual data type of the typedef is hidden behind a few layers
+     * of (unfortunately necessary) indirections, it is in essence
+     * TriaIterator<DoFCellAccessor>. The TriaIterator
+     * class works like a pointer to objects that when you
+     * dereference it yields an object of type DoFCellAccessor.
+     * DoFCellAccessor is a class that identifies properties that
+     * are specific to cells in a DoFHandler, but it is derived
+     * (and consequently inherits) from both DoFAccessor, TriaCellAccessor
+     * and TriaAccessor that describe
+     * what you can ask of more general objects (lines, faces, as
+     * well as cells) in a triangulation and DoFHandler objects.
+     *
+     * @ingroup Iterators
+     */
+    typedef level_cell_iterator                           cell_iterator;
+
     typedef typename ActiveSelector::face_iterator        face_iterator;
     typedef typename ActiveSelector::active_face_iterator active_face_iterator;
 
     typedef typename LevelSelector::CellAccessor          level_cell_accessor;
     typedef typename LevelSelector::FaceAccessor          level_face_accessor;
 
-    typedef typename LevelSelector::cell_iterator         level_cell_iterator;
     typedef typename LevelSelector::face_iterator         level_face_iterator;
 
-    typedef level_cell_iterator                           cell_iterator;
-
     /**
      * Alias the @p FunctionMap type
      * declared elsewhere.
@@ -862,7 +910,7 @@ namespace hp
      */
     std::vector<types::global_dof_index>      vertex_dofs_offsets;
 
-    std::vector<MGVertexDoFs> mg_vertex_dofs;
+    std::vector<MGVertexDoFs> mg_vertex_dofs;  // we should really remove this field!
 
     /**
      * Array to store the