[doxygen] Adapt documentation for richards, richardsnc, tracer models

dumux/porousmediumflow/richards/indices.hh

@@ -21,6 +21,7 @@
  * \ingroup RichardsModel
  * \brief Index names for the Richards model.
  */
+
 #ifndef DUMUX_RICHARDS_INDICES_HH
 #define DUMUX_RICHARDS_INDICES_HH
 

dumux/porousmediumflow/richards/iofields.hh

@@ -21,6 +21,7 @@
  * \ingroup RichardsModel
  * \brief Adds I/O fields specific to the Richards model.
  */
+
 #ifndef DUMUX_RICHARDS_IO_FIELDS_HH
 #define DUMUX_RICHARDS_IO_FIELDS_HH
 

dumux/porousmediumflow/richards/localresidual.hh

@@ -22,6 +22,7 @@
  * \brief Element-wise calculation of the Jacobian matrix for problems
  *        using the Richards fully implicit models.
  */
+
 #ifndef DUMUX_RICHARDS_LOCAL_RESIDUAL_HH
 #define DUMUX_RICHARDS_LOCAL_RESIDUAL_HH
 
@@ -71,7 +72,7 @@ public:
     using ParentType::ParentType;
 
     /*!
-     * \brief Evaluate the rate of change of all conservation
+     * \brief Evaluates the rate of change of all conservation
      *        quantites (e.g. phase mass) within a sub-control
      *        volume of a finite volume element for the immiscible models.
      * \param problem The problem
@@ -109,7 +110,7 @@ public:
 
 
     /*!
-     * \brief Evaluate the mass flux over a face of a sub control volume
+     * \brief Evaluates the mass flux over a face of a sub control volume.
      *
      * \param problem The problem
      * \param element The current element.

dumux/porousmediumflow/richards/model.hh

@@ -16,7 +16,6 @@
  *   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 RichardsModel
@@ -69,12 +68,12 @@
  * consequence, the \f$\frac{k_{r\alpha}}{\mu_\alpha}\f$ term
  * typically is much larger for the gas phase than for the wetting
  * phase. For this reason, the Richards model assumes that
- * \f$\frac{k_{rn}}{\mu_n}\f$ is infinitly large. This implies that
+ * \f$\frac{k_{rn}}{\mu_n}\f$ is infinitely large. This implies that
  * the pressure of the gas phase is equivalent to the static pressure
  * distribution and that therefore, mass conservation only needs to be
  * considered for the wetting phase.
  *
- * The model thus choses the absolute pressure of the wetting phase
+ * The model thus chooses the absolute pressure of the wetting phase
  * \f$p_w\f$ as its only primary variable. The wetting phase
  * saturation is calculated using the inverse of the capillary
  * pressure, i.e.

dumux/porousmediumflow/richards/newtonsolver.hh

@@ -19,8 +19,9 @@
 /*!
  * \file
  * \ingroup RichardsModel
- * \brief A Richards model newton solver.
+ * \brief A Richards model Newton solver.
  */
+
 #ifndef DUMUX_RICHARDS_NEWTON_SOLVER_HH
 #define DUMUX_RICHARDS_NEWTON_SOLVER_HH
 
@@ -31,7 +32,7 @@
 namespace Dumux {
 /*!
  * \ingroup RichardsModel
- * \brief A Richards model specific newton solver.
+ * \brief A Richards model specific Newton solver.
  *
  * This solver 'knows' what a 'physically meaningful' solution is
  * and can thus do update smarter than the plain Newton solver.
@@ -56,9 +57,7 @@ public:
 private:
 
     /*!
-     * \brief Update the current solution of the newton method
-     *
-     * \todo TODO: doc me!
+     * \brief Update the current solution of the Newton method
      *
      * \param uCurrentIter The solution after the current Newton iteration \f$ u^{k+1} \f$
      * \param uLastIter The solution after the last Newton iteration \f$ u^k \f$

dumux/porousmediumflow/richards/primaryvariableswitch.hh

@@ -21,6 +21,7 @@
  * \ingroup RichardsModel
  * \brief The primary variable switch for the extended Richards model.
  */
+
 #ifndef DUMUX_RICHARDS_PRIMARY_VARIABLE_SWITCH_HH
 #define DUMUX_RICHARDS_PRIMARY_VARIABLE_SWITCH_HH
 

dumux/porousmediumflow/richards/volumevariables.hh

@@ -21,6 +21,7 @@
  * \ingroup RichardsModel
  * \brief Volume averaged quantities required by the Richards model.
  */
+
 #ifndef DUMUX_RICHARDS_VOLUME_VARIABLES_HH
 #define DUMUX_RICHARDS_VOLUME_VARIABLES_HH
 
@@ -39,7 +40,7 @@
 namespace Dumux {
 
 namespace Detail {
-//! helper structs to conditionally use a primary variable switch or not
+//! Helper structs to conditionally use a primary variable switch or not
 struct VolVarsWithPVSwitch
 {
     using PrimaryVariableSwitch = ExtendedRichardsPrimaryVariableSwitch;
@@ -70,21 +71,21 @@ class RichardsVolumeVariables
     using ModelTraits = typename Traits::ModelTraits;
     static constexpr int numFluidComps = ParentType::numFluidComponents();
 public:
-    //! export type of the fluid system
+    //! Export type of the fluid system
     using FluidSystem = typename Traits::FluidSystem;
-    //! export type of the fluid state
+    //! Export type of the fluid state
     using FluidState = typename Traits::FluidState;
-    //! export type of the fluid state
-    //! export type of solid state
+    //! Export type of the fluid state
+    //! Export type of solid state
     using SolidState = typename Traits::SolidState;
-    //! export type of solid system
+    //! Export type of solid system
     using SolidSystem = typename Traits::SolidSystem;
     using Indices = typename Traits::ModelTraits::Indices;
-    //! if water diffusion in air is enabled
+    //! If water diffusion in air is enabled
     static constexpr bool enableWaterDiffusionInAir() { return ModelTraits::enableMolecularDiffusion(); };
 
     /*!
-     * \brief Update all quantities for a given control volume
+     * \brief Updates all quantities for a given control volume.
      *
      * \param elemSol A vector containing all primary variables connected to the element
      * \param problem The object specifying the problem which ought to
@@ -191,7 +192,7 @@ public:
     }
 
     /*!
-     * \brief Fill the fluid state according to the primary variables.
+     * \brief Fills the fluid state according to the primary variables.
      *
      * Taking the information from the primary variables,
      * the fluid state is filled with every information that is
@@ -251,8 +252,8 @@ public:
     }
 
     /*!
-     * \brief Return the fluid configuration at the given primary
-     *        variables
+     * \brief Returns the fluid configuration at the given primary
+     *        variables.
      */
     const FluidState &fluidState() const
     { return fluidState_; }
@@ -264,7 +265,7 @@ public:
     { return solidState_; }
 
     /*!
-     * \brief Return the temperature
+     * \brief Returns the temperature.
      */
     Scalar temperature() const
     { return fluidState_.temperature(); }
@@ -388,11 +389,10 @@ public:
     { return 100.0 *(pressure(phaseIdx) - pressure(FluidSystem::gasPhaseIdx))/density(phaseIdx)/9.81; }
 
     /*!
-     * \brief Returns the water content
-     *        fluid phase within the finite volume.
+     * \brief Returns the water content of a fluid phase within the finite volume.
      *
      * The water content is defined as the fraction of
-     * the saturation devided by the porosity
+     * the saturation devided by the porosity.
 
      * \param phaseIdx The index of the fluid phase
      * \note this function is here as a convenience to the user to not have to

dumux/porousmediumflow/richardsnc/iofields.hh

@@ -21,6 +21,7 @@
  * \ingroup RichardsNCModel
  * \brief Adds I/O fields specific to the Richards model.
  */
+
 #ifndef DUMUX_RICHARDSNC_IO_FIELDS_HH
 #define DUMUX_RICHARDSNC_IO_FIELDS_HH
 

dumux/porousmediumflow/richardsnc/model.hh

@@ -45,12 +45,12 @@
  * consequence, the \f$\frac{k_{r\alpha}}{\mu_\alpha}\f$ term
  * typically is much larger for the gas phase than for the wetting
  * phase. For this reason, the Richards model assumes that
- * \f$\frac{k_{rn}}{\mu_n}\f$ is infinitly large. This implies that
+ * \f$\frac{k_{rn}}{\mu_n}\f$ is infinitely large. This implies that
  * the pressure of the gas phase is equivalent to the static pressure
  * distribution and that therefore, mass conservation only needs to be
  * considered for the wetting phase.
  *
- * The model thus choses the absolute pressure of the wetting phase
+ * The model thus chooses the absolute pressure of the wetting phase
  * \f$p_w\f$ as its only primary variable. The wetting phase
  * saturation is calculated using the inverse of the capillary
  * pressure, i.e.

dumux/porousmediumflow/richardsnc/volumevariables.hh

@@ -22,6 +22,7 @@
  * \brief  Contains the quantities which are constant within a
  *        finite volume in the Richards, n-component model.
  */
+
 #ifndef DUMUX_RICHARDSNC_VOLUME_VARIABLES_HH
 #define DUMUX_RICHARDSNC_VOLUME_VARIABLES_HH
 
@@ -52,22 +53,22 @@ class RichardsNCVolumeVariables
     static constexpr bool useMoles = Traits::ModelTraits::useMoles();
 
 public:
-    //! export type of the fluid system
+    //! Export type of the fluid system
     using FluidSystem = typename Traits::FluidSystem;
-    //! export type of the fluid state
+    //! Export type of the fluid state
     using FluidState = typename Traits::FluidState;
-    //! export type of solid state
+    //! Export type of solid state
     using SolidState = typename Traits::SolidState;
-    //! export type of solid system
+    //! Export type of solid system
     using SolidSystem = typename Traits::SolidSystem;
-    //! export indices
+    //! Export indices
     using Indices = typename Traits::ModelTraits::Indices;
-    //! export phase acess indices
+    //! Export phase acess indices
     static constexpr int liquidPhaseIdx = 0;
     static constexpr int gasPhaseIdx = 1;
 
     /*!
-     * \brief Update all quantities for a given control volume
+     * \brief Updates all quantities for a given control volume.
      *
      * \param elemSol A vector containing all primary variables connected to the element
      * \param problem The object specifying the problem which ought to
@@ -118,7 +119,7 @@ public:
     }
 
     /*!
-     * \brief Fill the fluid state according to the primary variables.
+     * \brief Fills the fluid state according to the primary variables.
      *
      * Taking the information from the primary variables,
      * the fluid state is filled with every information that is
@@ -186,8 +187,8 @@ public:
     }
 
     /*!
-     * \brief Return the fluid configuration at the given primary
-     *        variables
+     * \brief Returns the fluid configuration at the given primary
+     *        variables.
      */
     const FluidState &fluidState() const
     { return fluidState_; }
@@ -199,7 +200,7 @@ public:
     { return solidState_; }
 
     /*!
-     * \brief Return the temperature
+     * \brief Returns the temperature.
      */
     Scalar temperature() const
     { return fluidState_.temperature(); }
@@ -337,7 +338,7 @@ public:
     { return saturation(phaseIdx) * solidState_.porosity(); }
 
     /*!
-     * \brief Return molar density \f$\mathrm{[mol/m^3]}\f$ the of the fluid phase.
+     * \brief Returns the molar density \f$\mathrm{[mol/m^3]}\f$ the of the fluid phase.
      *
      * We always forward to the fluid state with the phaseIdx property (see class description).
      */
@@ -345,7 +346,7 @@ public:
     { return phaseIdx == 0 ? this->fluidState_.molarDensity(phaseIdx) : 0.0; }
 
     /*!
-     * \brief Return mole fraction \f$\mathrm{[mol/mol]}\f$ of a component in the phase.
+     * \brief Returns the mole fraction \f$\mathrm{[mol/mol]}\f$ of a component in the phase.
      *
      * \param phaseIdx The index of the phase.
      * \param compIdx The index of the component.
@@ -356,7 +357,7 @@ public:
     { return phaseIdx == 0 ? this->fluidState_.moleFraction(phaseIdx, compIdx) : 0.0; }
 
     /*!
-     * \brief Return mass fraction \f$\mathrm{[kg/kg]}\f$ of a component in the phase.
+     * \brief Returns the mass fraction \f$\mathrm{[kg/kg]}\f$ of a component in the phase.
      *
      * \param phaseIdx The index of the phase.
      * \param compIdx The index of the component
@@ -367,7 +368,7 @@ public:
     { return phaseIdx == 0 ? this->fluidState_.massFraction(phaseIdx, compIdx) : 0.0; }
 
     /*!
-     * \brief Return concentration \f$\mathrm{[mol/m^3]}\f$  of a component in the phase.
+     * \brief Returns the concentration \f$\mathrm{[mol/m^3]}\f$  of a component in the phase.
      *
      * \param phaseIdx The index of the phase.
      * \param compIdx The index of the component
@@ -378,7 +379,7 @@ public:
     { return phaseIdx == 0 ? this->fluidState_.molarity(phaseIdx, compIdx) : 0.0; }
 
     /*!
-     * \brief Return the binary diffusion coefficient \f$\mathrm{[m^2/s]}\f$ in the fluid.
+     * \brief Returns the binary diffusion coefficient \f$\mathrm{[m^2/s]}\f$ in the fluid.
      *
      * \param phaseIdx The index of the phase.
      * \param compIdx The index of the component
@@ -390,22 +391,16 @@ protected:
     FluidState fluidState_; //!< the fluid state
 
 private:
-    /*!
-     * \brief TODO docme!
-     *
-     * \param d TODO docme!
-     * \param compIdx The index of the component
-     */
     void setDiffusionCoefficient_(int compIdx, Scalar d)
     { diffCoefficient_[compIdx-1] = d; }
 
     std::array<Scalar, ParentType::numFluidComponents()-1> diffCoefficient_;
 
-    Scalar relativePermeabilityWetting_; //!< the relative permeability of the wetting phase
+    Scalar relativePermeabilityWetting_; // the relative permeability of the wetting phase
     SolidState solidState_;
-    PermeabilityType permeability_; //!< the instrinsic permeability
-    Scalar pn_; //!< the reference non-wetting pressure
-    Scalar minPc_; //!< the minimum capillary pressure (entry pressure)
+    PermeabilityType permeability_; // the instrinsic permeability
+    Scalar pn_; // the reference non-wetting pressure
+    Scalar minPc_; // the minimum capillary pressure (entry pressure)
 };
 
 } // end namespace Dumux

dumux/porousmediumflow/tracer/iofields.hh

@@ -19,8 +19,9 @@
 /*!
  * \file
  * \ingroup TracerModel
- * \brief Adds I/O fields specific to the tracer model
+ * \brief Adds I/O fields specific to the tracer model.
  */
+
 #ifndef DUMUX_TRACER_IO_FIELDS_HH
 #define DUMUX_TRACER_IO_FIELDS_HH
 
@@ -33,7 +34,7 @@ namespace Dumux {
 
 /*!
  * \ingroup TracerModel
- * \brief Adds I/O fields specific to the tracer model
+ * \brief Adds I/O fields specific to the tracer model.
  */
 class TracerIOFields
 {

dumux/porousmediumflow/tracer/localresidual.hh

@@ -22,6 +22,7 @@
  * \brief Element-wise calculation of the local residual for problems
  *        using fully implicit tracer model.
  */
+
 #ifndef DUMUX_TRACER_LOCAL_RESIDUAL_HH
 #define DUMUX_TRACER_LOCAL_RESIDUAL_HH
 
@@ -29,14 +30,12 @@
 #include <dumux/common/parameters.hh>
 #include <dumux/discretization/method.hh>
 
-namespace Dumux
-{
+namespace Dumux {
 
 /*!
  * \ingroup TracerModel
  * \brief Element-wise calculation of the local residual for problems
  *        using fully implicit tracer model.
- *
  */
 template<class TypeTag>
 class TracerLocalResidual: public GetPropType<TypeTag, Properties::BaseLocalResidual>
@@ -64,13 +63,13 @@ public:
     using ParentType::ParentType;
 
     /*!
-     * \brief Evaluate the amount of all conservation quantities
+     * \brief Evaluates the amount of all conservation quantities
      *        (e.g. phase mass) within a sub-control volume.
      *
      * The result should be averaged over the volume (e.g. phase mass
      * inside a sub control volume divided by the volume)
      *
-     * \param problem TODO docme!
+     * \param problem The problem
      * \param scv The sub control volume
      * \param volVars The primary and secondary varaibles on the scv
      */
@@ -104,7 +103,7 @@ public:
      * \brief Evaluates the total flux of all conservation quantities
      *        over a face of a sub-control volume.
      *
-     * \param problem TODO docme!
+     * \param problem The problem
      * \param element The element
      * \param fvGeometry The finite volume geometry context
      * \param elemVolVars The volume variables for all flux stencil elements
@@ -162,11 +161,11 @@ public:
      * \brief TODO docme!
      *
      * \param partialDerivatives TODO docme!
-     * \param problem TODO docme!
+     * \param problem The problem
      * \param element The element
      * \param fvGeometry The finite volume geometry context
-     * \param curVolVars TODO docme!
-     * \param scv The sub control volume.
+     * \param curVolVars The current volume variables
+     * \param scv The sub control volume
      */
     template<class PartialDerivativeMatrix>
     void addStorageDerivatives(PartialDerivativeMatrix& partialDerivatives,
@@ -188,11 +187,11 @@ public:
      * \brief TODO docme!
      *
      * \param partialDerivatives TODO docme!
-     * \param problem TODO docme!
+     * \param problem The problem
      * \param element The element
      * \param fvGeometry The finite volume geometry context
-     * \param curVolVars TODO docme!
-     * \param scv The sub control volume.
+     * \param curVolVars The current volume variables
+     * \param scv The sub control volume
      */
     template<class PartialDerivativeMatrix>
     void addSourceDerivatives(PartialDerivativeMatrix& partialDerivatives,

dumux/porousmediumflow/tracer/model.hh

@@ -16,7 +16,6 @@
  *   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 TracerModel

dumux/porousmediumflow/tracer/volumevariables.hh

@@ -19,8 +19,9 @@
 /*!
  * \file
  * \ingroup TracerModel
- * \brief Quantities required by the tracer model in a control volume
+ * \brief Quantities required by the tracer model in a control volume.
  */
+
 #ifndef DUMUX_TRACER_VOLUME_VARIABLES_HH
 #define DUMUX_TRACER_VOLUME_VARIABLES_HH
 
@@ -45,12 +46,12 @@ class TracerVolumeVariables
     static constexpr bool useMoles = Traits::ModelTraits::useMoles();
 
 public:
-    //! export fluid system type
+    //! Export fluid system type
     using FluidSystem = typename Traits::FluidSystem;
     using SolidState = typename Traits::SolidState;
 
     /*!
-     * \brief Update all quantities for a given control volume
+     * \brief Updates all quantities for a given control volume.
      *
      * \param elemSol A vector containing all primary variables connected to the element
      * \param problem The object specifying the problem which ought to
@@ -82,7 +83,7 @@ public:
     }
 
     /*!
-     * \brief Return density \f$\mathrm{[kg/m^3]}\f$ the of the fluid phase.
+     * \brief Returns the density \f$\mathrm{[kg/m^3]}\f$ the of the fluid phase.
      *
      * We always forward to the fluid state with the phaseIdx property (see class description).
      *
@@ -98,66 +99,66 @@ public:
     { return solidState_; }
 
     /*!
-     * \brief Return the saturation
+     * \brief Returns the saturation.
      *
      * This method is here for compatibility reasons with other models. The saturation
      * is always 1.0 in a one-phasic context.
      *
-     * \param pIdx TODO docme!
+     * \param pIdx The phase index
      */
     Scalar saturation(int pIdx = 0) const
     { return 1.0; }
 
     /*!
-     * \brief Return the mobility
+     * \brief Returns the mobility.
      *
      * This method is here for compatibility reasons with other models. The mobility is always 1
      * for one-phasic models where the velocity field is given
      *
-     * \param pIdx TODO docme!
+     * \param pIdx The phase index
      */
     Scalar mobility(int pIdx = 0) const
     { return 1.0; }
 
     /*!
-     * \brief Return molar density \f$\mathrm{[mol/m^3]}\f$ the of the fluid phase.
+     * \brief Returns the molar density \f$\mathrm{[mol/m^3]}\f$ the of the fluid phase.
      *
-     * \param pIdx TODO docme!
+     * \param pIdx The phase index
      */
     Scalar molarDensity(int pIdx = 0) const
     { return fluidDensity_/fluidMolarMass_; }
 
     /*!
-     * \brief Return mole fraction \f$\mathrm{[mol/mol]}\f$ of a component in the phase.
+     * \brief Returns the mole fraction \f$\mathrm{[mol/mol]}\f$ of a component in the phase.
      *
-     * \param pIdx TODO docme!
+     * \param pIdx The phase index
      * \param compIdx The index of the component
      */
     Scalar moleFraction(int pIdx, int compIdx) const
     { return useMoles ? moleOrMassFraction_[compIdx] : moleOrMassFraction_[compIdx]/FluidSystem::molarMass(compIdx)*fluidMolarMass_; }
 
     /*!
-     * \brief Return mass fraction \f$\mathrm{[kg/kg]}\f$ of a component in the phase.
+     * \brief Returns the mass fraction \f$\mathrm{[kg/kg]}\f$ of a component in the phase.
      *
-     * \param pIdx TODO docme!
+     * \param pIdx The phase index
      * \param compIdx The index of the component
      */
     Scalar massFraction(int pIdx, int compIdx) const
     { return useMoles ? moleOrMassFraction_[compIdx]*FluidSystem::molarMass(compIdx)/fluidMolarMass_ : moleOrMassFraction_[compIdx]; }
 
     /*!
-     * \brief Return concentration \f$\mathrm{[mol/m^3]}\f$  of a component in the phase.
+     * \brief Returns the concentration \f$\mathrm{[mol/m^3]}\f$  of a component in the phase.
      *
-     * \param pIdx TODO docme!
+     * \param pIdx The phase index
      * \param compIdx The index of the component
      */
     Scalar molarity(int pIdx, int compIdx) const
     { return moleFraction(pIdx, compIdx)*molarDensity(); }
 
     /*!
-     * \brief Return the binary diffusion coefficient \f$\mathrm{[m^2/s]}\f$ in the fluid.
+     * \brief Returns the binary diffusion coefficient \f$\mathrm{[m^2/s]}\f$ in the fluid.
      *
-     * \param pIdx TODO docme!
+     * \param pIdx The phase index
      * \param compIdx The index of the component
      */
     Scalar diffusionCoefficient(int pIdx, int compIdx) const