further improved documentation for tutorial decoupled

examples/tutorialproblem_decoupled.hh

@@ -129,8 +129,8 @@ SET_SCALAR_PROP(TutorialProblemDecoupled, CFLFactor, 0.3); /*@\label{tutorial-de
 SET_BOOL_PROP(TutorialProblemDecoupled, EnableGravity, false); /*@\label{tutorial-decoupled:gravity}@*/
 } /*@\label{tutorial-decoupled:propertysystem-end}@*/
 
-/*!
+/*! \ingroup DecoupledProblems
-* \ingroup DecoupledProblems
+ * @brief Problem class for the decoupled tutorial
 */
 template<class TypeTag = TTAG(TutorialProblemDecoupled)>
 class TutorialProblemDecoupled: public IMPESProblem2P<TypeTag, TutorialProblemDecoupled<TypeTag> > /*@\label{tutorial-decoupled:def-problem}@*/
@@ -166,32 +166,25 @@ public:
             const GlobalPosition upperRight = GlobalPosition(0.)) : ParentType(gridView) /*@\label{tutorial-decoupled:constructor-problem}@*/
     {    }
 
-    /*!
+    //! The problem name.
-    * \brief The problem name.
+    /*! This is used as a prefix for files generated by the simulation.
-    *
-    * This is used as a prefix for files generated by the simulation.
     */
     const char *name() const    /*@\label{tutorial-decoupled:name}@*/
     {
         return "tutorial_decoupled";
     }
 
-    /*!
+    //!  Returns true if a restart file should be written.
-     * \brief Returns true if a restart file should be written.
+    /* The default behaviour is to write no restart file.
-     *
-     * The default behaviour is to write no restart file.
      */
     bool shouldWriteRestartFile() const /*@\label{tutorial-decoupled:restart}@*/
     {
         return false;
     }
 
-    /*!
+    //! Returns true if the current solution should be written to disk (i.e. as a VTK file)
-     * \brief Returns true if the current solution should be written to
+    /*! The default behaviour is to write out every the solution for
-     *        disk (i.e. as a VTK file)
+     *  very time step. Else, change divisor.
-     *
-     * The default behaviour is to write out every the solution for
-     * very time step. Else, change divisor.
      */
     bool shouldWriteOutput() const /*@\label{tutorial-decoupled:output}@*/
     {
@@ -199,43 +192,35 @@ public:
         (this->timeManager().timeStepIndex() % 1 == 0);
     }
 
-    /*!
+    //! Returns the temperature within the domain.
-    * \brief Returns the temperature within the domain.
+    /*! This problem assumes a temperature of 10 degrees Celsius.
-    *
+     */
-    * This problem assumes a temperature of 10 degrees Celsius.
-    */
     Scalar temperature(const GlobalPosition& globalPos, const Element& element) const /*@\label{tutorial-decoupled:temperature}@*/
     {
         return 273.15 + 10; // -> 10°C
     }
 
-    /*!
+    //! Returns a constant pressure to enter material laws
-    * \brief Returns a constant pressure to enter material laws
+    /* For incrompressible simulations, a constant pressure is necessary
-    *
+     * to enter the material laws to gain a constant density etc.
-    * For incrompressible simulations, a constant pressure is necessary
+     */
-    * to enter the material laws to gain a constant density etc.
-    */
     Scalar referencePressure(const GlobalPosition& globalPos, const Element& element) const /*@\label{tutorial-decoupled:refPressure}@*/
     {
         return 2e5;
     }
-    /*!
+    //! Source of mass \f$ [\frac{kg}{m^3 \cdot s}] \f$
-    * \brief Source of mass \f$ [\frac{kg}{m^3 \cdot s}] \f$
+    /*! Evaluate the source term for all phases within a given
-    *
+     *  volume. The method returns the mass generated (positive) or
-    *     Evaluate the source term for all phases within a given
+     *  annihilated (negative) per volume unit.
-    *     volume. The method returns the mass generated (positive) or
+     */
-    *     annihilated (negative) per volume unit.
-    */
     std::vector<Scalar> source(const GlobalPosition& globalPos, const Element& element) /*@\label{tutorial-decoupled:source}@*/
-        {
+    {
         return std::vector<Scalar>(2, 0.);
-        }
+    }
 
-    /*!
+    //! Type of pressure boundary condition.
-     * \brief Type of pressure boundary condition.
+    /*! Defines the type the boundary condition for the pressure equation,
-     *
+     *  either pressure (dirichlet) or flux (neumann).
-     * Defines the type the boundary condition for the pressure equation,
-     * either pressure (dirichlet) or flux (neumann).
      */
     typename BoundaryConditions::Flags bctypePress(const GlobalPosition& globalPos, const Intersection& intersection) const /*@\label{tutorial-decoupled:bctypePress}@*/
     {
@@ -245,11 +230,9 @@ public:
         return BoundaryConditions::neumann;
     }
 
-    /*!
+    //! Type of Transport boundary condition.
-     * \brief Type of Transport boundary condition.
+    /*! Defines the type the boundary condition for the transport equation,
-     *
+     *  either saturation (dirichlet) or flux (neumann).
-     * Defines the type the boundary condition for the transport equation,
-     * either saturation (dirichlet) or flux (neumann).
      */
     BoundaryConditions::Flags bctypeSat(const GlobalPosition& globalPos, const Intersection& intersection) const /*@\label{tutorial-decoupled:bctypeSat}@*/
     {
@@ -258,11 +241,9 @@ public:
         else
             return Dumux::BoundaryConditions::neumann;
     }
-    /*!
+    //! Value for dirichlet pressure boundary condition \f$ [Pa] \f$.
-     * \brief Value for dirichlet pressure boundary condition \f$ [Pa] \f$.
+    /*! In case of a dirichlet BC for the pressure equation, the pressure
-     *
+     *  have to be defined on boundaries.
-     * In case of a dirichlet BC for the pressure equation, the pressure
-     * have to be defined on boundaries.
      */
     Scalar dirichletPress(const GlobalPosition& globalPos, const Intersection& intersection) const /*@\label{tutorial-decoupled:dirichletPress}@*/
     {
@@ -271,11 +252,9 @@ public:
         // all other boundaries
         return 0;
     }
-    /*!
+    //! Value for transport dirichlet boundary condition (dimensionless).
-     * \brief Value for transport dirichlet boundary condition (dimensionless).
+    /*! In case of a dirichlet BC for the transport equation, a saturation
-     *
+     *  have to be defined on boundaries.
-     * In case of a dirichlet BC for the transport equation, a saturation
-     * have to be defined on boundaries.
      */
     Scalar dirichletSat(const GlobalPosition& globalPos, const Intersection& intersection) const /*@\label{tutorial-decoupled:dirichletSat}@*/
     {
@@ -285,9 +264,9 @@ public:
         return 0;
     }
     //! Value for pressure neumann boundary condition \f$ [\frac{kg}{m^3 \cdot s}] \f$.
-     /** In case of a neumann boundary condition, the flux of matter
+    /*! In case of a neumann boundary condition, the flux of matter
-      * is returned as a vector.
+     *  is returned as a vector.
-      */
+     */
     std::vector<Scalar> neumannPress(const GlobalPosition& globalPos, const Intersection& intersection) const /*@\label{tutorial-decoupled:neumannPress}@*/
     {
         std::vector<Scalar> neumannFlux(2,0.0);
@@ -298,17 +277,15 @@ public:
         return neumannFlux;
     }
     //! Value for transport neumann boundary condition \f$ [\frac{kg}{m^3 \cdot s}] \f$.
-     /** In case of a neumann boundary condition for the transport equation
+    /*! In case of a neumann boundary condition for the transport equation
-      * the flux of matter for the primary variable is returned as a scalar.
+     *  the flux of matter for the primary variable is returned as a scalar.
-      */
+     */
     Scalar neumannSat(const GlobalPosition& globalPos, const Intersection& intersection, Scalar factor) const /*@\label{tutorial-decoupled:neumannSat}@*/
     {
         return 0;
     }
     //! Saturation initial condition (dimensionless)
-    /*
+    /*! The problem is initialized with the following saturation.
-     * @param element reference to the cell for which the function is to be evaluated
-     * @param localPos local coordinates inside element
      */
     Scalar initSat(const GlobalPosition& globalPos, const Element& element) const /*@\label{tutorial-decoupled:initSat}@*/
     {

examples/tutorialspatialparameters_decoupled.hh

@@ -23,8 +23,7 @@
 
 namespace Dumux
 {
-
+//! Definition of the spatial parameters for the decoupled tutorial
-/** \todo Please doc me! */
 
 template<class TypeTag>
 class TutorialSpatialParametersDecoupled
@@ -42,35 +41,40 @@ class TutorialSpatialParametersDecoupled
     typedef Dune::FieldVector<CoordScalar, dim> LocalPosition;
     typedef Dune::FieldMatrix<Scalar,dim,dim> FieldMatrix;
 
+    // material law typedefs
     typedef RegularizedBrooksCorey<Scalar>                RawMaterialLaw;
 //    typedef LinearMaterial<Scalar>                        RawMaterialLaw;
 public:
     typedef EffToAbsLaw<RawMaterialLaw>               MaterialLaw;
     typedef typename MaterialLaw::Params MaterialLawParams;
 
+    //! Update the spatial parameters with the flow solution after a timestep.
+    /*! Function left blank as there is nothing to do for the tutorial.
+     */
     void update (Scalar saturationW, const Element& element)
-    {
+    {    }
-
+    //! Intrinsic permeability tensor
-    }
+    /*! Apply the intrinsic permeability tensor \f$[m^2]\f$ to a
-
+     *  pressure potential gradient.
+     */
     const FieldMatrix& intrinsicPermeability (const GlobalPosition& globalPos, const Element& element) const
     {
             return K_;
     }
 
+    //! Define the porosity \f$[-]\f$ of the spatial parameters
     double porosity(const GlobalPosition& globalPos, const Element& element) const
     {
         return 0.2;
     }
 
-
+    //! return the material law context (i.e. BC, regularizedVG, etc) depending on the position
-    // return the brooks-corey context depending on the position
     const MaterialLawParams& materialLawParams(const GlobalPosition& globalPos, const Element &element) const
     {
             return materialLawParams_;
     }
 
-
+    //! Constructor
     TutorialSpatialParametersDecoupled(const GridView& gridView)
     : K_(0)
     {