From: Wolfgang Bangerth Date: Tue, 21 May 2024 03:11:16 +0000 (-0600) Subject: Move namespace documentation to a better place. X-Git-Tag: v9.6.0-rc1~226^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=28faf86d683a7dcc687ea08e2175e06bd744afaf;p=dealii.git Move namespace documentation to a better place. --- diff --git a/include/deal.II/meshworker/local_results.h b/include/deal.II/meshworker/local_results.h index d23468e75e..fe0ddbbac6 100644 --- a/include/deal.II/meshworker/local_results.h +++ b/include/deal.II/meshworker/local_results.h @@ -34,128 +34,6 @@ DEAL_II_NAMESPACE_OPEN class BlockIndices; #endif -/** - * A collection of functions and classes for the mesh loops that are an - * ubiquitous part of each finite element program. - * - * The workhorse of this namespace is the loop() function, which implements a - * completely generic loop over all mesh cells. - * The loop() function depends on certain objects handed to it as arguments. - * These - * objects are of two types, @p info objects like DoFInfo and IntegrationInfo and - * function objects ("workers") that perform the local operations on cells, - * faces, and boundaries. - * - * Worker objects usually do two different jobs: first, they compute the local - * contribution of a cell or face to the global operation. Second, they - * assemble this local contribution into the global result, whether a - * functional, a form or a bilinear form. While the first job is particular to - * the problem being solved, the second is generic and only depends on the - * data structures. Therefore, base classes for workers assembling into global - * data are provided in the namespace Assembler. - * - *

Template argument types

- * - * The functions loop() and cell_action() take some arguments which are - * template parameters. Let us list the minimum requirements for these classes - * here and describe their properties. - * - *

ITERATOR

- * - * Any object that has an operator++() and points to a - * TriaAccessor or derived class. - * - *

DOFINFO

- * - * For an example implementation, refer to the class template DoFInfo. In - * order to work with cell_action() and loop(), DOFINFO needs to follow the - * following interface. - * @code - * class DOFINFO - * { - * private: - * DOFINFO(); - * DOFINFO(const DOFINFO&); - * DOFINFO& operator=(const DOFINFO&); - * - * public: - * template - * void reinit(const CellIt& c); - * - * template - * void reinit(const CellIt& c, const FaceIt& f, const unsigned int n); - * - * template - * void reinit(const CellIt& c, const FaceIt& f, const unsigned int n, - * const unsigned int s); - * - * friend template class DoFInfoBox; - * }; - * @endcode - * - * The three private functions are called by DoFInfoBox and should not be - * needed elsewhere. Obviously, they can be made public and then the friend - * declaration at the end may be missing. - * - * Additionally, you will need at least one public constructor. Furthermore - * DOFINFO is pretty useless yet: functions to interface with INTEGRATIONINFO - * and ASSEMBLER are needed. - * - * DOFINFO objects are gathered in a DoFInfoBox. In those objects, we store - * the results of local operations on each cell and its faces. Once all this - * information has been gathered, an ASSEMBLER is used to assemble it into - * global data. - * - *

INFOBOX

- * - * This type is exemplified in IntegrationInfoBox. It collects the input data - * for actions on cells and faces in INFO objects (see below). It provides the - * following interface to loop() and cell_action(): - * - * @code - * class INFOBOX - * { - * public: - * template - * void post_cell(const DoFInfoBox&); - * - * template - * void post_faces(const DoFInfoBox&); - * - * INFO cell; - * INFO boundary; - * INFO face; - * INFO subface; - * INFO neighbor; - * }; - * @endcode - * - * The main purpose of this class is gathering the five INFO objects, which - * contain the temporary data used on each cell or face. The requirements on - * these objects are listed below. Here, we only note that there need to be - * these 5 objects with the names listed above. - * - * The two function templates are call back functions called in cell_action(). - * The first is called before the faces are worked on, the second after the - * faces. - * - *

INFO

- * - * See IntegrationInfo for an example of these objects. They contain the - * temporary data needed on each cell or face to compute the result. The - * MeshWorker only uses the interface - * - * @code - * class INFO - * { - * public: - * void reinit(const DOFINFO& i); - * }; - * @endcode - * - * @ingroup MeshWorker - * @ingroup Integrators - */ namespace MeshWorker { /** diff --git a/include/deal.II/meshworker/loop.h b/include/deal.II/meshworker/loop.h index c8a2c97c18..3ce93481ad 100644 --- a/include/deal.II/meshworker/loop.h +++ b/include/deal.II/meshworker/loop.h @@ -75,6 +75,128 @@ namespace internal +/** + * A collection of functions and classes for the mesh loops that are an + * ubiquitous part of each finite element program. + * + * The workhorse of this namespace is the loop() function, which implements a + * completely generic loop over all mesh cells. + * The loop() function depends on certain objects handed to it as arguments. + * These + * objects are of two types, @p info objects like DoFInfo and IntegrationInfo and + * function objects ("workers") that perform the local operations on cells, + * faces, and boundaries. + * + * Worker objects usually do two different jobs: first, they compute the local + * contribution of a cell or face to the global operation. Second, they + * assemble this local contribution into the global result, whether a + * functional, a form or a bilinear form. While the first job is particular to + * the problem being solved, the second is generic and only depends on the + * data structures. Therefore, base classes for workers assembling into global + * data are provided in the namespace Assembler. + * + *

Template argument types

+ * + * The functions loop() and cell_action() take some arguments which are + * template parameters. Let us list the minimum requirements for these classes + * here and describe their properties. + * + *

ITERATOR

+ * + * Any object that has an operator++() and points to a + * TriaAccessor or derived class. + * + *

DOFINFO

+ * + * For an example implementation, refer to the class template DoFInfo. In + * order to work with cell_action() and loop(), DOFINFO needs to follow the + * following interface. + * @code + * class DOFINFO + * { + * private: + * DOFINFO(); + * DOFINFO(const DOFINFO&); + * DOFINFO& operator=(const DOFINFO&); + * + * public: + * template + * void reinit(const CellIt& c); + * + * template + * void reinit(const CellIt& c, const FaceIt& f, const unsigned int n); + * + * template + * void reinit(const CellIt& c, const FaceIt& f, const unsigned int n, + * const unsigned int s); + * + * friend template class DoFInfoBox; + * }; + * @endcode + * + * The three private functions are called by DoFInfoBox and should not be + * needed elsewhere. Obviously, they can be made public and then the friend + * declaration at the end may be missing. + * + * Additionally, you will need at least one public constructor. Furthermore + * DOFINFO is pretty useless yet: functions to interface with INTEGRATIONINFO + * and ASSEMBLER are needed. + * + * DOFINFO objects are gathered in a DoFInfoBox. In those objects, we store + * the results of local operations on each cell and its faces. Once all this + * information has been gathered, an ASSEMBLER is used to assemble it into + * global data. + * + *

INFOBOX

+ * + * This type is exemplified in IntegrationInfoBox. It collects the input data + * for actions on cells and faces in INFO objects (see below). It provides the + * following interface to loop() and cell_action(): + * + * @code + * class INFOBOX + * { + * public: + * template + * void post_cell(const DoFInfoBox&); + * + * template + * void post_faces(const DoFInfoBox&); + * + * INFO cell; + * INFO boundary; + * INFO face; + * INFO subface; + * INFO neighbor; + * }; + * @endcode + * + * The main purpose of this class is gathering the five INFO objects, which + * contain the temporary data used on each cell or face. The requirements on + * these objects are listed below. Here, we only note that there need to be + * these 5 objects with the names listed above. + * + * The two function templates are call back functions called in cell_action(). + * The first is called before the faces are worked on, the second after the + * faces. + * + *

INFO

+ * + * See IntegrationInfo for an example of these objects. They contain the + * temporary data needed on each cell or face to compute the result. The + * MeshWorker only uses the interface + * + * @code + * class INFO + * { + * public: + * void reinit(const DOFINFO& i); + * }; + * @endcode + * + * @ingroup MeshWorker + * @ingroup Integrators + */ namespace MeshWorker { /**