Merge pull request #1370 from chleh/improve-docu

Started writing some docu.

Documentation/ProjectFile/process/convergence_criterion/Residual/t_reltol.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/convergence_criterion/i_convergence_criterion.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/convergence_criterion/t_type.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/secondary_variables/i_secondary_variables.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/secondary_variables/secondary_variable/a_internal_name.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/secondary_variables/secondary_variable/a_output_name.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/secondary_variables/secondary_variable/a_sink_arg.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/secondary_variables/secondary_variable/a_source_fct.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/secondary_variables/secondary_variable/a_type.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/secondary_variables/secondary_variable/i_secondary_variable.md

+\ogs_missing_documentation

Documentation/ProjectFile/process/secondary_variables/secondary_variable/t_plug.md

+\ogs_missing_documentation

NumLib/ODESolver/ConvergenceCriterionDeltaX.cpp

@@ -54,11 +54,15 @@ void ConvergenceCriterionDeltaX::checkDeltaX(const GlobalVector& minus_delta_x,
 std::unique_ptr<ConvergenceCriterionDeltaX> createConvergenceCriterionDeltaX(
     const BaseLib::ConfigTree& config)
 {
+    //! \ogs_file_param{process__convergence_criterion__type}
     config.checkConfigParameter("type", "DeltaX");
 
+    //! \ogs_file_param{process__convergence_criterion__DeltaX__abstol}
     auto abstol = config.getConfigParameterOptional<double>("abstol");
+    //! \ogs_file_param{process__convergence_criterion__DeltaX__reltol}
     auto reltol = config.getConfigParameterOptional<double>("reltol");
     auto const norm_type_str =
+        //! \ogs_file_param{process__convergence_criterion__DeltaX__norm_type}
         config.getConfigParameter<std::string>("norm_type");
     auto const norm_type = MathLib::convertStringToVecNormType(norm_type_str);
 

NumLib/ODESolver/ConvergenceCriterionPerComponentDeltaX.cpp

@@ -80,13 +80,17 @@ void ConvergenceCriterionPerComponentDeltaX::setDOFTable(
 std::unique_ptr<ConvergenceCriterionPerComponentDeltaX>
 createConvergenceCriterionPerComponentDeltaX(const BaseLib::ConfigTree& config)
 {
+    //! \ogs_file_param{process__convergence_criterion__type}
     config.checkConfigParameter("type", "PerComponentDeltaX");
 
     auto abstols =
+        //! \ogs_file_param{process__convergence_criterion__PerComponentDeltaX__abstols}
         config.getConfigParameterOptional<std::vector<double>>("abstols");
     auto reltols =
+        //! \ogs_file_param{process__convergence_criterion__PerComponentDeltaX__reltols}
         config.getConfigParameterOptional<std::vector<double>>("reltols");
     auto const norm_type_str =
+        //! \ogs_file_param{process__convergence_criterion__PerComponentDeltaX__norm_type}
         config.getConfigParameter<std::string>("norm_type");
 
     if ((!abstols) && (!reltols))

NumLib/ODESolver/ConvergenceCriterionPerComponentResidual.cpp

@@ -90,13 +90,17 @@ std::unique_ptr<ConvergenceCriterionPerComponentResidual>
 createConvergenceCriterionPerComponentResidual(
     const BaseLib::ConfigTree& config)
 {
+    //! \ogs_file_param{process__convergence_criterion__type}
     config.checkConfigParameter("type", "PerComponentResidual");
 
     auto abstols =
+        //! \ogs_file_param{process__convergence_criterion__PerComponentResidual__abstols}
         config.getConfigParameterOptional<std::vector<double>>("abstols");
     auto reltols =
+        //! \ogs_file_param{process__convergence_criterion__PerComponentResidual__reltols}
         config.getConfigParameterOptional<std::vector<double>>("reltols");
     auto const norm_type_str =
+        //! \ogs_file_param{process__convergence_criterion__PerComponentResidual__norm_type}
         config.getConfigParameter<std::string>("norm_type");
 
     if ((!abstols) && (!reltols))

NumLib/ODESolver/ConvergenceCriterionResidual.cpp

@@ -58,11 +58,15 @@ void ConvergenceCriterionResidual::checkResidual(const GlobalVector& residual)
 std::unique_ptr<ConvergenceCriterionResidual>
 createConvergenceCriterionResidual(const BaseLib::ConfigTree& config)
 {
+    //! \ogs_file_param{process__convergence_criterion__type}
     config.checkConfigParameter("type", "Residual");
 
+    //! \ogs_file_param{process__convergence_criterion__Residual__abstol}
     auto abstol = config.getConfigParameterOptional<double>("abstol");
+    //! \ogs_file_param{process__convergence_criterion__Residual__reltol}
     auto reltol = config.getConfigParameterOptional<double>("reltol");
     auto const norm_type_str =
+        //! \ogs_file_param{process__convergence_criterion__Residual__norm_type}
         config.getConfigParameter<std::string>("norm_type");
     auto const norm_type = MathLib::convertStringToVecNormType(norm_type_str);
 

NumLib/ODESolver/NonlinearSolver.cpp

@@ -319,6 +319,7 @@ createNonlinearSolver(GlobalLinearSolver& linear_solver,
     //! \ogs_file_param{prj__nonlinear_solvers__nonlinear_solver__max_iter}
     auto const max_iter = config.getConfigParameter<unsigned>("max_iter");
 
+    //! \ogs_file_param_special{prj__nonlinear_solvers__nonlinear_solver__Picard}
     if (type == "Picard") {
         auto const tag = NonlinearSolverTag::Picard;
         using ConcreteNLS = NonlinearSolver<tag>;

ProcessLib/Utils/ParseSecondaryVariables.cpp

@@ -20,24 +20,24 @@ void parseSecondaryVariables(
     NumLib::NamedFunctionCaller& named_function_caller)
 {
     auto sec_vars_config =
-        // \ogs_file_param{process__secondary_variables}
+        //! \ogs_file_param{process__secondary_variables}
         config.getConfigSubtreeOptional("secondary_variables");
     if (!sec_vars_config)
         return;
 
     for (auto sec_var_config :
-         // \ogs_file_param{process__secondary_variables__secondary_variable}
+         //! \ogs_file_param{process__secondary_variables__secondary_variable}
          sec_vars_config->getConfigSubtreeList("secondary_variable"))
     {
         auto const type =
-            // \ogs_file_attr{process__secondary_variables__secondary_variable__type}
+            //! \ogs_file_attr{process__secondary_variables__secondary_variable__type}
             sec_var_config.getConfigAttribute<std::string>("type");
 
         auto const internal_name =
-            // \ogs_file_attr{process__secondary_variables__secondary_variable__internal_name}
+            //! \ogs_file_attr{process__secondary_variables__secondary_variable__internal_name}
             sec_var_config.getConfigAttribute<std::string>("internal_name");
         auto const output_name =
-            // \ogs_file_attr{process__secondary_variables__secondary_variable__output_name}
+            //! \ogs_file_attr{process__secondary_variables__secondary_variable__output_name}
             sec_var_config.getConfigAttribute<std::string>("output_name");
 
         secondary_variables.addNameMapping(internal_name, output_name);
@@ -48,14 +48,14 @@ void parseSecondaryVariables(
             auto const& sink_fct = internal_name;
 
             for (auto const plug :
-                 // \ogs_file_param{process__secondary_variables__secondary_variable__plug}
+                 //! \ogs_file_param{process__secondary_variables__secondary_variable__plug}
                  sec_var_config.getConfigParameterList("plug"))
             {
                 auto const sink_arg =
-                    // \ogs_file_attr{process__secondary_variables__secondary_variable__sink_arg}
+                    //! \ogs_file_attr{process__secondary_variables__secondary_variable__sink_arg}
                     plug.getConfigAttribute<std::string>("sink_arg");
                 auto const source_fct =
-                    // \ogs_file_attr{process__secondary_variables__secondary_variable__source_fct}
+                    //! \ogs_file_attr{process__secondary_variables__secondary_variable__source_fct}
                     plug.getConfigAttribute<std::string>("source_fct");
 
                 named_function_caller.plug(sink_fct, sink_arg, source_fct);

scripts/doc/linked-xml-file.py

@@ -250,7 +250,7 @@ for k, v in map_tag_to_prj_files.items():
 
 for k, v in map_attr_to_prj_files.items():
     map_attr_to_prj_files[k] = list(v)
-    documented_tags_attrs.discard((k, True))
+    documented_tags_attrs.discard((k, False))
 
 with open(os.path.join(docauxdir, "tested-parameters-cache.json"), "w") as fh:
     json.dump({ "tags": map_tag_to_prj_files, "attributes": map_attr_to_prj_files }, \