From 4f6ed342a3b47a4ed40084a683a8b1f73819f812 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Sun, 14 Oct 2018 22:05:37 -0600 Subject: [PATCH] Document the various *_accessor typedefs at their source. --- include/deal.II/dofs/dof_handler.h | 90 +++++++++++++++++++++++++++++- include/deal.II/grid/tria.h | 65 ++++++++++++++++++++- include/deal.II/hp/dof_handler.h | 90 +++++++++++++++++++++++++++++- 3 files changed, 236 insertions(+), 9 deletions(-) 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; /** -- 2.39.5