diff --git a/include/cantera/base/ctexceptions.h b/include/cantera/base/ctexceptions.h index 3c6ef9143..c01bcabe6 100644 --- a/include/cantera/base/ctexceptions.h +++ b/include/cantera/base/ctexceptions.h @@ -67,7 +67,11 @@ public: /*! * @param procedure String name for the function within which the error was * generated. - * @param msg Descriptive string describing the type of error message. + * @param msg Descriptive string describing the type of error message. This + * can be a fmt-style format string (i.e. using curly braces to indicate + * fields), which will be used with additional arguments to generate a + * formatted error message + * @param args Arguments which will be used to interpolate the format string */ template CanteraError(const std::string& procedure, const std::string& msg, @@ -255,8 +259,8 @@ public: * @param expr Boolean expression that must be true * @param procedure Character string or std:string expression indicating * the procedure where the assertion failed - * @param message Character string or std:string expression containing - * a descriptive message is added to the thrown error condition. + * Additional arguments are passed on to the constructor for CanteraError to + * generate a formatted error message. * * @ingroup errorhandling */ diff --git a/include/cantera/base/global.h b/include/cantera/base/global.h index 1c0a06ee6..d616758dc 100644 --- a/include/cantera/base/global.h +++ b/include/cantera/base/global.h @@ -160,10 +160,16 @@ inline void debuglog(const std::string& msg, int loglevel) } } -//! @copydoc Application::Messages::writelog(const std::string&) +//! Write a formatted message to the screen. +//! //! This function passes its arguments to the fmt library 'format' function to //! generate a formatted string from a Python-style (curly braces) format -//! string. +//! string. This method is used throughout Cantera to write log messages. It can +//! also be called by user programs. The advantage of using writelog over +//! writing directly to the standard output is that messages written with +//! writelog will display correctly even when Cantera is used from MATLAB or +//! other application that do not have a standard output stream. +//! @ingroup textlogs template void writelog(const std::string& fmt, const Args&... args) { if (sizeof...(args) == 0) { @@ -182,6 +188,7 @@ void writelog(const std::string& fmt, const Args&... args) { * and then feed it into writelog(). * * @param fmt c format string for the following arguments + * #param args arguments used to interpolate the format string * @ingroup textlogs */ template diff --git a/include/cantera/equil/vcs_solve.h b/include/cantera/equil/vcs_solve.h index d3a014e41..e3695760a 100644 --- a/include/cantera/equil/vcs_solve.h +++ b/include/cantera/equil/vcs_solve.h @@ -147,13 +147,13 @@ public: * Rearranges the solution data to put the component data at the * front of the species list. * - * Then, calculates m_stoichCoeffRxnMatrix(jcomp,irxn) the formation + * Then, calculates `m_stoichCoeffRxnMatrix(jcomp,irxn)` the formation * reactions for all noncomponent species in the mechanism. Also * calculates DNG(I) and DNL(I), the net mole change for each formation * reaction. Also, initializes IR(I) to the default state. * - * @param[in] doJustComponents If true, the m_stoichCoeffRxnMatrix and - * m_deltaMolNumPhase are not calculated. + * @param[in] doJustComponents If true, the #m_stoichCoeffRxnMatrix and + * #m_deltaMolNumPhase are not calculated. * @param[in] aw Vector of mole fractions which will be used to * construct an optimal basis from. * @param[in] sa Gram-Schmidt orthog work space (nc in length) sa[j] @@ -175,13 +175,13 @@ public: * calculates the #m_numComponents species. It switches their positions * in the species vector so that they occupy the first #m_numComponents * spots in the species vector. - * - #m_stoichCoeffRxnMatrix(jcomp,irxn) Stoichiometric coefficient + * - `m_stoichCoeffRxnMatrix(jcomp,irxn)` Stoichiometric coefficient * matrix for the reaction mechanism expressed in Reduced Canonical * Form. jcomp refers to the component number, and irxn refers to the * irxn_th non-component species. - * - #m_deltaMolNumPhase(iphase,irxn): Change in the number of moles in + * - `m_deltaMolNumPhase(iphase,irxn)`: Change in the number of moles in * phase, iphase, due to the noncomponent formation reaction, irxn. - * - #m_phaseParticipation(iphase,irxn): This is 1 if the phase, iphase, + * - `m_phaseParticipation(iphase,irxn)`: This is 1 if the phase, iphase, * participates in the formation reaction, irxn, and zero otherwise. */ int vcs_basopt(const bool doJustComponents, double aw[], double sa[], double sm[], @@ -518,7 +518,7 @@ public: /*! * Formation reactions are * reactions which create each noncomponent species from the component - * species. m_stoichCoeffRxnMatrix(jcomp,irxn) are the stoichiometric + * species. `m_stoichCoeffRxnMatrix(jcomp,irxn)` are the stoichiometric * coefficients for these reactions. A stoichiometric coefficient of * one is assumed for species irxn in this reaction. * @@ -1427,7 +1427,7 @@ public: * * NOTE: kspec = irxn + m_numComponents * - * m_stoichCoeffRxnMatrix(j,irxn) : j refers to the component number, and + * `m_stoichCoeffRxnMatrix(j,irxn)` : j refers to the component number, and * irxn refers to the irxn_th non-component species. The stoichiometric * coefficients multiplied by the Formula coefficients of the component * species add up to the negative value of the number of elements in the diff --git a/include/cantera/oneD/Sim1D.h b/include/cantera/oneD/Sim1D.h index a5bb5b05d..2a4257965 100644 --- a/include/cantera/oneD/Sim1D.h +++ b/include/cantera/oneD/Sim1D.h @@ -43,10 +43,10 @@ public: /// Set initial guess for one component for all domains /** - * @param comp component name - * @param pos A vector of relative positions, beginning with 0.0 at the + * @param component component name + * @param locs A vector of relative positions, beginning with 0.0 at the * left of the domain, and ending with 1.0 at the right of the domain. - * @param values A vector of values corresponding to the relative position + * @param vals A vector of values corresponding to the relative position * locations. */ void setInitialGuess(const std::string& component, vector_fp& locs, diff --git a/include/cantera/thermo/AdsorbateThermo.h b/include/cantera/thermo/AdsorbateThermo.h index 920438646..8b6de069a 100644 --- a/include/cantera/thermo/AdsorbateThermo.h +++ b/include/cantera/thermo/AdsorbateThermo.h @@ -40,6 +40,7 @@ public: * @param tlow output - Minimum temperature * @param thigh output - Maximum temperature * @param pref output - reference pressure (Pa). + * @param coeffs Coefficients for the parameterization */ Adsorbate(double tlow, double thigh, double pref, const double* coeffs) : SpeciesThermoInterpType(tlow, thigh, pref) diff --git a/include/cantera/thermo/HMWSoln.h b/include/cantera/thermo/HMWSoln.h index 62afd272d..dfe578247 100644 --- a/include/cantera/thermo/HMWSoln.h +++ b/include/cantera/thermo/HMWSoln.h @@ -1186,7 +1186,7 @@ public: * @param id Optional parameter identifying the name of the * phase. If none is given, the first XML * phase element will be used. - * @deprecated Use #initThermoFile instead. To be removed after Cantera 2.3. + * @deprecated Use initThermoFile() instead. To be removed after Cantera 2.3. */ void constructPhaseFile(std::string inputFile, std::string id); @@ -1208,7 +1208,7 @@ public: * describe the species in the phase. * @param id ID of the phase. If nonnull, a check is done to see if * phaseNode is pointing to the phase with the correct id. - * @deprecated Use #importPhase instead. To be removed after Cantera 2.3. + * @deprecated Use importPhase() instead. To be removed after Cantera 2.3. */ void constructPhaseXML(XML_Node& phaseNode, std::string id); diff --git a/include/cantera/thermo/IonsFromNeutralVPSSTP.h b/include/cantera/thermo/IonsFromNeutralVPSSTP.h index 1d1402a83..43279a0d0 100644 --- a/include/cantera/thermo/IonsFromNeutralVPSSTP.h +++ b/include/cantera/thermo/IonsFromNeutralVPSSTP.h @@ -126,7 +126,7 @@ public: * @param inputFile XML file containing the description of the phase * @param id Optional parameter identifying the name of the phase. If none * is given, the first XML phase element will be used. - * @deprecated Use #initThermoFile instead. To be removed after Cantera 2.3. + * @deprecated Use initThermoFile() instead. To be removed after Cantera 2.3. */ void constructPhaseFile(std::string inputFile, std::string id); @@ -148,7 +148,7 @@ public: * describe the species in the phase. * @param id ID of the phase. If nonnull, a check is done to see if * phaseNode is pointing to the phase with the correct id. - * @deprecated Use #importPhase instead. To be removed after Cantera 2.3. + * @deprecated Use importPhase() instead. To be removed after Cantera 2.3. */ void constructPhaseXML(XML_Node& phaseNode, std::string id); diff --git a/include/cantera/thermo/MultiSpeciesThermo.h b/include/cantera/thermo/MultiSpeciesThermo.h index 7d27cc4a2..b49d7da51 100644 --- a/include/cantera/thermo/MultiSpeciesThermo.h +++ b/include/cantera/thermo/MultiSpeciesThermo.h @@ -66,7 +66,7 @@ public: * This will set up the thermo for one species */ virtual void install_STIT(size_t index, - shared_ptr stit_ptr); + shared_ptr stit); //! Modify the species thermodynamic property parameterization for a species /*! @@ -74,7 +74,7 @@ public: * @param spec Pointer to the SpeciesThermoInterpType object */ virtual void modifySpecies(size_t index, - shared_ptr stit_ptr); + shared_ptr spec); //! Install a PDSS object to handle the reference state thermodynamics //! calculation diff --git a/include/cantera/thermo/ThermoFactory.h b/include/cantera/thermo/ThermoFactory.h index ee4694266..28591ead1 100644 --- a/include/cantera/thermo/ThermoFactory.h +++ b/include/cantera/thermo/ThermoFactory.h @@ -201,8 +201,6 @@ ThermoPhase* newPhase(const std::string& infile, std::string id=""); * thermodynamics for this phase. We initialize part of the * ThermoPhase object here, especially for those objects which are * part of the Cantera Kernel. - * @param spfactory species Thermo factory pointer, if available. If not - * available, one will be created. * @ingroup thermoprops */ void importPhase(XML_Node& phase, ThermoPhase* th); diff --git a/include/cantera/thermo/VPSSMgr_General.h b/include/cantera/thermo/VPSSMgr_General.h index ba5405d88..772cc97d3 100644 --- a/include/cantera/thermo/VPSSMgr_General.h +++ b/include/cantera/thermo/VPSSMgr_General.h @@ -75,7 +75,7 @@ protected: * The following methods are used in the process of constructing the phase * and setting its parameters from a specification in an input file. They * are not normally used in application programs. To see how they are - * used, see #importPhase. + * used, see importPhase(). */ //@{ virtual void initThermo(); diff --git a/include/cantera/zeroD/ReactorNet.h b/include/cantera/zeroD/ReactorNet.h index e88a9a3c2..0c214d11a 100644 --- a/include/cantera/zeroD/ReactorNet.h +++ b/include/cantera/zeroD/ReactorNet.h @@ -182,6 +182,7 @@ public: //! Used by Reactor and Wall objects to register the addition of //! sensitivity parameters so that the ReactorNet can keep track of the //! order in which sensitivity parameters are added. + //! @param name A name describing the parameter, e.g. the reaction string //! @param value The nominal value of the parameter //! @param scale A scaling factor to be applied to the sensitivity //! coefficient diff --git a/src/base/xml.cpp b/src/base/xml.cpp index 7200a8a7d..927addb6e 100644 --- a/src/base/xml.cpp +++ b/src/base/xml.cpp @@ -29,6 +29,7 @@ protected: * Note, we don't actually post the error in this class. Therefore, this * class can't be used externally. Therefore, it's a protected constructor. * + * @param file Name of the XML file being processed * @param line Number number where the error occurred. */ XML_Error(const std::string& file, int line) { @@ -60,6 +61,7 @@ public: * * @param opentag String representing the opening of the XML bracket * @param closetag String representing the closing of the XML bracket + * @param filename Name of the XML file being processed * @param line Line number where the error occurred. */ XML_TagMismatch(const std::string& opentag, const std::string& closetag, @@ -85,8 +87,9 @@ public: * An XML element doesn't have the required child node * * @param p XML_Node to write a string error message - * @param parent Namf of the parent node + * @param parent Name of the parent node * @param child Name of the required child node + * @param filename Name of the XML file being processed * @param line Line number where the error occurred. */ XML_NoChild(const XML_Node* p, const std::string& parent,