[shallowwater] Complete the doxygen documentation

Add the entries for the shallow water model in module.txt.
Ensure that all classes and functions have docstrings.
Document the ShallowWaterFlux class.

doc/doxygen/modules.txt

@@ -243,6 +243,12 @@
      * \brief An energy equation adaptor for isothermal free-flow models
      * \copydetails ./freeflow/nonisothermal/model.hh
      */
+    /*!
+     * \ingroup FreeflowModels
+     * \defgroup ShallowWaterModel 2D shallow water model
+     * \brief Two-dimensional shallow water flow (depth-averaged)
+     * \copydetails ./freeflow/shallowwater/model.hh
+     */
 /*!
  * \defgroup Geomechanics Geomechanics Models
  * \brief Models for taking into account solid deformation
@@ -375,6 +381,11 @@
          * \defgroup RANSNCTests Reynolds-Averaged Navier-Stokes nc tests
          * \brief  Various tests using a single-phase Reynolds-Averaged Navier-Stokes flow with n components. The files are listed below.
          */
+        /*!
+         * \ingroup FreeflowTests
+         * \defgroup ShallowWaterTests 2D shallow water tests
+         * \brief Tests for the two-dimensional shallow water model. The files are listed below.
+         */
     /*!
      * \ingroup BenchmarksAndTests
      * \defgroup GeomechanicsTests Geomechanics Tests
@@ -471,6 +482,11 @@
      * \defgroup StaggeredFlux Flux related to the staggered scheme
      * \brief Flux related to the staggered scheme
      */
+    /*!
+     * \ingroup Flux
+     * \defgroup ShallowWaterFlux Flux related to the shallow water model
+     * \brief Flux related to the shallow water model
+     */
 /* ***************** Material ******************/
 /*!
  * \defgroup Material Material and Fluid Framework

dumux/flux/shallowwater/exactriemann.hh

@@ -18,7 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
- * \ingroup ShallowWater
+ * \ingroup ShallowWaterFlux
  * \brief Function to compute the Riemann flux at the interface
  */
 #ifndef DUMUX_FLUX_SHALLOW_WATER_EXACT_RIEMANN_HH
@@ -40,7 +40,7 @@ struct RiemannSolution {
 
 
 /*!
- * \ingroup ShallowWater
+ * \ingroup ShallowWaterFlux
  * \brief Exact Riemann solver for Shallow water equations.
  *
  * This Riemann solver is described in the book

dumux/flux/shallowwater/fluxlimiterlet.hh

@@ -18,7 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
- * \ingroup ShallowWater
+ * \ingroup ShallowWaterFlux
  * \brief Function to limit the fluxes
  *
  */
@@ -32,7 +32,7 @@ namespace Dumux {
 namespace ShallowWater {
 
 /*!
- * \ingroup ShallowWater
+ * \ingroup ShallowWaterFlux
  * \brief Flux limiter function to scale fluxes for small water depths.
  *
  * This function acts like a kind of mobility, it limits the water flux

dumux/flux/shallowwater/riemannproblem.hh

@@ -18,8 +18,8 @@
  *****************************************************************************/
 /*!
  * \file
- * \ingroup ShallowWater
- * \brief This file includes a unction to construct the Riemann problem
+ * \ingroup ShallowWaterFlux
+ * \brief This file includes a function to construct the Riemann problem
  *
  */
 #ifndef DUMUX_FLUX_SHALLOW_WATER_RIEMANN_PROBLEM_HH
@@ -32,7 +32,7 @@ namespace Dumux {
 namespace ShallowWater {
 
 /*!
- * \ingroup ShallowWater
+ * \ingroup ShallowWaterFlux
  * \brief Construct Riemann Problem and solve it
  *
  *
@@ -58,7 +58,7 @@ namespace ShallowWater {
  * \param velocityYRight velocityY on the right side
  * \param bedSurfaceLeft surface of the bed on the left side
  * \param bedSurfaceRight surface of the bed on the right side
- * \param grav gravity constant
+ * \param gravity gravity constant
  * \param nxy the normal vector
  *
  */

dumux/flux/shallowwaterflux.hh

@@ -16,6 +16,11 @@
  *   You should have received a copy of the GNU General Public License       *
  *   along with this program.  If not, see <http://www.gnu.org/licenses/>.   *
  *****************************************************************************/
+/*!
+ * \file
+ * \ingroup Flux
+ * \copydoc Dumux::ShallowWaterFlux
+ */
 #ifndef DUMUX_FLUX_SHALLOW_WATER_FLUX_HH
 #define DUMUX_FLUX_SHALLOW_WATER_FLUX_HH
 
@@ -24,6 +29,13 @@
 
 namespace Dumux {
 
+/*!
+ * \ingroup Flux
+ * \brief In contrast to the other fluxes provided by dumux this flux is independent
+ *        of the discretization scheme. Therefore no specialisation for the different
+ *        discretizations is needed.
+ *        The shallow water flux is computed by solving a riemann problem.
+ */
 template<class NumEqVector>
 class ShallowWaterFlux
 {

dumux/freeflow/shallowwater/boundaryfluxes.hh

@@ -18,7 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
- * \ingroup ShallowWater
+ * \ingroup ShallowWaterModel
  * \brief Compute boundary conditions (cell state) via Riemann invariants
  *
  */

dumux/freeflow/shallowwater/indices.hh

@@ -30,8 +30,6 @@ namespace Dumux {
 /*!
  * \ingroup ShallowWaterModel
  * \brief The common indices for the shallow water equations model.
- *
- * \tparam PVOffset The first index in a primary variable vector.
  */
 struct ShallowWaterIndices
 {

dumux/freeflow/shallowwater/iofields.hh

@@ -19,7 +19,7 @@
 /*!
  * \file
  * \ingroup ShallowWaterModel
- * \copydoc Add I/O fields specific to shallow water
+ * \brief Add I/O fields specific to shallow water
  */
 #ifndef DUMUX_FREEFLOW_SHALLOW_WATER_IO_FIELDS_HH
 #define DUMUX_FREEFLOW_SHALLOW_WATER_IO_FIELDS_HH

dumux/freeflow/shallowwater/localresidual.hh

@@ -85,6 +85,7 @@ public:
      * \param fvGeometry The finite-volume geometry
      * \param elemVolVars The volume variables of the current element
      * \param scvf The sub control volume face to compute the flux on
+     * \param elemFluxVarsCache the flux variable cache for the element stencil
     */
     NumEqVector computeFlux(const Problem& problem,
                             const Element& element,

dumux/freeflow/shallowwater/model.hh

@@ -20,8 +20,7 @@
  * \file
  * \ingroup ShallowWaterModel
  *
- * \brief A two-dimesnional shallow water equations model
- *
+ * \brief A two-dimensional shallow water equations model
  * The two-dimensonal shallow water equations (SWEs) can be written as
  *
  * \f[

dumux/freeflow/shallowwater/problem.hh

@@ -32,7 +32,7 @@ namespace Dumux {
 
 /*!
  * \ingroup ShallowWaterModel
- * \brief ShallowWater problem base class.
+ * \brief Shallow water problem base class.
  */
 template<class TypeTag>
 class ShallowWaterProblem : public FVProblem<TypeTag>

test/freeflow/shallowwater/dambreak/main.cc

@@ -18,8 +18,8 @@
  *****************************************************************************/
 /*!
  * \file
- * \ingroup ShallowWaterTest
- * \brief Test for the shallow water model (wet dam break).
+ * \ingroup ShallowWaterTests
+ * \brief A test for the shallow water model (wet dam break).
  */
 #include <config.h>
 

test/freeflow/shallowwater/dambreak/problem.hh

@@ -18,8 +18,8 @@
  *****************************************************************************/
 /*!
  * \file
- * \ingroup ShallowWaterTest
- * \brief Test for the Shallow water model (wet dam break).
+ * \ingroup ShallowWaterTests
+ * \brief A test for the Shallow water model (wet dam break).
  */
 #ifndef DUMUX_DAM_BREAK_TEST_PROBLEM_HH
 #define DUMUX_DAM_BREAK_TEST_PROBLEM_HH

test/freeflow/shallowwater/dambreak/spatialparams.hh

@@ -18,7 +18,7 @@
  *****************************************************************************/
 /*!
  * \file
- * \ingroup ShallowWaterTest
+ * \ingroup ShallowWaterTests
  * \brief The spatial parameters for the dam break problem.
  */
 #ifndef DUMUX_DAM_BREAK_SPATIAL_PARAMETERS_HH