[Doc] Update docs for ReactionData and SurfaceArrhenius

include/cantera/kinetics/ReactionData.h

@@ -1,10 +1,8 @@
 /**
  *  @file ReactionData.h
- *
  */
 // Copyright 2001  California Institute of Technology
 
-
 #ifndef CT_REACTION_DATA_H
 #define CT_REACTION_DATA_H
 
@@ -13,10 +11,11 @@
 namespace Cantera
 {
 
+//! Intermediate class which stores data about a reaction and its rate
+//! parameterization before adding the reaction to a Kinetics object.
 class ReactionData
 {
 public:
-    //! Default constructor
     ReactionData() {
         reactionType = ELEMENTARY_RXN;
         validate = false;
@@ -33,29 +32,44 @@ public:
         beta = 0.0;
     }
 
-    //! Destructor
     virtual ~ReactionData() {}
 
-    //! type of the reaction
-    /*!
-     *  The valid types are listed in the file, reaction_defs.h.
-     */
+    //! Type of the reaction. The valid types are listed in the file,
+    //! reaction_defs.h, with constants ending in `RXN`.
     int reactionType;
 
-    bool validate;
-    int number;
-    int rxn_number;
-    std::vector<size_t> reactants;
-    std::vector<size_t> products;
+    bool validate; //!< Perform validation of the rate coefficient data
+    int number; //!< Index of this reaction within the mechanism
+    int rxn_number; //!< @deprecated duplicate of #number
+    std::vector<size_t> reactants; //!< Indices of reactant species
+    std::vector<size_t> products; //!< Indices of product species
+
+    //! Reaction order with respect to each reactant species, in the order
+    //! given by #reactants. Usually the same as the stoichiometric
+    //! coefficients.
     vector_fp rorder;
+
+    //! Reaction order of the reverse reaction with respect to each product
+    //! species, in the order given by #products. Usually the same as the
+    //! stoichiometric coefficients.
     vector_fp porder;
+
+    //! Reactant stoichiometric coefficients, in the order given by
+    //! #reactants.
     vector_fp rstoich;
+
+    //! Product stoichiometric coefficients, in the order given by #products.
     vector_fp pstoich;
-    std::vector<grouplist_t> rgroups;
-    std::vector<grouplist_t> pgroups;
+
+    std::vector<grouplist_t> rgroups; //!< Optional data used in reaction path diagrams
+    std::vector<grouplist_t> pgroups; //!< Optional data used in reaction path diagrams
+
+    //! Map of species index to third body efficiency
     std::map<size_t, doublereal> thirdBodyEfficiencies;
 
-    //! Net stoichiometric coefficients for participating species
+    //! Net stoichiometric coefficients for participating species. Used for
+    //! duplicate reaction detection. Key is `-1-k` for reactants, `1+k` for
+    //! products.
     std::map<int, doublereal> net_stoich;
 
     //! True if the current reaction is reversible. False otherwise
@@ -71,21 +85,52 @@ public:
      */
     int rateCoeffType;
 
-    //! Vector of rate coefficient parameters
+    //! Vector of rate coefficient parameters. For elementary reactions, these
+    //! are the pre- exponential factor, temperature exponent, and activation
+    //! energy in the Arrhenius expression.
     vector_fp rateCoeffParameters;
 
-    //! Vector of auxiliary rate coefficient parameters
+    //! Vector of auxiliary rate coefficient parameters. This is used for
+    //! the alternate Arrhenius parameters used in falloff and chemically
+    //! activated reactions.
     vector_fp auxRateCoeffParameters;
 
+    //! Type of falloff parameterization to use. Values are defined in
+    //! reaction_defs.h, with names ending in `FALLOFF`.
     int falloffType;
+
+    //! Values used in the falloff parameterization. Meaning of each parameter
+    //! depends on #falloffType.
     vector_fp falloffParameters;
-    int error;
+
+    int error; //!< @deprecated unused
+
+    //! The reaction equation. Used only for display purposes.
     std::string equation;
+
+    //! The default third body efficiency for species not listed in
+    //! #thirdBodyEfficiencies.
     doublereal default_3b_eff;
+
+    //! Adjustments to the Arrhenius rate expression dependent on surface
+    //! species coverages. Contains 4 elements for each coverage dependency:
+    //! the species index, and the three coverage parameters (a, E, m). See
+    //! SurfaceArrhenius for details on the parameterization.
     vector_fp cov;
+
+    //! True for "global" reactions which do not follow elementary mass action
+    //! kinetics, i.e. reactions for which the reaction order is not given by
+    //! the stoichiometric coefficients.
     bool global;
+
+    //! Some reactions can be elementary reactions but have fractional
+    //! stoichiometries with respect to some products and reactants. An
+    //! example of these are solid reactions involving phase transformations.
+    //! Species with fractional stoichiometries must be from single-species
+    //! phases with unity activities.
     bool isReversibleWithFrac;
-    doublereal beta;  // for electrochemical reactions
+
+    doublereal beta; //!< for electrochemical reactions
 
     //! Arrhenius parameters for P-log reactions.
     //! The keys are the pressures corresponding to each Arrhenius expression.

include/cantera/kinetics/RxnRates.h

@@ -130,6 +130,17 @@ protected:
 
 /**
  * An Arrhenius rate with coverage-dependent terms.
+ *
+ * The rate expression is given by:
+ * \f[
+ *     k_f = A T^b \exp \left(
+ *             \sum a_k \theta_k
+ *             - \frac{1}{RT} \left( E_a + \sum E_k\theta_k \right)
+ *             + \sum m_k \log \theta_k
+ *             \right)
+ *   \f]
+ * where the parameters \f$ (a_k, E_k, m_k) \f$ describe the dependency on the
+ * surface coverage of species \f$k, \theta_k \f$.
  */
 class SurfaceArrhenius
 {