Improve FlowParameters

* add more 'const' qualifiers
* Improve docstrings

dune/dorie/solver/param_interface.hh

@@ -17,6 +17,21 @@
 namespace Dune {
 namespace Dorie {
 
+/// Top-level parameterization interface.
+/** This class stores the parameters, maps them to grid entities, and provides 
+ *  functions to access the parameterization. For doing so, the
+ *  FlowParameters::bind function has to be called first to cache the
+ *  parameters of the given grid entity. Parameters are only stored for entities
+ *  of codim 0.
+ * 
+ *  \detail The parameterization consists of three structures:
+ *      - This top-level class serves as interface and storage. It also casts to
+ *          data types used by the DUNE operators
+ *      - The Dorie::RichardsParameterization interface that provides strong 
+ *          data types for the base parameters and purely virtual functions that
+ *          need to be defined by derived parameterizations
+ *      - The actual parameterization defining all parameters and functions
+ */
 template <typename Traits>
 class FlowParameters
 {
@@ -29,10 +44,15 @@ private:
     >;
 
     // Define the storage and cache for parameterizations and scaling
+    /// Index type used by the element mapper
     using Index = typename Mapper::Index;
+    /// Base class of the parameterization
     using Parameterization = Dorie::RichardsParameterization<Traits>;
+
     using ScalingType = typename Parameterization::Scaling::Type;
     using ScalingFactor = typename Parameterization::ScalingFactor;
+
+    /// Storage for parameters and skaling factors
     using ParameterStorage = std::map<Index,
         std::tuple<std::shared_ptr<Parameterization>,
                    ScalingType,
@@ -68,6 +88,12 @@ private:
     }
 
 public:
+    /// Constructor.
+    /** Create a level grid view of level 0, create a mapper on it, and store
+     *  the config tree.
+     *  \param config Configuration file tree
+     *  \param grid Shared pointer to the grid
+     */
     FlowParameters (
         const Dune::ParameterTree& config,
         std::shared_ptr<Grid> grid
@@ -77,8 +103,8 @@ public:
         _mapper(_gv, Dune::mcmgElementLayout())
     { }
 
-    /// Bind the parameterization of an Entity, caching its values
-    /** \param entity Entity to bind to
+    /// Bind to a grid entity. Required to call parameterization functions!
+    /** \param entity Grid entity (codim 0) to bind to
      */
     template <class Entity>
     void bind (const Entity& entity) const
@@ -100,13 +126,18 @@ public:
         _cache = *it;
     }
 
-    /// Return the conductivity function. Cast to RangeField
+    /// Return a scaled version of the Conductivity function
+    /** Uses the function of the underlying parameterization and applies
+     *  scaling as specified by SkalingType. Cast to operator-internal RF.
+     *  \return Function: Saturation -> Conductivity
+     */
     std::function<RF(RF)> conductivity_f () const
     {
         verify_cache();
-        auto& par = std::get<std::shared_ptr<Parameterization>>(_cache.second);
-        auto& type = std::get<ScalingType>(_cache.second);
-        auto cond_f = par->conductivity_f();
+        const auto& par =
+            std::get<std::shared_ptr<Parameterization>>(_cache.second);
+        const auto& type = std::get<ScalingType>(_cache.second);
+        const auto cond_f = par->conductivity_f();
         using Saturation = typename Parameterization::Saturation;
 
         if (type == ScalingType::Miller) {
@@ -121,17 +152,22 @@ public:
         };
     }
 
-    /// Return the saturaton function. Cast to RangeField
+    /// Return a scaled version of the Saturation function
+    /** Uses the function of the underlying parameterization and applies
+     *  scaling as specified by SkalingType. Cast to operator-internal RF.
+     *  \return Function: Matric Head -> Saturation
+     */
     std::function<RF(RF)> saturation_f () const
     {
         verify_cache();
-        auto& par = std::get<std::shared_ptr<Parameterization>>(_cache.second);
-        auto& type = std::get<ScalingType>(_cache.second);
-        auto sat_f = par->saturation_f();
+        const auto& par = 
+            std::get<std::shared_ptr<Parameterization>>(_cache.second);
+        const auto& type = std::get<ScalingType>(_cache.second);
+        const auto sat_f = par->saturation_f();
         using MatricHead = typename Parameterization::MatricHead;
 
         if (type == ScalingType::Miller) {
-            auto& scale = std::get<ScalingFactor>(_cache.second).value;
+            const auto& scale = std::get<ScalingFactor>(_cache.second).value;
             return [sat_f, &scale](const RF matric_head){
                 return sat_f(MatricHead{matric_head * scale}).value;
             };
@@ -142,12 +178,17 @@ public:
         };
     }
 
-    /// Return the water content function. Cast to Rangefield
+    /// Return a scaled version of the Water Content function
+    /** Uses the function of the underlying parameterization and applies
+     *  scaling as specified by SkalingType. Cast to operator-internal RF.
+     *  \return Function: Saturation -> Water Content
+     */
     std::function<RF(RF)> water_content_f () const
     {
         verify_cache();
-        auto& par = std::get<std::shared_ptr<Parameterization>>(_cache.second);
-        auto wc_f = par->water_content_f();
+        const auto& par =
+            std::get<std::shared_ptr<Parameterization>>(_cache.second);
+        const auto wc_f = par->water_content_f();
         using Saturation = typename Parameterization::Saturation;
 
         return [wc_f](const RF saturation) {
@@ -155,6 +196,10 @@ public:
         };
     }
 
+    /// Copy parameters from the 'old' parameterization implementation
+    /** \todo Remove once new interface is established
+     *  \param p_base Old parameterization base class
+     */
     template <class Param>
     void copy_from_old_parameters (const Param& p_base)
     {