From: Wolfgang Bangerth Date: Mon, 15 Oct 2018 04:05:37 +0000 (-0600) Subject: Document the various *_accessor typedefs at their source. X-Git-Tag: v9.1.0-rc1~613^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F7351%2Fhead;p=dealii.git 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 585aa54c01..638e98b535 100644 --- 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, 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 active 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 active 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 active 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 e3576577a4..4c2a37136a 100644 --- a/include/deal.II/grid/tria.h +++ b/include/deal.II/grid/tria.h @@ -1580,13 +1580,72 @@ public: using active_vertex_iterator = TriaActiveIterator>; - 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 active 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 active 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 active 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 6560d5646f..8c8859e9c9 100644 --- a/include/deal.II/hp/dof_handler.h +++ b/include/deal.II/hp/dof_handler.h @@ -176,16 +176,100 @@ namespace hp Iterators, 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 active 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 active 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 active 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; /**