[docs] Fix Doxygen autobrief

Cantera · Aug 3, 2023 · 8047989 · 8047989
1 parent 4dd28c4
commit 8047989
Show file tree

Hide file tree

Showing 11 changed files with 55 additions and 51 deletions.
diff --git a/include/cantera/base/SolutionArray.h b/include/cantera/base/SolutionArray.h
@@ -41,8 +41,8 @@ class SolutionArray
 public:
     virtual ~SolutionArray() {}
 
-    /*!
-     *  Instantiate a new SolutionArray reference
+    /**
+     *  Instantiate a new SolutionArray reference.
      *
      *  @param sol  Solution object defining phase definitions
      *  @param size  Number of SolutionArray entries
@@ -55,7 +55,7 @@ class SolutionArray
         return shared_ptr<SolutionArray>(new SolutionArray(sol, size, meta));
     }
 
-    /*!
+    /**
      *  Share locations from an existing SolutionArray and return new reference.
      *
      *  Both SolutionArray object share common data. The method is used for slicing
@@ -92,7 +92,7 @@ class SolutionArray
         return static_cast<int>(m_apiShape.size());
     }
 
-    /*!
+    /**
      *  Print a concise summary of a SolutionArray.
      *  @param keys  List of components to be displayed; if empty, all components are
      *      considered.
@@ -126,15 +126,15 @@ class SolutionArray
     //! auxiliary variable)
     bool hasComponent(const string& name) const;
 
-    /*!
+    /**
      *  Retrieve a component of the SolutionArray by name.
      *  Returns an AnyValue containing an array with length size() with a type
      *  specific to the component; in most cases, the type is double, but may differ
      *  for auxiliary data.
      */
     AnyValue getComponent(const string& name) const;
 
-    /*!
+    /**
      *  Set a component of the SolutionArray by name.
      *  The passed AnyValue should containing an array with length size() with a type
      *  specific to the component; in most cases, the type is double, but may differ
@@ -145,12 +145,12 @@ class SolutionArray
      */
     void setComponent(const string& name, const AnyValue& data);
 
-    /*!
+    /**
      *  Update the buffered location used to access SolutionArray entries.
      */
     void setLoc(int loc, bool restore=true);
 
-    /*!
+    /**
      *  Update state at given location to state of associated Solution object.
      */
     void updateState(int loc);
@@ -164,7 +164,7 @@ class SolutionArray
     //! Normalize mass/mole fractions
     void normalize();
 
-    /*!
+    /**
      *  Add auxiliary component to SolutionArray. Initialization requires a subsequent
      *  call of setComponent.
      *
@@ -192,7 +192,7 @@ class SolutionArray
     //! Append location entry at end of SolutionArray.
     void append(const vector<double>& state, const AnyMap& extra);
 
-    /*!
+    /**
      *  Write header data to a HDF container file.
      *
      *  @param fname  Name of HDF container file
@@ -203,7 +203,7 @@ class SolutionArray
     static void writeHeader(const string& fname, const string& name, const string& desc,
                             bool overwrite=false);
 
-    /*!
+    /**
      *  Write header data to AnyMap; used by YAML serialization.
      *
      *  @param root  Root node of AnyMap structure
@@ -214,7 +214,7 @@ class SolutionArray
     static void writeHeader(AnyMap& root, const string& name, const string& desc,
                             bool overwrite=false);
 
-    /*!
+    /**
      *  Write SolutionArray data to a CSV file.
      *
      *  @param fname  Name of CSV file
@@ -225,7 +225,7 @@ class SolutionArray
      */
     void writeEntry(const string& fname, bool overwrite=false, const string& basis="");
 
-    /*!
+    /**
      *  Write SolutionArray data to a HDF container file.
      *
      *  @param fname  Name of HDF container file
@@ -237,8 +237,8 @@ class SolutionArray
     void writeEntry(const string& fname, const string& name, const string& sub,
                     bool overwrite=false, int compression=0);
 
-    /*!
-     *  Write SolutionArray data to AnyMap; used by YAML serialization.
+    /**
+     *  Write SolutionArray data to AnyMap. Used by YAML serialization.
      *
      *  @param root  Root node of AnyMap structure
      *  @param name  Identifier of node holding header information and subgroup
@@ -248,7 +248,7 @@ class SolutionArray
     void writeEntry(AnyMap& root, const string& name, const string& sub,
                     bool overwrite=false);
 
-    /*!
+    /**
      *  Save current SolutionArray contents to a data file.
      *
      *  Data can be saved either in CSV format (extension '*.csv'), YAML container
@@ -286,23 +286,23 @@ class SolutionArray
               const string& desc="", bool overwrite=false, int compression=0,
               const string& basis="");
 
-    /*!
+    /**
      *  Read header information from a HDF container file.
      *
      *  @param fname  Name of HDF container file
      *  @param name  Identifier of group holding header information
      */
     static AnyMap readHeader(const string& fname, const string& name);
 
-    /*!
-     *  Read header information from AnyMap; used by YAML serialization.
+    /**
+     *  Read header information from AnyMap. Used by YAML serialization.
      *
      *  @param root  Root node of AnyMap structure
      *  @param name  Identifier of node holding header information
      */
     static AnyMap readHeader(const AnyMap& root, const string& name);
 
-    /*!
+    /**
      *  Restore SolutionArray data from a HDF container file.
      *
      *  @param fname  Name of HDF container file
@@ -311,7 +311,7 @@ class SolutionArray
      */
     void readEntry(const string& fname, const string& name, const string& sub);
 
-    /*!
+    /**
      *  Restore SolutionArray data from AnyMap; used by YAML serialization.
      *
      *  @param root  Root node of AnyMap structure
@@ -320,7 +320,7 @@ class SolutionArray
      */
     void readEntry(const AnyMap& root, const string& name, const string& sub);
 
-    /*!
+    /**
      *  Restore SolutionArray data and header information from a container file.
      *
      *  This method retrieves data from a YAML or HDF files that were previously saved
@@ -339,34 +339,35 @@ class SolutionArray
     //! Service function used to resize SolutionArray
     void _resize(size_t size);
 
-    /*!
-     *  Initialize extra SolutionArray component
+    /**
+     *  Initialize extra SolutionArray component.
      *
      *  @param name  Name of component (property defining auxiliary variable)
      *  @param value  Default value; used to determine type of component
      */
     void _initExtra(const string& name, const AnyValue& value);
 
-    /*!
-     *  Resize extra SolutionArray component
+    /**
+     *  Resize extra SolutionArray component.
      *
      *  @param name  Name of component (property defining auxiliary variable)
      *  @param value  Default value
      */
     void _resizeExtra(const string& name, const AnyValue& value=AnyValue());
 
-    /*!
+    /**
      *  Set extra SolutionArray component
      *
      *  @param name  Name of component (property defining auxiliary variable)
      *  @param data  Value to be set
      */
     void _setExtra(const string& name, const AnyValue& data=AnyValue());
 
-    /*!
-     *  Identify storage mode of state data (combination of properties defining state);
-     *  valid modes include Phase::nativeState ("native") or other property combinations
-     *  defined by Phase::fullStates (three-letter acronyms, for example "TDY", "TPX").
+    /**
+     *  Identify storage mode of state data. The storage mode is a combination of
+     *  properties defining state); valid modes include Phase::nativeState ("native") or
+     *  other property combinations defined by Phase::fullStates (three-letter acronyms,
+     *  for example "TDY", "TPX").
      */
     string _detectMode(const set<string>& names, bool native=true);
 

diff --git a/include/cantera/base/Storage.h b/include/cantera/base/Storage.h
@@ -27,8 +27,8 @@ namespace HighFive {
 namespace Cantera
 {
 
-/*!
- *  A wrapper class handling storage to HDF; acts as a thin wrapper for HighFive.
+/**
+ *  A wrapper class handling storage to HDF. Acts as a thin wrapper for HighFive.
  *  The class implements methods that are intended to be called from SolutionArray.
  *
  *  @since New in %Cantera 3.0.

diff --git a/include/cantera/base/ValueCache.h b/include/cantera/base/ValueCache.h
@@ -14,7 +14,8 @@
 namespace Cantera
 {
 
-/*! A cached property value and the state at which it was evaluated
+/**
+ * A cached property value and the state at which it was evaluated.
  *
  * This struct stores the value of some property evaluated at a particular
  * thermodynamic state. The #value can be either a real scalar or an array,
@@ -115,7 +116,8 @@ struct CachedValue {
 typedef CachedValue<double>& CachedScalar;
 typedef CachedValue<vector_fp>& CachedArray;
 
-/*! Storage for cached values
+/**
+ * Storage for cached values.
  *
  * Stores cached values of properties evaluated at a particular thermodynamic
  * state. A class that needs cached values can have a ValueCache as a

diff --git a/include/cantera/equil/MultiPhaseEquil.h b/include/cantera/equil/MultiPhaseEquil.h
@@ -11,7 +11,7 @@
 namespace Cantera
 {
 
-/*!
+/**
  * Multiphase chemical equilibrium solver. Class MultiPhaseEquil is designed
  * to be used to set a mixture containing one or more phases to a state of
  * chemical equilibrium. It implements the VCS algorithm, described in Smith

diff --git a/include/cantera/kinetics/KineticsFactory.h b/include/cantera/kinetics/KineticsFactory.h
@@ -101,8 +101,8 @@ unique_ptr<Kinetics> newKinetics(const std::vector<ThermoPhase*>& phases,
                                  const std::string& filename,
                                  const std::string& phase_name);
 
-/*!
- * @brief Add reactions to a Kinetics object.
+/**
+ * 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

diff --git a/include/cantera/numerics/FuncEval.h b/include/cantera/numerics/FuncEval.h
@@ -86,7 +86,7 @@ class FuncEval
      */
     int evalDaeNoThrow(double t, double* y, double* ydot, double* residual);
 
-    /*! Evaluate the setup processes for the Jacobian preconditioner.
+    /** Evaluate the setup processes for the Jacobian preconditioner.
      * @param[in] t time.
      * @param[in] y solution vector, length neq()
      * @param gamma the gamma in M=I-gamma*J
@@ -97,7 +97,7 @@ class FuncEval
         throw NotImplementedError("FuncEval::preconditionerSetup");
     }
 
-    /*! Evaluate the linear system Ax=b where A is the preconditioner.
+    /** Evaluate the linear system Ax=b where A is the preconditioner.
      * @param[in] rhs right hand side vector used in linear system
      * @param[out] output output vector for solution
      * @warning This function is an experimental part of the %Cantera API and may be
@@ -112,7 +112,7 @@ class FuncEval
         throw NotImplementedError("FuncEval::updatePreconditioner");
     }
 
-    /*! Preconditioner setup that doesn't throw an error but returns a
+    /** Preconditioner setup that doesn't throw an error but returns a
      * CVODES flag. It also helps as a first level of polymorphism
      * which identifies the specific FuncEval, e.g., ReactorNet.
      * @param[in] t time.
@@ -123,7 +123,7 @@ class FuncEval
      */
     int preconditioner_setup_nothrow(double t, double* y, double gamma);
 
-    /*! Preconditioner solve that doesn't throw an error but returns a
+    /** Preconditioner solve that doesn't throw an error but returns a
      * CVODES flag. It also helps as a first level of polymorphism
      * which identifies the specific FuncEval, e.g., ReactorNet.
      * @param[in] rhs right hand side vector used in linear system

diff --git a/include/cantera/oneD/OneDim.h b/include/cantera/oneD/OneDim.h
@@ -137,7 +137,7 @@ class OneDim
         return m_bw;
     }
 
-    /*!
+    /**
      * Initialize all domains. On the first call, this methods calls the init
      * method of each domain, proceeding from left to right. Subsequent calls
      * do nothing.
@@ -174,7 +174,7 @@ class OneDim
         return (m_rdt == 0.0);
     }
 
-    /*!
+    /**
      * Prepare to solve the steady-state problem. After invoking this method,
      * subsequent calls to solve() will solve the steady-state problem. Sets
      * the reciprocal of the time step to zero, and, if it was previously non-
@@ -210,7 +210,7 @@ class OneDim
         return m_mask;
     }
 
-    /*!
+    /**
      * Take time steps using Backward Euler.
      *
      * @param nsteps number of steps

diff --git a/include/cantera/oneD/StFlow.h b/include/cantera/oneD/StFlow.h
@@ -292,7 +292,7 @@ class StFlow : public Domain1D
         m_dovisc = dovisc;
     }
 
-    /*!
+    /**
      *  Evaluate the residual function for axisymmetric stagnation flow. If
      *  j == npos, the residual function is evaluated at all grid points.
      *  Otherwise, the residual function is only evaluated at grid points

diff --git a/include/cantera/transport/IonGasTransport.h b/include/cantera/transport/IonGasTransport.h
@@ -58,7 +58,8 @@ class IonGasTransport : public MixTransport
     //! The binary transport between two charged species is neglected.
     virtual void getMixDiffCoeffs(double* const d);
 
-    /*! The electrical conductivity (Siemens/m).
+    /**
+     * The electrical conductivity (Siemens/m).
      * @f[
      *     \sigma = \sum_k{\left|C_k\right| \mu_k \frac{X_k P}{k_b T}}
      * @f]

diff --git a/include/cantera/transport/Transport.h b/include/cantera/transport/Transport.h
@@ -184,7 +184,7 @@ class Transport
             return transportModel();
     }
 
-    /*!
+    /**
      * Phase object. Every transport manager is designed to compute properties
      * for a specific phase of a mixture, which might be a liquid solution, a
      * gas mixture, a surface, etc. This method returns a reference to the
@@ -194,7 +194,7 @@ class Transport
         return *m_thermo;
     }
 
-    /*!
+    /**
      * Returns true if the transport manager is ready for use.
      * @deprecated To be removed after %Cantera 3.0.
      */
@@ -225,7 +225,7 @@ class Transport
     //! @name Transport Properties
     //! @{
 
-    /*!
+    /**
      * The viscosity in Pa-s.
      */
     virtual double viscosity() {

diff --git a/include/cantera/zeroD/Reactor.h b/include/cantera/zeroD/Reactor.h
@@ -132,7 +132,7 @@ class Reactor : public ReactorBase
     //! coefficients for governing equations, length m_nv, default values 0
     virtual void eval(double t, double* LHS, double* RHS);
 
-    /*!
+    /**
      * Evaluate the reactor governing equations. Called by ReactorNet::eval.
      * @param[in] t time.
      * @param[in] y solution vector, length neq()