#9 Doxygen: fixing missing doxygen documentation in VariationalFormulation...

#9 Doxygen: fixing missing doxygen documentation in VariationalFormulation base class. Also introduce a generic documentation for TimeManager.

HappyHeart.xcodeproj/project.pbxproj

@@ -4880,6 +4880,7 @@
 		BE70B2541C522001000936BC /* MatchDofInNumberingSubset.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; name = MatchDofInNumberingSubset.cpp; path = Sources/Operators/Miscellaneous/MatchDofInNumberingSubset.cpp; sourceTree = "<group>"; };
 		BE70B2551C522001000936BC /* MatchDofInNumberingSubset.hpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.h; name = MatchDofInNumberingSubset.hpp; path = Sources/Operators/Miscellaneous/MatchDofInNumberingSubset.hpp; sourceTree = "<group>"; };
 		BE70B2561C522001000936BC /* MatchDofInNumberingSubset.hxx */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.h; name = MatchDofInNumberingSubset.hxx; path = Sources/Operators/Miscellaneous/MatchDofInNumberingSubset.hxx; sourceTree = "<group>"; };
+		BE765F041CB5AC9A004B17FC /* TimeManager.doxygen */ = {isa = PBXFileReference; explicitFileType = sourcecode.cpp.h; fileEncoding = 4; path = TimeManager.doxygen; sourceTree = "<group>"; };
 		BE768E7B1B8325BB009B24CB /* ManualParsing.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = ManualParsing.cpp; sourceTree = "<group>"; };
 		BE768E7C1B8325BB009B24CB /* ManualParsing.hpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.h; path = ManualParsing.hpp; sourceTree = "<group>"; };
 		BE768E821B832795009B24CB /* Subtuple.hpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.h; path = Subtuple.hpp; sourceTree = "<group>"; };
@@ -7842,6 +7843,7 @@
 		BE63C15E1B21DE7900978D05 /* TimeManager */ = {
 			isa = PBXGroup;
 			children = (
+				BE765F041CB5AC9A004B17FC /* TimeManager.doxygen */,
 				BE63C15F1B21DE7900978D05 /* TimeManager.cpp */,
 				BE63C1601B21DE7900978D05 /* TimeManager.hpp */,
 				BE63C1611B21DE7900978D05 /* TimeManager.hxx */,

Sources/Core/TimeManager/TimeManager.doxygen

+/*!
+ * \class doxygen_hide_time_manager_arg
+ *
+ * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+ */
+
+
+/*!
+ * \class doxygen_hide_time_manager_accessor
+ *
+ * \brief Object in charge of keeping track of the time-related informations.
+ *
+ * \return Reference to the \a TimeManager.
+ */
\ No newline at end of file

Sources/Core/TimeManager/TimeManager.hpp

@@ -20,7 +20,7 @@ namespace HappyHeart
     
     
     /*!
-     * \brief Class in charge of managing the elaspsing of time within the simulation.
+     * \brief Class in charge of managing the elapsing of time within the simulation.
      *
      * \attention This is an abstract class; in your model you are probably seeking a TimeManagerInstance.
      *

Sources/FiniteElement/FiniteElementSpace/GodOfDof.hpp

@@ -665,18 +665,7 @@ namespace HappyHeart
     void AllocateGlobalVector(const GodOfDof& god_of_dof,
                               GlobalVector& vector);
 
-    
-    /*!
-     * \brief Init the DofProgramWiseIndexListPerVertexCoordIndex objects related to a given GodOfDof.
-     *
-     * Such an object is strongly related to a GodOfDof; upon reading the input parameter data file
-     * each of them can only be created by the GodOfDof to which it is related.
-     */
-//    template<class InputParameterDataT>
-//    void SetDofProgramWiseIndexListPerVertexCoordIndex(const InputParameterDataT& input_parameter_data,
-//                               const GodOfDof& god_of_dof)
-
-    
+        
     ///@} // \addtogroup
     
     

Sources/FormulationSolver/Crtp/VolumicAndSurfacicSource.hpp

@@ -27,8 +27,9 @@
 namespace HappyHeart
 {
     
-    enum class SourceType { volumic, surfacic };
     
+    //! Whether volumic or surfacic source is considered.
+    enum class SourceType { volumic, surfacic };
     
  
     namespace Crtp

Sources/FormulationSolver/VariationalFormulation.hpp

@@ -103,7 +103,7 @@ namespace HappyHeart
          * class, and this class knows this call must occur (it is already coded once and for all in its internals).
          *
          * \copydetails doxygen_hide_mpi_param
-         * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+         \copydetails doxygen_hide_time_manager_arg
          * \param[in] god_of_dof God of dof into which the formulation works.
          * \param[in] boundary_condition_list List of Dirichlet boundary conditions to take into account in the
          * variational formulation.
@@ -122,8 +122,10 @@ namespace HappyHeart
         //! Move constructor - deactivated.
         VariationalFormulation(VariationalFormulation&&) = delete;
         
-        //! Operator= - deactivated.
+        //! Copy assignation.
         VariationalFormulation& operator=(const VariationalFormulation&) = delete;
+        
+        //! Move assignation.
         VariationalFormulation& operator=(VariationalFormulation&&) = delete;
         
         
@@ -131,8 +133,6 @@ namespace HappyHeart
         
     public:
         
-        using matrix_block_definition_type =
-            std::pair<NumberingSubset::const_shared_ptr, NumberingSubset::const_shared_ptr>;
         
         /*!
          * \brief Performs the complete build of the object.
@@ -149,31 +149,50 @@ namespace HappyHeart
     public:
         
         /*!
+         * \class doxygen_hide_varf_solve_linear
+         *
          * \brief Perform a linear solve, using Petsc's KSP algorithm.
          *
          * This method does only the resolution itself; assembling or applying boundary conditions must be
          * done beforehand.
          *
          * \tparam IsFactorizedT If the same matrix has already been set up previously you should rather
-         * set this parameter to yes to avoid a call to Petsc's KSPSetOperators() and to reuse the already 
+         * set this parameter to yes to avoid a call to Petsc's KSPSetOperators() and to reuse the already
          * computed factorized matrix. However, in doubt (acceptable during development process...), the safe
          * option is 'no'.
          */
+        
+        /*!
+         *  \class doxygen_hide_varf_solve_numbering_subset_arg
+         *
+         * \param[in] row_numbering_subset Solver will be applied on the system matrix which row is given by this
+         * numbering subset.
+         * \param[in] col_numbering_subset Solver will be applied on the system matrix which column is given by this
+         * numbering subset, and with the RHS pointed out by this very same numbering subset.
+         */
+        
+        
+        /*!
+         * \copydoc doxygen_hide_varf_solve_linear
+         *
+         * \copydetails doxygen_hide_varf_solve_numbering_subset_arg
+         */
         template<IsFactorized IsFactorizedT>
         void SolveLinear(const NumberingSubset& row_numbering_subset,
                          const NumberingSubset& col_numbering_subset);
         
         
         /*!
-         * \brief Perform a linear solve, using Petsc's KSP algorithm.
+         * \copydoc doxygen_hide_varf_solve_linear
          *
-         * This method does only the resolution itself; assembling or applying boundary conditions must be
-         * done beforehand.
+         * This version is broader that the overload above, as you can give your own matrix and vector rather than
+         * using the so-called 'system' ones.
+         *
+         * \param[in] matrix Matrix part of the equation to solve (e.g. A in 'A X = R').
+         * \param[in] rhs Rhs part of the equation to solve (e.g. R in 'A X = R').
+         * \param[out] out Solution part of the equation to solve (e.g. X in 'A X = R'). It must have been properly
+         * allocated; only the content is filled.
          *
-         * \tparam IsFactorizedT If the same matrix has already been set up previously you should rather
-         * set this parameter to yes to avoid a call to Petsc's KSPSetOperators() and to reuse the already
-         * computed factorized matrix. However, in doubt (acceptable during development process...), the safe
-         * option is 'no'.
          */
         template<IsFactorized IsFactorizedT>
         void SolveLinear(const GlobalMatrix& matrix,
@@ -184,12 +203,14 @@ namespace HappyHeart
         /*!
          * \brief Perform a non-linear solve, using Petsc's Newton SNES algorithm.
          *
-         * \internal <b><tt>[internal]</tt></b> This method requires that ImplementSnesFunction(), ImplementSnesJacobian() and
-         * ImplementSnesViewer() all returns something that is not nullptr.
+         * \internal <b><tt>[internal]</tt></b> This method requires that ImplementSnesFunction(), ImplementSnesJacobian()
+         * and ImplementSnesViewer() all returns something that is not nullptr.
          *
          * As assembling and application of boundary conditions may occur at each Newton iteration, these
          * operations are often handled within the snes function given by ImplementSnesFunction(); so it differs
          * from SolveLinear() on that matter.
+         *
+         * \copydetails doxygen_hide_varf_solve_numbering_subset_arg
          */
         void SolveNonLinear(const NumberingSubset& row_numbering_subset,
                             const NumberingSubset& col_numbering_subset);
@@ -200,57 +221,151 @@ namespace HappyHeart
         /*!
          * \brief Apply essential boundary counditions.
          *
-         * \internal <b><tt>[internal]</tt></b> Natural boundary conditions are managed by dedicated operators (their 'naturalness' is fully
-         * used!)
+         * \internal <b><tt>[internal]</tt></b> Natural boundary conditions are managed by dedicated operators (their 
+         * 'naturalness' is fully used!)
          *
          * \tparam AppliedOnT Whether the essential boundary conditions are applied on matrix, vector or both.
+         *
+         * * \copydetails doxygen_hide_varf_solve_numbering_subset_arg
          */
         template<OperatorNS::Nature AppliedOnT>
         void ApplyEssentialBoundaryCondition(const NumberingSubset& row_numbering_subset,
                                              const NumberingSubset& col_numbering_subset);
         
-        // Print solution of the system solve.
-        void DebugPrintSolutionElasticWithOneUnknown(const NumberingSubset& numbering_subset, unsigned int verbose = 0) const;
+        /*!
+         * \brief Print min and max of the solution of the system solved (should be removed at some point).
+         *
+         * Works only when one unknown involved in the model.
+         *
+         * \param[in] numbering_subset Numbering subset onto which solution is described.
+         * \param[in] verbose Arbitrary value that decides what is printed or not. Thresholds are currently applied 
+         * at 9 and 19; this is really a remnant of the Felisce era.
+         */
+        void DebugPrintSolutionElasticWithOneUnknown(const NumberingSubset& numbering_subset,
+                                                     unsigned int verbose = 0) const;
         
-        //! Print solution extrema.
+        /*!
+         * \brief Print min and max of the solution of the system solved (should be removed at some point).
+         *
+         * \param[in] numbering_subset Numbering subset onto which solution is described.
+         */
         void DebugPrintSolution(const NumberingSubset& numbering_subset) const;
         
-        //! Write the solution.
-        void WriteSolution(const TimeManager& transient,
+        /*!
+         * \brief Write the solution in the output directory given in the input parameter file.
+         *
+         * \copydetails doxygen_hide_time_manager_arg
+         * \param[in] numbering_subset Numbering subset onto which solution is described.
+         */
+        void WriteSolution(const TimeManager& time_manager,
                            const NumberingSubset& numbering_subset) const;
         
+        
+        /*!
+         * \brief Print norm of the solution of the system solved (should be removed at some point).
+         *
+         * \param[in] numbering_subset Numbering subset onto which solution is described.
+         *
+         * SHould be removed at some point, especially considering proper tools to compute the norm based directly
+         * on Petsc have been introduced since.
+         */
         void DebugPrintNorm(const NumberingSubset& numbering_subset) const;
         
     public:
         
-        //! Access to the system matrix (A in A X = R).
+        
+        /*!
+         * \class doxygen_hide_varf_matrix_rowcol_numbering_subset
+         *
+         * \param[in] row_numbering_subset Matrix required is the one which row is described by this numbering subset.
+         * \param[in] col_numbering_subset Matrix required is the one which column is described by this numbering subset.
+         *
+         */
+        
+        /*!
+         * \class doxygen_hide_varf_matrix_rowcol_numbering_subset_and_return
+         *
+         * \copydetails doxygen_hide_varf_matrix_rowcol_numbering_subset
+         *
+         * \return Reference to the adequate system matrix.
+         */
+        
+     
+        /*!
+         * \brief Access to the system matrix (A in A X = R).
+         *
+         * \copydetails doxygen_hide_varf_matrix_rowcol_numbering_subset_and_return
+         */
         const GlobalMatrix& GetSystemMatrix(const NumberingSubset& row_numbering_subset,
                                             const NumberingSubset& col_numbering_subset) const;
         
-        //! Non constant access to the system matrix (A in A X = R).
+        /*!
+         * \brief Non constant access to the system matrix (A in A X = R).
+         *
+         * \copydetails doxygen_hide_varf_matrix_rowcol_numbering_subset_and_return
+         */
         GlobalMatrix& GetNonCstSystemMatrix(const NumberingSubset& row_numbering_subset,
                                             const NumberingSubset& col_numbering_subset);
         
-        //! Access to the system rhs (R in A X = R).
+        
+        /*!
+         * \class doxygen_hide_varf_vector_numbering_subset
+         *
+         * \param[in] numbering_subset Vector required is the one described by this numbering subset.
+         *
+         */
+        
+        /*!
+         * \class doxygen_hide_varf_vector_numbering_subset_and_return
+         *
+         * \copydetails doxygen_hide_varf_vector_numbering_subset
+         *
+         * \return Reference to the required vector.
+         */
+        
+        
+        
+        /*!
+         * \brief Access to the system rhs (R in A X = R).
+         *
+         * \copydetails doxygen_hide_varf_vector_numbering_subset_and_return
+         */
         const GlobalVector& GetSystemRhs(const NumberingSubset& numbering_subset) const;
 
-        //! Non constant access to the system rhs (R in A X = R).
+        /*!
+         * \brief Non constant access to the system rhs (R in A X = R).
+         *
+         * \copydetails doxygen_hide_varf_vector_numbering_subset_and_return
+         */
         GlobalVector& GetNonCstSystemRhs(const NumberingSubset& numbering_subset);
         
-
-        //! Access to the system rhs (X in A X = R).
+        /*!
+         * \brief Access to the system solution (X in A X = R).
+         *
+         * \copydetails doxygen_hide_varf_vector_numbering_subset_and_return
+         */
         const GlobalVector& GetSystemSolution(const NumberingSubset& numbering_subset) const;
         
-        //! Non constant access to the system rhs (X in A X = R).
+        /*!
+         * \brief Non constant access to the system solution (X in A X = R).
+         *
+         * \copydetails doxygen_hide_varf_vector_numbering_subset_and_return
+         */
         GlobalVector& GetNonCstSystemSolution(const NumberingSubset& numbering_subset);
         
-        //! Access to the object in charge of all transient parameters.
+        //! \copydoc doxygen_hide_time_manager_accessor
         const TimeManager& GetTimeManager() const;
      
         
     public:
         
-        //! Returns the output directory.
+        /*!
+         * \brief Returns the output directory into which solutions for \a numbering_subset are written.
+         *
+         * \param[in] numbering_subset \a NumberingSubset of the solution for which the output directory is requested.
+         *
+         * \return Path to the output directory into which solutions related to \a numbering_subset are written.
+         */
         std::string GetOutputDirectory(const NumberingSubset& numbering_subset) const;
         
         /*!
@@ -268,9 +383,11 @@ namespace HappyHeart
          * };
          *
          * ...
-         * GetQuadratureRuleSet(EnumUnderlyingType(Operators::mass));
+         * GetQuadratureRulePerTopologyType(EnumUnderlyingType(Operators::mass));
          *
          * \endcode
+         *
+         * \return Set of quadrature rules to use.
          */
         const quadrature_rule_per_topology_type& GetQuadratureRulePerTopologyType(unsigned int index = 0u) const noexcept;
         
@@ -281,11 +398,17 @@ namespace HappyHeart
         /*!
          * \brief Allocate the global matrix circonscribed by the two given numbering subsets.
          *
+         * This method is merely a wrapper over HappyHeart::AllocateGlobalMatrix() specialized for the system matrices
+         * within the \a VariationalFormulation.
+         *
+         * \copydetails doxygen_hide_varf_matrix_rowcol_numbering_subset
+         *
          * This is done once and for all during the initialisation phase of HappyHeart; no others should be
          * allocated in the core of the calculation.
          *
          * The data have already been reduced to processor-wise when this operation is performed (or for that
-         * matter when VariationalFormulation are expected to be built, i.e. typically in *ModelInstance*::SupplInitialize()).
+         * matter when VariationalFormulation are expected to be built, i.e. typically in 
+         * the method \a SupplInitialize() to define in each model instance).
          *
          * The pattern of the matrix is expected to have been computed in the GodOfDof before the reduction of data.
          *
@@ -297,6 +420,11 @@ namespace HappyHeart
         /*!
          * \brief Allocate the global vector circonscribed by the given numbering subset.
          *
+         * This method is merely a wrapper over HappyHeart::AllocateGlobalVector() specialized for the system vectors
+         * within the \a VariationalFormulation.
+         *
+         * \copydetails doxygen_hide_varf_vector_numbering_subset
+         *
          * This is done once and for all during the initialisation phase of HappyHeart; no others should be
          * allocated in the core of the calculation.
          *

Sources/FormulationSolver/VariationalFormulation.hxx

@@ -563,8 +563,6 @@ namespace HappyHeart
         
         const int Ncomponent_int = static_cast<int>(Ncomponent(unknown, mesh_dimension));
         
-
-        
         for (const auto& pair : felt_list_per_type)
         {
             const auto& ref_felt_space_list_ptr = pair.first;

Sources/ModelInstances/FSI_EI/SolidVariationalFormulationPolicy/Elasticity/Policy.hpp

@@ -78,7 +78,7 @@ namespace HappyHeart
                  * \brief Constructor.
                  *
                  * \copydetails doxygen_hide_mpi_param
-                 * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+                 \copydetails doxygen_hide_time_manager_arg
                  * \param[in] god_of_dof God of dof into which the formulation works.
                  * \param[in] main_felt_space Finite element space upon which the variational formulation apply.
                  * \param[in] solid_displacement Unknown considered; it should be a solid displacement.

Sources/ModelInstances/FSI_EI/SolidVariationalFormulationPolicy/Hyperelasticity/Policy.hpp

@@ -85,7 +85,7 @@ namespace HappyHeart
                  * \brief Constructor.
                  *
                  * \copydetails doxygen_hide_mpi_param
-                 * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+                 \copydetails doxygen_hide_time_manager_arg
                  * \param[in] god_of_dof God of dof into which the formulation works.
                  * \param[in] main_felt_space Finite element space upon which the variational formulation apply.
                  * \param[in] solid_displacement Unknown considered; it should be a solid displacement.

Sources/ModelInstances/FSI_EI/SolidVariationalFormulationPolicy/Hyperelasticity/VariationalFormulation.hpp

@@ -118,7 +118,7 @@ namespace HappyHeart
                  * \brief Constructor.
                  *
                  * \copydetails doxygen_hide_mpi_param
-                 * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+                 \copydetails doxygen_hide_time_manager_arg
                  * \param[in] god_of_dof God of dof into which the formulation works.
                  * \param[in] felt_space Finite element space upon which the variational formulation apply.
                  * \param[in] solid_displacement Unknown considered; it should be a solid displacement.

Sources/ModelInstances/Hyperelasticity/VariationalFormulationHyperElasticity.hpp

@@ -134,7 +134,7 @@ namespace HappyHeart
              * \brief Constructor.
              *
              * \copydetails doxygen_hide_mpi_param
-             * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+             \copydetails doxygen_hide_time_manager_arg
              * \param[in] god_of_dof God of dof into which the formulation works.
              * \param[in] main_felt_space Finite element space upon which the variational formulation apply.
              * \param[in] neumann_felt_space Finite element space upon which the Neumann condition apply.

Sources/ModelInstances/Legacy/FSI_EI_One_Mesh/SolidVariationalFormulationPolicy/Elasticity/Policy.hpp

@@ -78,7 +78,7 @@ namespace HappyHeart
                  * \brief Constructor.
                  *
                  * \copydetails doxygen_hide_mpi_param
-                 * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+                 \copydetails doxygen_hide_time_manager_arg
                  * \param[in] god_of_dof God of dof into which the formulation works.
                  * \param[in] main_felt_space Finite element space upon which the variational formulation apply.
                  * \param[in] solid_displacement Unknown considered; it should be a solid displacement.

Sources/ModelInstances/Legacy/FSI_EI_One_Mesh/SolidVariationalFormulationPolicy/Hyperelasticity/Policy.hpp

@@ -85,7 +85,7 @@ namespace HappyHeart
                  * \brief Constructor.
                  *
                  * \copydetails doxygen_hide_mpi_param
-                 * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+                 \copydetails doxygen_hide_time_manager_arg
                  * \param[in] god_of_dof God of dof into which the formulation works.
                  * \param[in] main_felt_space Finite element space upon which the variational formulation apply.
                  * \param[in] solid_displacement Unknown considered; it should be a solid displacement.

Sources/ModelInstances/Legacy/FSI_EI_One_Mesh/SolidVariationalFormulationPolicy/Hyperelasticity/VariationalFormulation.hpp

@@ -112,7 +112,7 @@ namespace HappyHeart
                  * \brief Constructor.
                  *
                  * \copydetails doxygen_hide_mpi_param
-                 * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+                 \copydetails doxygen_hide_time_manager_arg
                  * \param[in] god_of_dof God of dof into which the formulation works.
                  * \param[in] felt_space Finite element space upon which the variational formulation apply.
                  * \param[in] solid_displacement Unknown considered; it should be a solid displacement.

Sources/ModelInstances/UnderDevelopment/Poromechanics/SolidVariationalFormulationPolicy/Hyperelasticity/Policy.hpp

@@ -85,7 +85,7 @@ namespace HappyHeart
                  * \brief Constructor.
                  *
                  * \copydetails doxygen_hide_mpi_param
-                 * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+                 \copydetails doxygen_hide_time_manager_arg
                  * \param[in] god_of_dof God of dof into which the formulation works.
                  * \param[in] main_felt_space Finite element space upon which the variational formulation apply.
                  * \param[in] solid_displacement Unknown considered; it should be a solid displacement.

Sources/ModelInstances/UnderDevelopment/Poromechanics/SolidVariationalFormulationPolicy/Hyperelasticity/VariationalFormulation.hpp

@@ -119,7 +119,7 @@ namespace HappyHeart
                  * \brief Constructor.
                  *
                  * \copydetails doxygen_hide_mpi_param
-                 * \param[in] time_manager Object in charge of keeping track of the time-related informations.
+                 \copydetails doxygen_hide_time_manager_arg
                  * \param[in] god_of_dof God of dof into which the formulation works.
                  * \param[in] felt_space Finite element space upon which the variational formulation apply.
                  * \param[in] solid_displacement Unknown considered; it should be a solid displacement.