[docs] Restructure Kinetics doxygen documentation

include/cantera/kinetics/Arrhenius.h

@@ -33,20 +33,12 @@ struct ArrheniusData : public ReactionData
 };
 
 
-/**
- *  @defgroup arrheniusGroup  Arrhenius-type Parameterizations
- *
- *  This section describes the parameterizations used to describe the standard
- *  Arrhenius rate parameterization and derived models.
- *
- *  @ingroup chemkinetics
- */
-
 //! Base class for Arrhenius-type Parameterizations
 /*!
  * This base class provides a minimally functional interface that allows for parameter
  * access from derived classes as well as classes that use Arrhenius-type expressions
  * internally, for example FalloffRate and PlogRate.
+ * @ingroup arrheniusGroup
  */
 class ArrheniusBase : public ReactionRate
 {

include/cantera/kinetics/BulkKinetics.h

@@ -1,6 +1,5 @@
 /**
  * @file BulkKinetics.h
- * @ingroup chemkinetics
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or
@@ -17,7 +16,7 @@ namespace Cantera
 {
 
 //! Specialization of Kinetics for chemistry in a single bulk phase
-//! @ingroup kinetics
+//! @ingroup kineticsmgr
 class BulkKinetics : public Kinetics
 {
 public:

include/cantera/kinetics/ChebyshevRate.h

@@ -85,6 +85,8 @@ struct ChebyshevData : public ReactionData
  * Chebyshev polynomials are not defined outside the interval (-1,1), and
  * therefore extrapolation of rates outside the range of temperatures and
  * pressures for which they are defined is strongly discouraged.
+ *
+ * @ingroup otherRateGroup
  */
 class ChebyshevRate final : public ReactionRate
 {

include/cantera/kinetics/Custom.h

@@ -32,6 +32,7 @@ class Func1;
  *
  * @warning This class is an experimental part of the %Cantera API and
  *    may be changed or removed without notice.
+ * @ingroup otherRateGroup
  */
 class CustomFunc1Rate final : public ReactionRate
 {

include/cantera/kinetics/EdgeKinetics.h

@@ -1,7 +1,6 @@
 /**
  * @file EdgeKinetics.h
  *
- * @ingroup chemkinetics
  * @ingroup electrochem
  */
 
@@ -18,6 +17,7 @@ namespace Cantera
 /**
  * Heterogeneous reactions at one-dimensional interfaces between
  * multiple adjacent two-dimensional surfaces.
+ * @ingroup kineticsmgr
  */
 class EdgeKinetics : public InterfaceKinetics
 {

include/cantera/kinetics/Falloff.h

@@ -12,16 +12,6 @@ namespace Cantera
 
 class AnyMap;
 
-/**
- *  @defgroup falloffGroup  Falloff Parameterizations
- *
- *  This section describes the parameterizations used to describe
- *  the fall-off in reaction rate constants due to intermolecular
- *  energy transfer.
- *  @ingroup chemkinetics
- */
-
-
 //! Data container holding shared data specific to Falloff rates
 /**
  * The data container `FalloffData` holds precalculated data common to
@@ -76,6 +66,7 @@ struct FalloffData : public ReactionData
  * Base class for falloff rate calculators. Each instance of a subclass of FalloffRate
  * calculates the falloff reaction rate based on specific implementations of the
  * falloff function.
+ * @ingroup falloffGroup
  */
 class FalloffRate : public ReactionRate
 {

include/cantera/kinetics/GasKinetics.h

@@ -1,6 +1,5 @@
 /**
  * @file GasKinetics.h
- * @ingroup chemkinetics
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or
@@ -24,7 +23,7 @@ namespace Cantera
  * Kinetics manager for elementary gas-phase chemistry. This kinetics manager
  * implements standard mass-action reaction rate expressions for low-density
  * gases.
- * @ingroup kinetics
+ * @ingroup kineticsmgr
  * @deprecated Replace with BulkKinetics. To be removed after Cantera 3.0.
  */
 class GasKinetics : public BulkKinetics

include/cantera/kinetics/ImplicitSurfChem.h

@@ -51,7 +51,7 @@ namespace Cantera
  * phase with \f$ N_s \f$ surface sites, it consists of the surface coverages
  * \f$ \theta_k \f$ for \f$ k = 0, N_s - 1 \f$
  *
- * @ingroup  kineticsmgr
+ * @ingroup chemkinetics
  */
 class ImplicitSurfChem : public FuncEval
 {

include/cantera/kinetics/InterfaceKinetics.h

@@ -1,6 +1,5 @@
 /**
  * @file InterfaceKinetics.h
- * @ingroup chemkinetics
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or
@@ -51,7 +50,7 @@ class ImplicitSurfChem;
  * kinetics operator. Nonexistent phases are deemed to be unstable by default,
  * but this can be changed.
  *
- *  @ingroup chemkinetics
+ * @ingroup kineticsmgr
  */
 class InterfaceKinetics : public Kinetics
 {

include/cantera/kinetics/InterfaceRate.h

@@ -18,16 +18,6 @@ namespace Cantera
 
 class AnyMap;
 
-/**
- *  @defgroup surfaceGroup  Coverage-dependent rate parameterizations
- *
- *  This section describes the parameterizations used to describe rate
- *  parameterization that involve interfaces.
- *
- *  @ingroup chemkinetics
- */
-
-
 //! Data container holding shared data for reaction rate specification with interfaces
 /**
  * The data container InterfaceData holds precalculated data common to
@@ -98,6 +88,7 @@ struct InterfaceData : public BlowersMaselData
  * The InterfaceRateBase class implements terms related to coverage only, which allows
  * for combinations with arbitrary rate parameterizations (for example Arrhenius and
  * BlowersMaselRate).
+ * @ingroup surfaceGroup
  */
 class InterfaceRateBase
 {
@@ -273,6 +264,7 @@ class InterfaceRateBase
 //! Base class for rate parameterizations that implement sticking coefficients
 /**
  * The StickingCoverage class enhances Coverage to accommodate sticking coefficients.
+ * @ingroup surfaceGroup
  */
 class StickingCoverage : public InterfaceRateBase
 {
@@ -369,6 +361,7 @@ class StickingCoverage : public InterfaceRateBase
 
 
 //! A class template for interface reaction rate specifications
+//! @ingroup surfaceGroup
 template <class RateType, class DataType>
 class InterfaceRate : public RateType, public InterfaceRateBase
 {
@@ -455,11 +448,17 @@ class InterfaceRate : public RateType, public InterfaceRateBase
     }
 };
 
+//! Arrhenius-type interface reaction rate specifications
+//! @ingroup surfaceGroup
 using InterfaceArrheniusRate = InterfaceRate<ArrheniusRate, InterfaceData>;
+
+//! Blowers-Masel-type interface reaction rate specifications
+//! @ingroup surfaceGroup
 using InterfaceBlowersMaselRate = InterfaceRate<BlowersMaselRate, InterfaceData>;
 
 
 //! A class template for interface sticking rate specifications
+//! @ingroup surfaceGroup
 template <class RateType, class DataType>
 class StickingRate : public RateType, public StickingCoverage
 {
@@ -587,7 +586,12 @@ class StickingRate : public RateType, public StickingCoverage
     }
 };
 
+//! Arrhenius-type interface sticking rate specifications
+//! @ingroup surfaceGroup
 using StickingArrheniusRate = StickingRate<ArrheniusRate, InterfaceData>;
+
+//! Blowers-Masel-type interface sticking rate specifications
+//! @ingroup surfaceGroup
 using StickingBlowersMaselRate = StickingRate<BlowersMaselRate, InterfaceData>;
 
 }

include/cantera/kinetics/Kinetics.h

@@ -26,7 +26,12 @@ class AnyMap;
  * @defgroup chemkinetics Chemical Kinetics
  */
 
+//! @defgroup reactionGroup Reactions and Reaction Rates
+//! Classes for handling reactions and reaction rates.
+//! @ingroup chemkinetics
+
 //! @defgroup kineticsmgr Kinetics Managers
+//! Classes implementing models for chemical kinetics.
 //! @section kinmodman Models and Managers
 //!
 //! A kinetics manager is a C++ class that implements a kinetics model; a
@@ -93,6 +98,10 @@ class AnyMap;
 //! occupy the last 5 locations.
 //! @ingroup chemkinetics
 
+//! @defgroup rateEvaluators Rate Evaluators
+//! These classes are used to evaluate the rates of reactions.
+//! @ingroup chemkinetics
+
 
 //! Public interface for kinetics managers.
 /*!
@@ -1414,8 +1423,6 @@ class Kinetics
      *
      *  @return 0.0 if the stoichiometries are not multiples of one another
      *    Otherwise, it returns the ratio of the stoichiometric coefficients.
-     *
-     * @ingroup kineticsmgr
      */
     double checkDuplicateStoich(std::map<int, double>& r1,
                                 std::map<int, double>& r2) const;

include/cantera/kinetics/KineticsFactory.h

@@ -36,6 +36,9 @@ class KineticsFactory : public Factory<Kinetics>
     static std::mutex kinetics_mutex;
 };
 
+//! @addtogroup kineticsmgr
+//! @{
+
 /**
  *  Create a new kinetics manager.
  *  @deprecated  To be removed after Cantera 3.0; superseded by newKinetics.
@@ -47,9 +50,8 @@ Kinetics* newKineticsMgr(const string& model);
  */
 shared_ptr<Kinetics> newKinetics(const string& model);
 
+//! Create a new kinetics manager, initialize it, and add reactions.
 /*!
- * Create a new kinetics manager, initialize it, and add reactions
- *
  * @param phases     Vector of phases containing species which participate in
  *     reactions, with the phase where the reactions occur (lowest-dimensional
  *     phase) listed first.
@@ -65,16 +67,16 @@ shared_ptr<Kinetics> newKinetics(const vector<shared_ptr<ThermoPhase>>& phases,
                                  const AnyMap& rootNode=AnyMap(),
                                  shared_ptr<Solution> soln={});
 
+//! @brief Create a new kinetics manager, initialize it, and add reactions.
 //! @see newKinetics(const vector<shared_ptr<ThermoPhase>>&, const AnyMap&, const AnyMap&, shared_ptr<Solution>)
 //! @deprecated  To be removed after Cantera 3.0;
 //!     superseded by newKinetics() returning shared_ptr
 unique_ptr<Kinetics> newKinetics(const std::vector<ThermoPhase*>& phases,
                                  const AnyMap& phaseNode,
                                  const AnyMap& rootNode=AnyMap());
 
+//! Create a new kinetics manager, initialize it, and add reactions.
 /*!
- * Create a new kinetics manager, initialize it, and add reactions
- *
  * @param phases      Vector of phases containing species which participate in
  *     reactions, with the phase where the reactions occur (lowest-dimensional
  *     phase) listed first.
@@ -100,7 +102,7 @@ unique_ptr<Kinetics> newKinetics(const std::vector<ThermoPhase*>& phases,
                                  const std::string& phase_name);
 
 /*!
- * Add reactions to a Kinetics object
+ * @brief Add reactions to a Kinetics object.
  *
  * @param kin        The Kinetics object to be initialized
  * @param phaseNode  Phase entry for the phase where the reactions occur. This
@@ -112,6 +114,8 @@ unique_ptr<Kinetics> newKinetics(const std::vector<ThermoPhase*>& phases,
 void addReactions(Kinetics& kin, const AnyMap& phaseNode,
                   const AnyMap& rootNode=AnyMap());
 
+//! @}
+
 }
 
 #endif

include/cantera/kinetics/MultiRate.h

@@ -16,6 +16,7 @@ namespace Cantera
 {
 
 //! A class template handling ReactionRate specializations.
+//! @ingroup rateEvaluators
 template <class RateType, class DataType>
 class MultiRate final : public MultiRateBase
 {

include/cantera/kinetics/MultiRateBase.h

@@ -22,6 +22,7 @@ class Kinetics;
  * Because this class has no template parameters, the Kinetics object can store all of
  * these rate coefficient evaluators as a `vector<shared_ptr<MultiRateBase>>`. All of
  * the actual implementation for this capability is done in the MultiRate class.
+ * @ingroup rateEvaluators
  */
 class MultiRateBase
 {

include/cantera/kinetics/PlogRate.h

@@ -71,6 +71,7 @@ struct PlogData : public ReactionData
  * the rate used in the interpolation formula is the sum of all the rates given
  * at that pressure. For pressures outside the given range, the rate expression
  * at the nearest pressure is used.
+ * @ingroup otherRateGroup
  */
 class PlogRate final : public ReactionRate
 {

include/cantera/kinetics/Reaction.h

@@ -20,8 +20,6 @@ class ThirdBody;
 class ArrheniusRate; // @todo  Remove after Cantera 3.0
 class FalloffRate; // @todo  Remove after Cantera 3.0
 
-//! @defgroup reactionGroup Reactions and reaction rates
-
 //! Abstract base class which stores data about a reaction and its rate
 //! parameterization so that it can be added to a Kinetics object.
 //! @ingroup reactionGroup
@@ -210,6 +208,7 @@ class Reaction
 
 
 //! A class for managing third-body efficiencies, including default values
+//! @ingroup reactionGroup
 class ThirdBody
 {
 public:

include/cantera/kinetics/ReactionData.h

@@ -21,6 +21,7 @@ class Kinetics;
 //! Data container holding shared data used for ReactionRate calculation
 /**
  * The base class defines variables and methods used by all specializations.
+ * @ingroup reactionGroup
  */
 struct ReactionData
 {

include/cantera/kinetics/ReactionRate.h

@@ -42,6 +42,7 @@ class Reaction;
 //!     partners, associated `DataType` containers should implement the methods
 //!     `perturbPressure(double deltaP)` and/or `perturbThirdBodies(double deltaM)`,
 //!     which allow for the calculation of numerical derivatives.
+//! @ingroup reactionGroup
 class ReactionRate
 {
 public:

include/cantera/kinetics/ReactionRateDelegator.h

@@ -64,6 +64,7 @@ class ReactionDataDelegator : public Delegator, public ReactionData
 //! Delegate methods of the ReactionRate class to external functions
 //!
 //! @since New in Cantera 3.0
+//! @ingroup otherRateGroup
 class ReactionRateDelegator : public Delegator, public ReactionRate
 {
 public: