Document the various *_accessor typedefs at their source.

diff --git a/include/deal.II/dofs/dof_handler.h b/include/deal.II/dofs/dof_handler.h
index 585aa54c0109a6ef82e0418eb639146469c1f2af..638e98b535eef00536755d17bd87aaafbacd4ab2 100644 (file)
--- a/include/deal.II/dofs/dof_handler.h
+++ b/include/deal.II/dofs/dof_handler.h
@@ -205,16 +205,100 @@ class DoFHandler : public Subscriptor
     Iterators<DoFHandler<dim, spacedim>, true>;
 
 public:
+  /**
+   * An alias that is used to identify cell iterators in DoFHandler objects.
+   * The concept of iterators is discussed at length in the
+   * @ref Iterators "iterators documentation module".
+   *
+   * The current alias works, in essence, like the corresponding
+   * Triangulation::cell_accessor alias. However, it also makes available
+   * the member functions of DoFCellAccessor, in addition to the ones
+   * already available through the CellAccessor class.
+   *
+   * @ingroup Iterators
+   */
   using cell_accessor = typename ActiveSelector::CellAccessor;
+
+  /**
+   * An alias that is used to identify iterators that point to faces.
+   * The concept of iterators is discussed at length in the
+   * @ref Iterators "iterators documentation module".
+   *
+   * The current alias works, in essence, like the corresponding
+   * Triangulation::face_accessor alias. However, it also makes available
+   * the member functions of DoFAccessor, in addition to the ones
+   * already available through the TriaAccessor class.
+   *
+   * @ingroup Iterators
+   */
   using face_accessor = typename ActiveSelector::FaceAccessor;
 
-  using line_iterator        = typename ActiveSelector::line_iterator;
+  /**
+   * An alias that defines an iterator over the (one-dimensional) lines
+   * of a mesh. In one-dimensional meshes, these are the cells of the mesh,
+   * whereas in two-dimensional meshes the lines are the faces of cells.
+   *
+   * @ingroup Iterators
+   */
+  using line_iterator = typename ActiveSelector::line_iterator;
+
+  /**
+   * An alias that allows iterating over the <i>active</i> lines, i.e.,
+   * that subset of lines that have no children. In one-dimensional meshes,
+   * these are the cells of the mesh, whereas in two-dimensional
+   * meshes the lines are the faces of cells.
+   *
+   * In two- or three-dimensional meshes, lines without children (i.e.,
+   * the active lines) are part of at least one active cell. Each such line may
+   * additionally be a child of a line of a coarser cell adjacent to a cell
+   * that is active. (This coarser neighbor would then also be active.)
+   *
+   * @ingroup Iterators
+   */
   using active_line_iterator = typename ActiveSelector::active_line_iterator;
 
-  using quad_iterator        = typename ActiveSelector::quad_iterator;
+  /**
+   * An alias that defines an iterator over the (two-dimensional) quads
+   * of a mesh. In two-dimensional meshes, these are the cells of the mesh,
+   * whereas in three-dimensional meshes the quads are the faces of cells.
+   *
+   * @ingroup Iterators
+   */
+  using quad_iterator = typename ActiveSelector::quad_iterator;
+
+  /**
+   * An alias that allows iterating over the <i>active</i> quads, i.e.,
+   * that subset of quads that have no children. In two-dimensional meshes,
+   * these are the cells of the mesh, whereas in three-dimensional
+   * meshes the quads are the faces of cells.
+   *
+   * In three-dimensional meshes, quads without children (i.e.,
+   * the active quads) are faces of at least one active cell. Each such quad may
+   * additionally be a child of a quad face of a coarser cell adjacent to a cell
+   * that is active. (This coarser neighbor would then also be active.)
+   *
+   * @ingroup Iterators
+   */
   using active_quad_iterator = typename ActiveSelector::active_quad_iterator;
 
-  using hex_iterator        = typename ActiveSelector::hex_iterator;
+  /**
+   * An alias that defines an iterator over the (three-dimensional) hexes
+   * of a mesh. This iterator only makes sense in three-dimensional meshes,
+   * where hexes are the cells of the mesh.
+   *
+   * @ingroup Iterators
+   */
+  using hex_iterator = typename ActiveSelector::hex_iterator;
+
+  /**
+   * An alias that allows iterating over the <i>active</i> hexes of a mesh.
+   * This iterator only makes sense in three-dimensional meshes,
+   * where hexes are the cells of the mesh. Consequently, in these
+   * three-dimensional meshes, this iterator is equivalent to the
+   * @p active_cell_iterator alias.
+   *
+   * @ingroup Iterators
+   */
   using active_hex_iterator = typename ActiveSelector::active_hex_iterator;
 
   /**

diff --git a/include/deal.II/grid/tria.h b/include/deal.II/grid/tria.h
index e3576577a4e081dfa90cddcbb6ce088c405d3fdd..4c2a37136a8cfa4fdfddae57e94febcbd374fc5a 100644 (file)
--- a/include/deal.II/grid/tria.h
+++ b/include/deal.II/grid/tria.h
@@ -1580,13 +1580,72 @@ public:
   using active_vertex_iterator =
     TriaActiveIterator<dealii::TriaAccessor<0, dim, spacedim>>;
 
-  using line_iterator        = typename IteratorSelector::line_iterator;
+  /**
+   * An alias that defines an iterator over the (one-dimensional) lines
+   * of a mesh. In one-dimensional meshes, these are the cells of the mesh,
+   * whereas in two-dimensional meshes the lines are the faces of cells.
+   *
+   * @ingroup Iterators
+   */
+  using line_iterator = typename IteratorSelector::line_iterator;
+
+  /**
+   * An alias that allows iterating over the <i>active</i> lines, i.e.,
+   * that subset of lines that have no children. In one-dimensional meshes,
+   * these are the cells of the mesh, whereas in two-dimensional
+   * meshes the lines are the faces of cells.
+   *
+   * In two- or three-dimensional meshes, lines without children (i.e.,
+   * the active lines) are part of at least one active cell. Each such line may
+   * additionally be a child of a line of a coarser cell adjacent to a cell
+   * that is active. (This coarser neighbor would then also be active.)
+   *
+   * @ingroup Iterators
+   */
   using active_line_iterator = typename IteratorSelector::active_line_iterator;
 
-  using quad_iterator        = typename IteratorSelector::quad_iterator;
+  /**
+   * An alias that defines an iterator over the (two-dimensional) quads
+   * of a mesh. In two-dimensional meshes, these are the cells of the mesh,
+   * whereas in three-dimensional meshes the quads are the faces of cells.
+   *
+   * @ingroup Iterators
+   */
+  using quad_iterator = typename IteratorSelector::quad_iterator;
+
+  /**
+   * An alias that allows iterating over the <i>active</i> quads, i.e.,
+   * that subset of quads that have no children. In two-dimensional meshes,
+   * these are the cells of the mesh, whereas in three-dimensional
+   * meshes the quads are the faces of cells.
+   *
+   * In three-dimensional meshes, quads without children (i.e.,
+   * the active quads) are faces of at least one active cell. Each such quad may
+   * additionally be a child of a quad face of a coarser cell adjacent to a cell
+   * that is active. (This coarser neighbor would then also be active.)
+   *
+   * @ingroup Iterators
+   */
   using active_quad_iterator = typename IteratorSelector::active_quad_iterator;
 
-  using hex_iterator        = typename IteratorSelector::hex_iterator;
+  /**
+   * An alias that defines an iterator over the (three-dimensional) hexes
+   * of a mesh. This iterator only makes sense in three-dimensional meshes,
+   * where hexes are the cells of the mesh.
+   *
+   * @ingroup Iterators
+   */
+  using hex_iterator = typename IteratorSelector::hex_iterator;
+
+  /**
+   * An alias that allows iterating over the <i>active</i> hexes of a mesh.
+   * This iterator only makes sense in three-dimensional meshes,
+   * where hexes are the cells of the mesh. Consequently, in these
+   * three-dimensional meshes, this iterator is equivalent to the
+   * @p active_cell_iterator alias.
+   *
+   * @ingroup Iterators
+   */
   using active_hex_iterator = typename IteratorSelector::active_hex_iterator;
 
   /**

diff --git a/include/deal.II/hp/dof_handler.h b/include/deal.II/hp/dof_handler.h
index 6560d5646fd897dd23a88eb0ccc9ea63326aeb9a..8c8859e9c9b24f9b4fc4db15c43a7044c594667d 100644 (file)
--- a/include/deal.II/hp/dof_handler.h
+++ b/include/deal.II/hp/dof_handler.h
@@ -176,16 +176,100 @@ namespace hp
       Iterators<DoFHandler<dim, spacedim>, true>;
 
   public:
+    /**
+     * An alias that is used to identify cell iterators in DoFHandler objects.
+     * The concept of iterators is discussed at length in the
+     * @ref Iterators "iterators documentation module".
+     *
+     * The current alias works, in essence, like the corresponding
+     * Triangulation::cell_accessor alias. However, it also makes available
+     * the member functions of DoFCellAccessor, in addition to the ones
+     * already available through the CellAccessor class.
+     *
+     * @ingroup Iterators
+     */
     using cell_accessor = typename ActiveSelector::CellAccessor;
+
+    /**
+     * An alias that is used to identify iterators that point to faces.
+     * The concept of iterators is discussed at length in the
+     * @ref Iterators "iterators documentation module".
+     *
+     * The current alias works, in essence, like the corresponding
+     * Triangulation::face_accessor alias. However, it also makes available
+     * the member functions of DoFAccessor, in addition to the ones
+     * already available through the TriaAccessor class.
+     *
+     * @ingroup Iterators
+     */
     using face_accessor = typename ActiveSelector::FaceAccessor;
 
-    using line_iterator        = typename ActiveSelector::line_iterator;
+    /**
+     * An alias that defines an iterator over the (one-dimensional) lines
+     * of a mesh. In one-dimensional meshes, these are the cells of the mesh,
+     * whereas in two-dimensional meshes the lines are the faces of cells.
+     *
+     * @ingroup Iterators
+     */
+    using line_iterator = typename ActiveSelector::line_iterator;
+
+    /**
+     * An alias that allows iterating over the <i>active</i> lines, i.e.,
+     * that subset of lines that have no children. In one-dimensional meshes,
+     * these are the cells of the mesh, whereas in two-dimensional
+     * meshes the lines are the faces of cells.
+     *
+     * In two- or three-dimensional meshes, lines without children (i.e.,
+     * the active lines) are part of at least one active cell. Each such line
+     * may additionally be a child of a line of a coarser cell adjacent to a
+     * cell that is active. (This coarser neighbor would then also be active.)
+     *
+     * @ingroup Iterators
+     */
     using active_line_iterator = typename ActiveSelector::active_line_iterator;
 
-    using quad_iterator        = typename ActiveSelector::quad_iterator;
+    /**
+     * An alias that defines an iterator over the (two-dimensional) quads
+     * of a mesh. In two-dimensional meshes, these are the cells of the mesh,
+     * whereas in three-dimensional meshes the quads are the faces of cells.
+     *
+     * @ingroup Iterators
+     */
+    using quad_iterator = typename ActiveSelector::quad_iterator;
+
+    /**
+     * An alias that allows iterating over the <i>active</i> quads, i.e.,
+     * that subset of quads that have no children. In two-dimensional meshes,
+     * these are the cells of the mesh, whereas in three-dimensional
+     * meshes the quads are the faces of cells.
+     *
+     * In three-dimensional meshes, quads without children (i.e.,
+     * the active quads) are faces of at least one active cell. Each such quad
+     * may additionally be a child of a quad face of a coarser cell adjacent to
+     * a cell that is active. (This coarser neighbor would then also be active.)
+     *
+     * @ingroup Iterators
+     */
     using active_quad_iterator = typename ActiveSelector::active_quad_iterator;
 
-    using hex_iterator        = typename ActiveSelector::hex_iterator;
+    /**
+     * An alias that defines an iterator over the (three-dimensional) hexes
+     * of a mesh. This iterator only makes sense in three-dimensional meshes,
+     * where hexes are the cells of the mesh.
+     *
+     * @ingroup Iterators
+     */
+    using hex_iterator = typename ActiveSelector::hex_iterator;
+
+    /**
+     * An alias that allows iterating over the <i>active</i> hexes of a mesh.
+     * This iterator only makes sense in three-dimensional meshes,
+     * where hexes are the cells of the mesh. Consequently, in these
+     * three-dimensional meshes, this iterator is equivalent to the
+     * @p active_cell_iterator alias.
+     *
+     * @ingroup Iterators
+     */
     using active_hex_iterator = typename ActiveSelector::active_hex_iterator;
 
     /**