From 74bb9f4a81316c986f596fdbcaf26a9fd2adbe20 Mon Sep 17 00:00:00 2001
From: Timo Koch <timo.koch@iws.uni-stuttgart.de>
Date: Tue, 10 Jul 2018 20:15:10 +0200
Subject: [PATCH] [multidomain][doc] Improve multidomain documentation

---
 dumux/multidomain/couplingjacobianpattern.hh  |  9 +++--
 dumux/multidomain/fvassembler.hh              | 18 +++++++++-
 dumux/multidomain/newtonsolver.hh             |  3 +-
 dumux/multidomain/privarswitchnewtonsolver.hh |  2 ++
 dumux/multidomain/staggeredtraits.hh          |  5 ++-
 .../multidomain/subdomainboxlocalassembler.hh | 35 +++++++++++--------
 .../multidomain/subdomaincclocalassembler.hh  | 27 ++++++++------
 .../subdomainstaggeredlocalassembler.hh       | 34 +++++++++++-------
 dumux/multidomain/traits.hh                   |  1 +
 9 files changed, 92 insertions(+), 42 deletions(-)

diff --git a/dumux/multidomain/couplingjacobianpattern.hh b/dumux/multidomain/couplingjacobianpattern.hh
index 67f4cdf68a..bafd2842c8 100644
--- a/dumux/multidomain/couplingjacobianpattern.hh
+++ b/dumux/multidomain/couplingjacobianpattern.hh
@@ -19,7 +19,8 @@
 /*!
  * \file
  * \ingroup Assembly
- * \brief Helper function to generate Jacobian pattern for multidomain models
+ * \ingroup MultiDomain
+ * \brief Helper function to generate Jacobian pattern for multi domain models
  */
 #ifndef DUMUX_MUTLIDOMAIN_COUPLING_JACOBIAN_PATTERN_HH
 #define DUMUX_MUTLIDOMAIN_COUPLING_JACOBIAN_PATTERN_HH
@@ -32,6 +33,7 @@ namespace Dumux {
 
 /*!
  * \ingroup Assembly
+ * \ingroup MultiDomain
  * \brief Helper function to generate coupling Jacobian pattern (off-diagonal blocks)
  *        for cell-centered schemes
  */
@@ -70,6 +72,7 @@ Dune::MatrixIndexSet getCouplingJacobianPattern(const CouplingManager& couplingM
 
 /*!
  * \ingroup Assembly
+ * \ingroup MultiDomain
  * \brief Helper function to generate coupling Jacobian pattern (off-diagonal blocks)
  *        for the box scheme
  */
@@ -111,6 +114,7 @@ Dune::MatrixIndexSet getCouplingJacobianPattern(const CouplingManager& couplingM
 
 /*!
  * \ingroup Assembly
+ * \ingroup MultiDomain
  * \brief Helper function to generate coupling Jacobian pattern (off-diagonal blocks)
  *        for the staggered scheme (degrees of freedom on cell centers)
  */
@@ -137,6 +141,7 @@ Dune::MatrixIndexSet getCouplingJacobianPattern(const CouplingManager& couplingM
 
 /*!
  * \ingroup Assembly
+ * \ingroup MultiDomain
  * \brief Helper function to generate coupling Jacobian pattern (off-diagonal blocks)
  *        for the staggered scheme (degrees of freedom on faces)
  */
@@ -168,6 +173,6 @@ Dune::MatrixIndexSet getCouplingJacobianPattern(const CouplingManager& couplingM
     return pattern;
 }
 
-} // namespace Dumux
+} // end namespace Dumux
 
 #endif
diff --git a/dumux/multidomain/fvassembler.hh b/dumux/multidomain/fvassembler.hh
index bca3dad708..467f1f53a7 100644
--- a/dumux/multidomain/fvassembler.hh
+++ b/dumux/multidomain/fvassembler.hh
@@ -289,6 +289,9 @@ public:
         { res[domainId].resize(this->numDofs(domainId)); });
     }
 
+    /*!
+     * \brief Updates the grid variables with the given solution
+     */
     void updateGridVariables(const SolutionVector& curSol)
     {
         using namespace Dune::Hybrid;
@@ -296,6 +299,9 @@ public:
         { this->gridVariables(domainId).update(curSol[domainId]); });
     }
 
+    /*!
+     * \brief Resets the grid variables to the last time step
+     */
     void resetTimeStep(const SolutionVector& curSol)
     {
         using namespace Dune::Hybrid;
@@ -303,39 +309,49 @@ public:
         { this->gridVariables(domainId).resetTimeStep(curSol[domainId]); });
     }
 
+    //! the number of dof locations of domain i
     template<std::size_t i>
     std::size_t numDofs(Dune::index_constant<i> domainId) const
     { return std::get<domainId>(fvGridGeometryTuple_)->numDofs(); }
 
+    //! the problem of domain i
     template<std::size_t i>
     const auto& problem(Dune::index_constant<i> domainId) const
     { return *std::get<domainId>(problemTuple_); }
 
+    //! the finite volume grid geometry of domain i
     template<std::size_t i>
     const auto& fvGridGeometry(Dune::index_constant<i> domainId) const
     { return *std::get<domainId>(fvGridGeometryTuple_); }
 
+    //! the grid view of domain i
     template<std::size_t i>
     const auto& gridView(Dune::index_constant<i> domainId) const
     { return fvGridGeometry(domainId).gridView(); }
 
+    //! the grid variables of domain i
     template<std::size_t i>
     auto& gridVariables(Dune::index_constant<i> domainId)
     { return *std::get<domainId>(gridVariablesTuple_); }
 
+    //! the grid variables of domain i
     template<std::size_t i>
     const auto& gridVariables(Dune::index_constant<i> domainId) const
     { return *std::get<domainId>(gridVariablesTuple_); }
 
+    //! the coupling manager
     const CouplingManager& couplingManager() const
     { return *couplingManager_; }
 
+    //! the full Jacobian matrix
     JacobianMatrix& jacobian()
     { return *jacobian_; }
 
+    //! the full residual vector
     SolutionVector& residual()
     { return *residual_; }
 
+    //! the solution of the previous time step
     const SolutionVector& prevSol() const
     { return *prevSol_; }
 
@@ -487,6 +503,6 @@ private:
     std::shared_ptr<SolutionVector> residual_;
 };
 
-} // namespace Dumux
+} // end namespace Dumux
 
 #endif
diff --git a/dumux/multidomain/newtonsolver.hh b/dumux/multidomain/newtonsolver.hh
index b9e3bc5abb..8bb6a7919b 100644
--- a/dumux/multidomain/newtonsolver.hh
+++ b/dumux/multidomain/newtonsolver.hh
@@ -19,8 +19,8 @@
 /*!
  * \file
  * \ingroup Nonlinear
+ * \ingroup MultiDomain
  * \copydoc Dumux::MultiDomainNewtonSolver
- *
  */
 #ifndef DUMUX_MULTIDOMAIN_NEWTON_SOLVER_HH
 #define DUMUX_MULTIDOMAIN_NEWTON_SOLVER_HH
@@ -32,6 +32,7 @@ namespace Dumux {
 
 /*!
  * \ingroup Nonlinear
+ * \ingroup MultiDomain
  * \brief Newton sover for coupled problems
  */
 template <class Assembler, class LinearSolver, class CouplingManager,
diff --git a/dumux/multidomain/privarswitchnewtonsolver.hh b/dumux/multidomain/privarswitchnewtonsolver.hh
index 6397cb77ae..769307df07 100644
--- a/dumux/multidomain/privarswitchnewtonsolver.hh
+++ b/dumux/multidomain/privarswitchnewtonsolver.hh
@@ -18,6 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
+ * \ingroup Nonlinear
  * \ingroup MultiDomain
  * \copydoc Dumux::MultiDomainPriVarSwitchNewtonSolver
  */
@@ -34,6 +35,7 @@
 namespace Dumux {
 
 /*!
+ * \ingroup Nonlinear
  * \ingroup MultiDomain
  * \brief A newton solver that handles primary variable switches for multi domain problems
  */
diff --git a/dumux/multidomain/staggeredtraits.hh b/dumux/multidomain/staggeredtraits.hh
index 56a7ba876e..528beb2b8a 100644
--- a/dumux/multidomain/staggeredtraits.hh
+++ b/dumux/multidomain/staggeredtraits.hh
@@ -18,7 +18,8 @@
  *****************************************************************************/
 /*!
  * \file
- * \ingroup MixedDimension
+ * \ingroup MultiDomain
+ * \ingroup StaggeredDiscretization
  * \brief Linear algebra traits for mixeddimension problems
  */
 
@@ -44,6 +45,8 @@
 namespace Dumux {
 
 /*
+ * \ingroup MultiDomain
+ * \ingroup StaggeredDiscretization
  * \brief A traits class every multidomain model has to provide
  * \tparam SubDomainTypeTags the TypeTags of the sub domain problems
  * \note should export the types
diff --git a/dumux/multidomain/subdomainboxlocalassembler.hh b/dumux/multidomain/subdomainboxlocalassembler.hh
index 59b6e8df5b..629e156c0b 100644
--- a/dumux/multidomain/subdomainboxlocalassembler.hh
+++ b/dumux/multidomain/subdomainboxlocalassembler.hh
@@ -20,10 +20,8 @@
  * \file
  * \ingroup Assembly
  * \ingroup BoxDiscretization
- * \brief An assembler for Jacobian and residual contribution per element (box methods)
- * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
+ * \ingroup MultiDomain
+ * \brief An assembler for Jacobian and residual contribution per element (box methods) for multidomain problems
  */
 #ifndef DUMUX_MULTIDOMAIN_BOX_LOCAL_ASSEMBLER_HH
 #define DUMUX_MULTIDOMAIN_BOX_LOCAL_ASSEMBLER_HH
@@ -44,11 +42,13 @@ namespace Dumux {
 
 /*!
  * \ingroup Assembly
- * \ingroup CCDiscretization
- * \brief A base class for all local assemblers
+ * \ingroup BoxDiscretization
+ * \ingroup MultiDomain
+ * \brief A base class for all box local assemblers
  * \tparam id the id of the sub domain
  * \tparam TypeTag the TypeTag
  * \tparam Assembler the assembler type
+ * \tparam Implementation the actual implementation type
  */
 template<std::size_t id, class TypeTag, class Assembler, class Implementation>
 class SubDomainBoxLocalAssemblerBase : public FVLocalAssemblerBase<TypeTag, Assembler,Implementation, true>
@@ -234,10 +234,13 @@ private:
 
 /*!
  * \ingroup Assembly
- * \ingroup CCDiscretization
- * \brief A base class for all implicit local assemblers
+ * \ingroup BoxDiscretization
+ * \ingroup MultiDomain
+ * \brief A base class for all implicit box local assemblers
+ * \tparam id the id of the sub domain
  * \tparam TypeTag the TypeTag
  * \tparam Assembler the assembler type
+ * \tparam Implementation the actual implementation type
  */
 template<std::size_t id, class TypeTag, class Assembler, class Implementation>
 class SubDomainBoxLocalAssemblerImplicitBase : public SubDomainBoxLocalAssemblerBase<id, TypeTag, Assembler, Implementation>
@@ -286,19 +289,23 @@ public:
 
 /*!
  * \ingroup Assembly
- * \ingroup CCDiscretization
- * \brief An assembler for Jacobian and residual contribution per element (cell-centered methods)
+ * \ingroup BoxDiscretization
+ * \ingroup MultiDomain
+ * \brief The box scheme multidomain local assembler
+ * \tparam id the id of the sub domain
  * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
+ * \tparam Assembler the assembler type
+ * \tparam DM the numeric differentiation method
+ * \tparam implicit whether the assembler is explicit or implicit in time
  */
 template<std::size_t id, class TypeTag, class Assembler, DiffMethod DM = DiffMethod::numeric, bool implicit = true>
 class SubDomainBoxLocalAssembler;
 
 /*!
  * \ingroup Assembly
- * \ingroup CCDiscretization
- * \brief Cell-centered scheme local assembler using numeric differentiation and implicit time discretization
+ * \ingroup BoxDiscretization
+ * \ingroup MultiDomain
+ * \brief Box scheme multi domain local assembler using numeric differentiation and implicit time discretization
  */
 template<std::size_t id, class TypeTag, class Assembler>
 class SubDomainBoxLocalAssembler<id, TypeTag, Assembler, DiffMethod::numeric, /*implicit=*/true>
diff --git a/dumux/multidomain/subdomaincclocalassembler.hh b/dumux/multidomain/subdomaincclocalassembler.hh
index 6cba4a09f4..10102bb6be 100644
--- a/dumux/multidomain/subdomaincclocalassembler.hh
+++ b/dumux/multidomain/subdomaincclocalassembler.hh
@@ -20,10 +20,8 @@
  * \file
  * \ingroup Assembly
  * \ingroup CCDiscretization
- * \brief An assembler for Jacobian and residual contribution per element (cell-centered methods)
- * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
+ * \ingroup MultiDomain
+ * \brief A multidomain local assembler for Jacobian and residual contribution per element (cell-centered methods)
  */
 #ifndef DUMUX_MULTIDOMAIN_CC_LOCAL_ASSEMBLER_HH
 #define DUMUX_MULTIDOMAIN_CC_LOCAL_ASSEMBLER_HH
@@ -46,10 +44,12 @@ namespace Dumux {
 /*!
  * \ingroup Assembly
  * \ingroup CCDiscretization
- * \brief A base class for all local assemblers
+ * \ingroup MultiDomain
+ * \brief A base class for all multidomain local assemblers
  * \tparam id the id of the sub domain
  * \tparam TypeTag the TypeTag
  * \tparam Assembler the assembler type
+ * \tparam Implementation the actual assembler implementation
  */
 template<std::size_t id, class TypeTag, class Assembler, class Implementation>
 class SubDomainCCLocalAssemblerBase : public FVLocalAssemblerBase<TypeTag, Assembler,Implementation, true>
@@ -192,9 +192,12 @@ private:
 /*!
  * \ingroup Assembly
  * \ingroup CCDiscretization
- * \brief A base class for all implicit local assemblers
+ * \ingroup MultiDomain
+ * \brief A base class for all implicit multidomain local assemblers
+ * \tparam id the id of the sub domain
  * \tparam TypeTag the TypeTag
  * \tparam Assembler the assembler type
+ * \tparam Implementation the actual assembler implementation
  */
 template<std::size_t id, class TypeTag, class Assembler, class Implementation>
 class SubDomainCCLocalAssemblerImplicitBase : public SubDomainCCLocalAssemblerBase<id, TypeTag, Assembler, Implementation>
@@ -249,10 +252,13 @@ public:
 /*!
  * \ingroup Assembly
  * \ingroup CCDiscretization
- * \brief An assembler for Jacobian and residual contribution per element (cell-centered methods)
+ * \ingroup MultiDomain
+ * \brief The cell-centered scheme multidomain local assembler
+ * \tparam id the id of the sub domain
  * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
+ * \tparam Assembler the assembler type
+ * \tparam DM the numeric differentiation method
+ * \tparam implicit whether the assembler is explicit or implicit in time
  */
 template<std::size_t id, class TypeTag, class Assembler, DiffMethod DM = DiffMethod::numeric, bool implicit = true>
 class SubDomainCCLocalAssembler;
@@ -260,7 +266,8 @@ class SubDomainCCLocalAssembler;
 /*!
  * \ingroup Assembly
  * \ingroup CCDiscretization
- * \brief Cell-centered scheme local assembler using numeric differentiation and implicit time discretization
+ * \ingroup MultiDomain
+ * \brief Cell-centered scheme multidomain local assembler using numeric differentiation and implicit time discretization
  */
 template<std::size_t id, class TypeTag, class Assembler>
 class SubDomainCCLocalAssembler<id, TypeTag, Assembler, DiffMethod::numeric, /*implicit=*/true>
diff --git a/dumux/multidomain/subdomainstaggeredlocalassembler.hh b/dumux/multidomain/subdomainstaggeredlocalassembler.hh
index ec60c21793..15d1033a89 100644
--- a/dumux/multidomain/subdomainstaggeredlocalassembler.hh
+++ b/dumux/multidomain/subdomainstaggeredlocalassembler.hh
@@ -20,10 +20,8 @@
  * \file
  * \ingroup Assembly
  * \ingroup StaggeredDiscretization
- * \brief An assembler for Jacobian and residual contribution per element (staggered method)
- * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
+ * \ingroup MultiDomain
+ * \brief A multidomain assembler for Jacobian and residual contribution per element (staggered method)
  */
 #ifndef DUMUX_MULTIDOMAIN_STAGGERED_LOCAL_ASSEMBLER_HH
 #define DUMUX_MULTIDOMAIN_STAGGERED_LOCAL_ASSEMBLER_HH
@@ -45,10 +43,13 @@ namespace Dumux {
 /*!
  * \ingroup Assembly
  * \ingroup StaggeredDiscretization
- * \brief A base class for all local assemblers
+ * \ingroup MultiDomain
+ * \brief A base class for all multidomain local assemblers (staggered)
  * \tparam id the id of the sub domain
  * \tparam TypeTag the TypeTag
  * \tparam Assembler the assembler type
+ * \tparam Implementation the actual assembler implementation
+ * \tparam implicit whether the assembly is explicit or implicit in time
  */
 template<std::size_t id, class TypeTag, class Assembler, class Implementation, bool isImplicit = true>
 class SubDomainStaggeredLocalAssemblerBase : public FVLocalAssemblerBase<TypeTag, Assembler,Implementation, isImplicit>
@@ -370,10 +371,13 @@ private:
 
 /*!
  * \ingroup Assembly
- * \ingroup CCDiscretization
- * \brief A base class for all implicit local assemblers
+ * \ingroup StaggeredDiscretization
+ * \ingroup MultiDomain
+ * \brief A base class for all implicit multidomain local assemblers (staggered)
+ * \tparam id the id of the sub domain
  * \tparam TypeTag the TypeTag
  * \tparam Assembler the assembler type
+ * \tparam Implementation the actual assembler implementation
  */
 template<std::size_t id, class TypeTag, class Assembler, class Implementation>
 class SubDomainStaggeredLocalAssemblerImplicitBase : public SubDomainStaggeredLocalAssemblerBase<id, TypeTag, Assembler, Implementation>
@@ -411,19 +415,23 @@ public:
 
 /*!
  * \ingroup Assembly
- * \ingroup CCDiscretization
- * \brief An assembler for Jacobian and residual contribution per element (cell-centered methods)
+ * \ingroup StaggeredDiscretization
+ * \ingroup MultiDomain
+ * \brief The staggered multidomain local assembler
+ * \tparam id the id of the sub domain
  * \tparam TypeTag the TypeTag
- * \tparam DM the differentiation method to residual compute derivatives
- * \tparam implicit if to use an implicit or explicit time discretization
+ * \tparam Assembler the assembler type
+ * \tparam DM the numeric differentiation method
+ * \tparam implicit whether the assembler is explicit or implicit in time
  */
 template<std::size_t id, class TypeTag, class Assembler, DiffMethod DM = DiffMethod::numeric, bool implicit = true>
 class SubDomainStaggeredLocalAssembler;
 
 /*!
  * \ingroup Assembly
- * \ingroup CCDiscretization
- * \brief Cell-centered scheme local assembler using numeric differentiation and implicit time discretization
+ * \ingroup StaggeredDiscretization
+ * \ingroup MultiDomain
+ * \brief Staggered scheme local assembler using numeric differentiation and implicit time discretization
  */
 template<std::size_t id, class TypeTag, class Assembler>
 class SubDomainStaggeredLocalAssembler<id, TypeTag, Assembler, DiffMethod::numeric, /*implicit=*/true>
diff --git a/dumux/multidomain/traits.hh b/dumux/multidomain/traits.hh
index a80790c464..834679cca0 100644
--- a/dumux/multidomain/traits.hh
+++ b/dumux/multidomain/traits.hh
@@ -86,6 +86,7 @@ public:
 } // end namespace Detail
 
 /*
+ * \ingroup MultiDomain
  * \brief A traits class every multidomain model has to provide
  * \tparam SubDomainTypeTags the TypeTags of the sub domain problems
  * \note should export the types
-- 
GitLab