[Doc] Add code documentation

dune/dorie/model/richards/modules.dox

@@ -51,7 +51,7 @@ in the @ref LocalOperators.
 ## Scaling
 
 The parameterizations implemented with the
-Dune::Dorie::RichardsParameterization interface are envisaged to be constant
+Dune::Dorie::Parameterization::Richards interface are envisaged to be constant
 throughout a single medium layer. However, one typically finds small-scale
 variations at the scale of interest. To account for these heterogeneities,
 several scaling schemes have been developed.
@@ -59,7 +59,8 @@ several scaling schemes have been developed.
 We implement scaling by storing a set of scaling factors for every grid cell on
 the coarsest level. Unlike the parameterization objects, these do not map
 to a certain medium but only the cell itself (and its child cells). The scaling
-factors are stored inside instances of Dune::Dorie::ScalingFactors.
+factors are stored inside instances of 
+Dune::Dorie::Parameterization::ScalingFactors.
 
 For evaluating scaling factor data, the Dune::Dorie::ScalingAdapter interface
 is used, which internally uses the Interpolator interface. These structures are

dune/dorie/model/richards/parameterization/factory.hh

@@ -3,6 +3,7 @@
 
 #include <dune/common/exceptions.hh>
 
+#include <dune/dorie/common/logging.hh>
 #include <dune/dorie/common/parameterization_factory.hh>
 #include <dune/dorie/model/richards/parameterization/interface.hh>
 #include <dune/dorie/model/richards/parameterization/mualem_van_genuchten.hh>
@@ -11,8 +12,8 @@ namespace Dune {
 namespace Dorie {
 namespace Parameterization {
 
-/**
- * @brief      Factory of richards parameters
+/*-------------------------------------------------------------------------*//**
+ * @brief      Factory of Transport parameters
  *
  * @tparam     Traits  The base traits
  */
@@ -35,9 +36,9 @@ struct RichardsFactory
             return std::make_shared<Parameterization::MualemVanGenuchten<Traits>>(name);
         }
         else {
-            log->error("Parameterization '{}' has unknown type '{}'",
+            log->error("Richards parameterization '{}' has unknown type '{}'",
                         name, type);
-            DUNE_THROW(IOError, "Unknown parameterization type");
+            DUNE_THROW(IOError, "Unknown Richards parameterization type");
         }
     }
 };

dune/dorie/model/transport/modules.dox

@@ -29,10 +29,27 @@
         \Gamma_D
     @f}
 
-    It implemented with a finite volume scheme and is written so that could
+    It's implemented with a finite volume scheme and is written so that could
     be run independently of the @ref RichardsModel model (e.g. with an
     stationary case), or fully coupled with a transient case with fluxes
     provided by the Dune::Dorie::RichardsSimulation class.
 @}
 
+@defgroup TransportParam Parameterization
+@{
+@ingroup TransportModel
+
+@brief Representing dispersion properties of the solute in the porous medium
+
+## Overview
+
+...
+
+Storing this data, providing grid-to-data mappings, and access to this data
+are tasks of the Dune::Dorie::TransportParameters interface, that is directly 
+used in the @ref LocalOperators.
+
+
+@}
+
 **/

dune/dorie/model/transport/parameterization/factory.hh

 #ifndef DUNE_DORIE_PARAM_TRANSPORT_FACTORY_HH
 #define DUNE_DORIE_PARAM_TRANSPORT_FACTORY_HH
 
+#include <dune/dorie/common/logging.hh>
 #include <dune/dorie/common/parameterization_factory.hh>
 #include <dune/dorie/model/transport/parameterization/interface.hh>
 #include <dune/dorie/model/transport/parameterization/hydrodynamic_dispersion/interface.hh>
@@ -24,9 +25,9 @@ namespace Dorie {
 namespace Parameterization {
 
 /*-------------------------------------------------------------------------*//**
- * @brief      { struct_description }
+ * @brief      Factory of Transport parameters
  *
- * @tparam     Traits  { description }
+ * @tparam     Traits  The base traits
  */
 template<class Traits>
 struct TransportFactory 
@@ -42,6 +43,8 @@ struct TransportFactory
       const YAML::Node& type_node,
       const std::string name) const override
   {
+    auto log = Dorie::get_logger(log_transport);
+
     std::shared_ptr<Transport<Traits>> hd_dips;
 
     const auto type = type_node["type"].as<std::string>();
@@ -65,7 +68,10 @@ struct TransportFactory
       } else if (eff_diff_type == MillingtonQuirk2<Traits>::type) {
           eff_diff = std::make_shared<MillingtonQuirk2<Traits>>(name);
       } else {
-          DUNE_THROW(NotImplemented,"Invalid eff_diff");
+        log->error("Effective Diffusion parameterization '{}' "
+                  "has unknown type '{}'",
+                    name, eff_diff_type);
+        DUNE_THROW(IOError, "Unknown Transport parameterization type");
       }
 
       // Select type for effective hydromechanic dispersion
@@ -90,24 +96,35 @@ struct TransportFactory
         if (long_disp_type == ConstLongitudinalDispersivity<Traits>::type) {
             lambda_l = std::make_shared<ConstLongitudinalDispersivity<Traits>>(name);
         } else {
-            DUNE_THROW(NotImplemented,"Invalid long_disp");
+          log->error("Longitudinal Dispersivity parameterization '{}' "
+                    "has unknown type '{}'",
+                      name, long_disp_type);
+          DUNE_THROW(IOError, "Unknown Transport parameterization type");
         }
 
         // Build parametrization for transverse dispersivity
         if (trans_disp_type == ConstTransverseDispersivity<Traits>::type) {
             lambda_t = std::make_shared<ConstTransverseDispersivity<Traits>>(name);
         } else {
-            DUNE_THROW(NotImplemented,"Invalid trans_disp");
+          log->error("Transverse Dispersivity parameterization '{}' "
+                    "has unknown type '{}'",
+                      name, trans_disp_type);
+          DUNE_THROW(IOError, "Unknown Transport parameterization type");
         }
 
         eff_hm_disp = std::make_shared<IsotropicEffectiveHydromechanicDispersion<Traits>>(name,lambda_l,lambda_t);
       } else {
-          DUNE_THROW(NotImplemented,"Invalid eff_hydromech_disp");
+        log->error("Effective Hydromechanic Dispersion parameterization '{}' "
+                  "has unknown type '{}'",
+                    name, eff_hm_disp_type);
+        DUNE_THROW(IOError, "Unknown Transport parameterization type");
       }
 
       hd_dips = std::make_shared<HydrodynamicDispersionSuperposition<Traits>>(name,eff_diff,eff_hm_disp);
     } else {
-            DUNE_THROW(NotImplemented,"Invalid hydrodyn_disp" );
+      log->error("Transport parameterization '{}' has unknown type '{}'",
+                  name, type);
+      DUNE_THROW(IOError, "Unknown Transport parameterization type");
     }
     return hd_dips;
   }

dune/dorie/model/transport/parameterization/interface.hh

@@ -38,11 +38,13 @@ public:
         Vector value;
     };
 
+    /// Type of microscopic peclet number
     struct PecletType
     {
         RangeField value;
     };
 
+    /// Parameter defining the characteristic length
     struct CharacteristicLengthType
     {
         CharacteristicLengthType() {}
@@ -50,6 +52,7 @@ public:
         inline static const std::string name = "char_length";
     };
 
+    /// Parameter defining the molecluar diffusion
     struct MolecularDiffusionType
     {
         MolecularDiffusionType() {}
@@ -57,9 +60,25 @@ public:
         inline static const std::string name = "mol_diff";
     };
 
+    //! Value of the characteristic length.
+    CharacteristicLengthType _char_length;
+    //! Value of the molecluar diffusion.
+    MolecularDiffusionType _mol_diff;
+    //! The name of this parameterization instance, associated with the layer.
+    const std::string _name;
+
+public:
+    /// Construct with default-initialized parameters
+    /** \param name The name associated with this soil layer
+     *  \param parameters Tuple of parameters to use in this parameterization
+     */
     Transport (const std::string name) : _name(name)
     { }
 
+    /// Construct from a tuple of parameters
+    /** \param name The name associated with this soil layer
+     *  \param parameters Tuple of parameters to use in this parameterization
+     */
     template<typename... Args>
     Transport (
             const std::string name,
@@ -68,17 +87,22 @@ public:
         _mol_diff(std::get<MolecularDiffusionType>(parameters))
     { }
 
-    CharacteristicLengthType _char_length;
-    MolecularDiffusionType _mol_diff;
-
+    /// Default constructor (virtual).
     virtual ~Transport () = default;
 
+    /// Return the name of this parameterization instance.
     const std::string& get_name() const { return _name; }
 
+    /// Return a bound version of the hydrodunamic dispersion tensor
+    /** \return Function: {Water Flux, Water Content} -> Hydrodunamic Disp. Tensor
+     */
     virtual std::function<
         HydrodynamicDispersionType(const WaterFluxType water_flux, const WaterContentType water_content)> 
             hydrodynamic_dispersion_f () const = 0;
 
+    /// Return a bound version of the microscopic peclet function
+    /** \return Function: {Water Flux, Water Content} -> Peclet
+     */
     std::function<
         PecletType(const WaterFluxType, const WaterContentType)> 
             peclet_f () const
@@ -111,10 +135,10 @@ public:
         };
     }
 
+    /// Clone the plymorphic class
+    /** \return unique pointer to the cloned object
+     */
     virtual std::unique_ptr<Transport<Traits>> clone () const = 0;
-
-private:
-    const std::string _name;
 };
 
 } // namespace Parameterization