Update docs for Richards FV solver

* Mention FV and DG solver options in Feature Overview.
* Update default parameter descriptions on 'FEorder' and 'vertex data'.
* Adjust Richards FV local operator docstrings
  - Add RichardsDGTemporalOperator to Richards model doc module.
  - Add [out] tags to residual arguments.
  - Use regular comment scheme when comments surpassed line limit.

doc/default_files/richards-parameters.xml

@@ -52,10 +52,9 @@ adding an empty line, make text **bold** or ``monospaced``.
 
     <parameter name="vertexData">
       <definition> Plot vertex based (``true``) or cell-centered (``false``)
-       data into VTK files. Vertex based data might render sharp
-       parameterization boundaries inappropriately.
-       System tests and plotting functions (``dorie plot``) require
-       cell-centered data.
+       data into VTK files. Select vertex data when using the DG solver. System
+       tests and plotting functions (``dorie plot``) require cell-centered
+       data.
       </definition>
       <values> true, false </values>
       <suggestion> true </suggestion>
@@ -240,8 +239,10 @@ adding an empty line, make text **bold** or ``monospaced``.
     </parameter>
 
     <parameter name="FEorder">
-      <definition> Order of the finite element method used. Values &gt; 1 are not
-        thoroughly tested. </definition>
+      <definition> Polynomial order of the DG method used. Setting this value
+        to 0 (zero) selects the finite volume (FV) solver (only compatible to
+        structured rectangular grids).
+      </definition>
       <suggestion> 1 </suggestion>
       <values> 0, 1, 2, 3 </values>
     </parameter>

doc/introduction/features.rst

@@ -39,6 +39,15 @@ singularities.
 Use the value ``richards`` in the ``simulation.mode`` keyword to run the
 standalone Richards solver.
 
+Solver Options
+--------------
+
+DORiE includes a finite volume (FV) and a discontinuous Galerkin (DG) solver
+for the Richards equation. The FV solver can be selected for structured
+rectangular grids by setting ``richards.numerics.FEorder = 0`` when adaptivity
+is disabled. The DG solver is used for orders :math:`k \geq 1` and is available
+for all grid options.
+
 Solute Transport Solver
 =======================
 

dune/dorie/model/richards/local_operator_DG.hh

@@ -938,6 +938,7 @@ public:
  * @brief DG local operator for the temporal derivative of the Richards equation
  *
  * @ingroup LocalOperators
+ * @ingroup RichardsModel
  */
 template<typename Traits, typename Parameter, typename FEM, bool adjoint>
   class RichardsDGTemporalOperator

dune/dorie/model/richards/local_operator_FV.hh

-// -*- tab-width: 4; indent-tabs-mode: nil -*-
 #ifndef DUNE_DORIE_RICHARDS_OPERATOR_FV_HH
 #define DUNE_DORIE_RICHARDS_OPERATOR_FV_HH
 
@@ -81,8 +80,8 @@ public:
     * @param[in]  lfsu_o  The outside ansatz local function space
     * @param[in]  x_o     The coefficients of the lfsu_o
     * @param[in]  lfsv_o  The outside test local function space
-    * @param      r_i     The view of the residual vector w.r.t lfsu_i
-    * @param      r_o     The view of the residual vector w.r.t lfsu_o
+    * @param[out] r_i     The view of the residual vector w.r.t lfsu_i
+    * @param[out] r_o     The view of the residual vector w.r.t lfsu_o
     *
     * @tparam     IG      The type for ig
     * @tparam     LFSU    The type for lfsu_i and lfsu_o
@@ -182,7 +181,7 @@ public:
    * @param[in]  lfsu_i  The inside ansatz local function space
    * @param[in]  x_i     The coefficients of the lfsu_i
    * @param[in]  lfsv_i  The inside test local function space
-   * @param      r_i     The view of the residual vector w.r.t lfsu_i
+   * @param[out] r_i     The view of the residual vector w.r.t lfsu_i
    *
    * @tparam     IG      The type for ig
    * @tparam     LFSU    The type for lfsu_i
@@ -290,8 +289,10 @@ public:
   }
 
 private:
-  std::shared_ptr<const Parameter> _param; //!< class providing equation parameters
-  std::shared_ptr<const Boundary> _boundary; //!< class providing boundary conditions
+  /// Class providing equation parameters
+  std::shared_ptr<const Parameter> _param;
+  /// Class providing boundary conditions
+  std::shared_ptr<const Boundary> _boundary;
   double _time;
 };
 
@@ -340,11 +341,11 @@ public:
   /*-----------------------------------------------------------------------*//**
    * @brief      Volume integral depending on test and ansatz functions
    *
-   * @param[in]  eg    THe entity of the grid
+   * @param[in]  eg    The entity of the grid
    * @param[in]  lfsu  The ansatz local function space
    * @param[in]  x     The coefficients of the lfsu
    * @param[in]  lfsv  The test local function space
-   * @param      r     The view of the residual vector w.r.t lfsu
+   * @param[out] r     The view of the residual vector w.r.t lfsu
    *
    * @tparam     EG    The type for eg
    * @tparam     LFSU  The type for lfsu
@@ -379,13 +380,12 @@ public:
     r.accumulate(lfsv ,0 , water_content*geo.volume());
   }
 
-  /*-----------------------------------------------------------------------*//**
+  /**
    * @brief      Sets the time.
    *
    * @param[in]  t     time of type RangeField
    *
-   * @tparam     RF    { description }
-   * @tparam     RangeField  type of the range field
+   * @tparam     RF    Type of the range field
    */
   template<class RF>
   void setTime (RF t)
@@ -394,7 +394,8 @@ public:
   }
 
 private:
-  std::shared_ptr<const Parameter> _param; //!< class providing equation parameters
+  /// class providing equation parameters
+  std::shared_ptr<const Parameter> _param;
   double _time;
 };