[Doc] Fix incorrect use of @internal command

Cantera · May 30, 2022 · 21c0653 · 21c0653
1 parent af33ed6
commit 21c0653
Show file tree

Hide file tree

Showing 13 changed files with 16 additions and 41 deletions.
diff --git a/include/cantera/base/Units.h b/include/cantera/base/Units.h
@@ -90,7 +90,7 @@ class Units
  *  simplifies access when joining exponents. The utility is used in the context
  *  of effective reaction rate units.
  *
- * @internal Helper utility class.
+ * @note Helper utility class for internal use within Cantera.
  *
  * @warning This class is an experimental part of the %Cantera API and
  *    may be changed or removed without notice.

diff --git a/include/cantera/base/global.h b/include/cantera/base/global.h
@@ -263,7 +263,7 @@ template <typename T> int sign(T x) {
 
 //! Convert a type name to a human readable string, using `boost::core::demangle` if
 //! available. Also has a set of short names for some common types.
-//! @internal Mainly for use by AnyMap and Delegator
+//! @note Mainly for internal use by AnyMap and Delegator
 std::string demangle(const std::type_info& type);
 
 }

diff --git a/include/cantera/kinetics/BlowersMaselRate.h b/include/cantera/kinetics/BlowersMaselRate.h
@@ -138,7 +138,6 @@ class BlowersMaselRate : public ArrheniusBase
 protected:
     //! Return the effective activation energy (a function of the delta H of reaction)
     //! divided by the gas constant (that is, the activation temperature) [K]
-    //! @internal  The enthalpy change of reaction is not an independent parameter
     double effectiveActivationEnergy_R(double deltaH_R) const {
         if (deltaH_R < -4 * m_Ea_R) {
             return 0.;
@@ -170,7 +169,7 @@ class BlowersMaselRate : public ArrheniusBase
 
     //! Set current enthalpy change of reaction [J/kmol]
     /*!
-     *  @internal  used for testing purposes only; note that this quantity is not an
+     *  @note  used for testing purposes only; This quantity is not an
      *      independent variable and will be overwritten during an update of the state.
      *
      *  @warning  This method is an experimental part of the %Cantera API and

diff --git a/include/cantera/kinetics/GasKinetics.h b/include/cantera/kinetics/GasKinetics.h
@@ -91,7 +91,7 @@ class GasKinetics : public BulkKinetics
 protected:
     //! @name Internal service methods
     //!
-    //! These methods are for @internal use, and seek to avoid code duplication
+    //! @note These methods are for internal use, and seek to avoid code duplication
     //! while evaluating terms used for rate constants, rates of progress, and
     //! their derivatives.
     //! @{

diff --git a/include/cantera/kinetics/InterfaceRate.h b/include/cantera/kinetics/InterfaceRate.h
@@ -213,9 +213,9 @@ class InterfaceRateBase
 
     //! Set site density [kmol/m^2]
     /*!
-     *  @internal  This method is used for testing purposes only as the site density
-     *      is a property of InterfaceKinetics and will be overwritten during an update
-     *      of the thermodynamic state.
+     *  @note  This method is used internally, for testing purposes only as the site
+     *      density is a property of InterfaceKinetics and will be overwritten during an
+     *      update of the thermodynamic state.
      *
      *  @warning  This method is an experimental part of the %Cantera API and
      *      may be changed or removed without notice.
@@ -303,7 +303,7 @@ class StickingCoverage : public InterfaceRateBase
 
     //! Set exponent applied to site density (sticking order)
     /*!
-     *  @internal  This method is used for testing purposes only as the value is
+     *  @note  This method is used for internal testing purposes only as the value is
      *      determined automatically by setContext.
      *
      *  @warning  This method is an experimental part of the %Cantera API and
@@ -320,7 +320,7 @@ class StickingCoverage : public InterfaceRateBase
 
     //! Set the molecular weight of the sticking species
     /*!
-     *  @internal  This method is used for testing purposes only as the value is
+     *  @note  This method is used for internal testing purposes only as the value is
      *      determined automatically by setContext.
      *
      *  @warning  This method is an experimental part of the %Cantera API and

diff --git a/include/cantera/kinetics/Reaction.h b/include/cantera/kinetics/Reaction.h
@@ -189,9 +189,9 @@ class Reaction
     //! Flag indicating whether reaction is set up correctly
     bool m_valid;
 
-    //! @internal  Helper function returning vector of undeclared third body species
+    //! Helper function returning vector of undeclared third body species
     //! and a boolean expression indicating whether the third body is specified.
-    //! The function is used by the checkSpecies method and only needed as long as
+    //! @note The function is used by the checkSpecies method and only needed as long as
     //! there is no unified approach to handle third body collision partners.
     //! @param kin  Kinetics object
     virtual std::pair<std::vector<std::string>, bool>

diff --git a/include/cantera/kinetics/StoichManager.h b/include/cantera/kinetics/StoichManager.h
@@ -125,7 +125,6 @@ namespace Cantera
  * Handles one species in a reaction.
  * See @ref Stoichiometry
  * @ingroup Stoichiometry
- * @internal
  */
 class C1
 {
@@ -596,16 +595,6 @@ class StoichManagerN
 public:
     /**
      * Constructor for the StoichManagerN class.
-     *
-     * @internal Consider adding defaulted entries here that supply the total
-     *     number of reactions in the mechanism and the total number of species
-     *     in the species list. Then, we could use those numbers to provide
-     *     error checks during the construction of the object. Those numbers
-     *     would also provide some clarity to the purpose and utility of this
-     *     class.
-     *
-     * DGG - the problem is that the number of reactions and species are not
-     * known initially.
      */
     StoichManagerN() : m_ready(true) {
         m_stoichCoeffs.setZero();

diff --git a/include/cantera/thermo/IdealGasPhase.h b/include/cantera/thermo/IdealGasPhase.h
@@ -577,7 +577,7 @@ class IdealGasPhase: public ThermoPhase
     //! Temporary array containing internally calculated partial pressures
     mutable vector_fp m_pp;
 
-    //! @internal Update the species reference state thermodynamic functions
+    //! Update the species reference state thermodynamic functions
     /*!
      *  This method is called each time a thermodynamic property is requested,
      *  to check whether the internal species properties within the object

diff --git a/include/cantera/thermo/SingleSpeciesTP.h b/include/cantera/thermo/SingleSpeciesTP.h
@@ -257,11 +257,8 @@ class SingleSpeciesTP : public ThermoPhase
     //! Dimensionless entropy at the (mtlast, m_p0)
     mutable double m_s0_R;
 
-    /**
-     * @internal This crucial internal routine calls the species thermo update
-     *        program to calculate new species Cp0, H0, and S0 whenever the
-     *        temperature has changed.
-     */
+    //! This internal routine calculates new species Cp0, H0, and S0 whenever the
+    //! temperature has changed.
     void _updateThermo() const;
 };
 

diff --git a/include/cantera/thermo/ThermoPhase.h b/include/cantera/thermo/ThermoPhase.h
@@ -1576,15 +1576,12 @@ class ThermoPhase : public Phase
     //! reference-state thermodynamic properties
     /*!
      * @param k   Species id. The default is -1, meaning return the default
-     *
-     * @internal
      */
     virtual MultiSpeciesThermo& speciesThermo(int k = -1);
 
     virtual const MultiSpeciesThermo& speciesThermo(int k = -1) const;
 
     /**
-     * @internal
      * Initialize a ThermoPhase object using an input file.
      *
      * Used to implement constructors for derived classes which take a
@@ -1599,8 +1596,6 @@ class ThermoPhase : public Phase
 
     //! Initialize the ThermoPhase object after all species have been set up
     /*!
-     * @internal Initialize.
-     *
      * This method is provided to allow subclasses to perform any initialization
      * required after all species have been added. For example, it might be used
      * to resize internal work arrays that must have an entry for each species.

diff --git a/include/cantera/thermo/VPStandardStateTP.h b/include/cantera/thermo/VPStandardStateTP.h
@@ -190,8 +190,6 @@ class VPStandardStateTP : public ThermoPhase
     //! Updates the standard state thermodynamic functions at the current T and
     //! P of the solution.
     /*!
-     * @internal
-     *
      * If m_useTmpStandardStateStorage is true,
      * this function must be called for every call to functions in this class.
      *

diff --git a/include/cantera/thermo/WaterSSTP.h b/include/cantera/thermo/WaterSSTP.h
@@ -185,10 +185,7 @@ class WaterSSTP : public SingleSpeciesTP
     void _allowGasPhase(bool flag) { m_allowGasPhase = flag; }
 
 protected:
-    /**
-     * @internal This internal routine must be overridden because it is not
-     *        applicable.
-     */
+    //! This routine must be overridden because it is not applicable.
     void _updateThermo() const;
 
 private:

diff --git a/interfaces/cython/cantera/utils.pyx b/interfaces/cython/cantera/utils.pyx
@@ -373,7 +373,7 @@ cdef vector[vector[string]] list2_string_to_anyvalue(data):
     return v
 
 def _py_to_any_to_py(dd):
-    # @internal  used for testing purposes only
+    # used for internal testing purposes only
     cdef string name = stringify("test")
     cdef CxxAnyValue vv = python_to_anyvalue(dd)
     return anyvalue_to_python(name, vv), pystr(vv.type_str())