From 52e2b78a180637b169c9f9172ac47a2fe1321ec0 Mon Sep 17 00:00:00 2001 From: Harry Moffat Date: Thu, 25 Jan 2007 00:12:37 +0000 Subject: [PATCH] Doxygen update: I worked on upgrading the Cantera Error Handling section and I eliminated all of the doxygen warning messages that I encountered. --- Cantera/src/Kinetics.cpp | 6 +- Cantera/src/ThermoPhase.cpp | 10 +- Cantera/src/ctexceptions.h | 155 +++++++++++++++------ Cantera/src/global.h | 71 ++++++++-- Cantera/src/misc.cpp | 46 +++--- Cantera/src/thermo/IdealSolidSolnPhase.cpp | 10 +- Cantera/src/thermo/MolalityVPSSTP.cpp | 8 +- Cantera/src/thermo/VPStandardStateTP.cpp | 4 +- tools/doc/doxyinput/thermo.txt | 2 +- 9 files changed, 216 insertions(+), 96 deletions(-) diff --git a/Cantera/src/Kinetics.cpp b/Cantera/src/Kinetics.cpp index da5df7228..ff0941865 100644 --- a/Cantera/src/Kinetics.cpp +++ b/Cantera/src/Kinetics.cpp @@ -104,7 +104,7 @@ namespace Cantera { * the value -1 is returned. * - If no match is found in any phase, the value -2 is returned. */ - int Kinetics::kineticsSpeciesIndex(string nm, string ph) const { + int Kinetics::kineticsSpeciesIndex(std::string nm, std::string ph) const { int np = static_cast(m_thermo.size()); int k; string id; @@ -133,7 +133,7 @@ namespace Cantera { * phase where the species resides. * Will throw an error if the species string doesn't match. */ - thermo_t& Kinetics::speciesPhase(string nm) { + thermo_t& Kinetics::speciesPhase(std::string nm) { int np = static_cast(m_thermo.size()); int k; string id; @@ -220,7 +220,7 @@ namespace Cantera { * Private function of the class Kinetics, indicating that a function * inherited from the base class hasn't had a definition assigned to it */ - void Kinetics::err(string m) const { + void Kinetics::err(std::string m) const { throw CanteraError("Kinetics::" + m, "The default Base class method was called, when " "the inherited class's method should " diff --git a/Cantera/src/ThermoPhase.cpp b/Cantera/src/ThermoPhase.cpp index 2a82be749..bbbc56a79 100644 --- a/Cantera/src/ThermoPhase.cpp +++ b/Cantera/src/ThermoPhase.cpp @@ -121,7 +121,7 @@ namespace Cantera { } void ThermoPhase::setState_TPX(doublereal t, doublereal p, - const string& x) { + const std::string& x) { compositionMap xx; int kk = nSpecies(); for (int k = 0; k < kk; k++) xx[speciesName(k)] = -1.0; @@ -146,7 +146,7 @@ namespace Cantera { } void ThermoPhase::setState_TPY(doublereal t, doublereal p, - const string& y) { + const std::string& y) { compositionMap yy; int kk = nSpecies(); for (int k = 0; k < kk; k++) yy[speciesName(k)] = -1.0; @@ -246,7 +246,7 @@ namespace Cantera { throw CanteraError("setState_SV","no convergence. dt = " + fp2str(dt)); } - doublereal ThermoPhase::err(string msg) const { + doublereal ThermoPhase::err(std::string msg) const { throw CanteraError("ThermoPhase","Base class method " +msg+" called. Equation of state type: "+int2str(eosType())); return 0; @@ -301,7 +301,7 @@ namespace Cantera { * phase. If none is given, the first XML * phase element will be used. */ - void ThermoPhase::initThermoFile(string inputFile, string id) { + void ThermoPhase::initThermoFile(std::string inputFile, std::string id) { if (inputFile.size() == 0) { throw CanteraError("ThermoPhase::initThermoFile", @@ -346,7 +346,7 @@ namespace Cantera { * to see if phaseNode is pointing to the phase * with the correct id. */ - void ThermoPhase::initThermoXML(XML_Node& phaseNode, string id) { + void ThermoPhase::initThermoXML(XML_Node& phaseNode, std::string id) { /* * The default implementation just calls initThermo(); */ diff --git a/Cantera/src/ctexceptions.h b/Cantera/src/ctexceptions.h index 0afd8b7df..01343124a 100755 --- a/Cantera/src/ctexceptions.h +++ b/Cantera/src/ctexceptions.h @@ -1,7 +1,8 @@ /** * @file ctexceptions.h * - * THis contains + * This contains the definitions for the classes that are + * thrown when Cantera experiences an error condition. */ /* @@ -16,56 +17,130 @@ #define CT_CTEXCEPTIONS_H #include -//using namespace std; // See file misc.cpp for implementations of methods/functions declared // here. namespace Cantera { - /** - * @defgroup errorhandling Error Handling - * - * These classes and related functions are used to handle errors - * and unknown events within Cantera. - * - * The general idea is that exceptions are thrown using the common - * base class called CanteraError. Derived types of CanteraError - * characterize what type of error is thrown. A list of all - * of these errors is kept in the Application class. - * - * Any exceptions which are not caught cause a fatal error exit - * from the program. - */ + /*! + * @defgroup errorhandling Error Handling + * + * \brief These classes and related functions are used to handle errors and unknown events within Cantera. + * + * The general idea is that exceptions are thrown using the common + * base class called CanteraError. Derived types of CanteraError + * characterize what type of error is thrown. A list of all + * of the thrown errors is kept in the Application class. + * + * Any exceptions which are not caught cause a fatal error exit + * from the program. + * + * Below is an example of how to catch errors that throw the CanteraError class. + * In general, all Cantera C++ programs will have this basic structure. + * + * \include edemo.cpp + * + * The function showErrors() will print out the fatal error condition to standard output. + */ - /** - * Base class for exceptions thrown by Cantera classes. + //! Base class for exceptions thrown by Cantera classes. + /*! + * This class is the base class for exceptions thrown by Cantera. + * + * @ingroup errorhandling + */ + class CanteraError { + public: + //! Normal Constructor for the CanteraError base class + /*! + * This class doesn't have any storage associated with it. In its + * constructor, a call to the Application class is made to store + * the strings associated with the generated error condition. * - * @ingroup errorhandling + * @param proc String name for the function within which the error was + * generated. + * @param msg Descriptive string describing the type of error message. */ - class CanteraError { - public: - CanteraError() {} - CanteraError(std::string proc, std::string msg); - virtual ~CanteraError(){} - protected: - }; + CanteraError(std::string proc, std::string msg); - /// Array size error. - /// - class ArraySizeError : public CanteraError { - public: - ArraySizeError(std::string proc, int sz, int reqd); - }; + //! Destructor for base class does nothing + virtual ~CanteraError(){} + protected: + //! Empty base constructor is made protected so that it may be used only by + //! inherited classes. + /*! + * We want to discourage throwing an error containing no information. + */ + CanteraError() {} + }; - /// Exception thrown if an element index is out of range. - class ElementRangeError : public CanteraError { - public: - ElementRangeError(std::string func, int m, int mmax); - }; - - void deprecatedMethod(std::string classnm, std::string oldnm, std::string newnm); - void removeAtVersion(std::string func, std::string version); + //! Array size error. + /*! + * This error is thrown if a supplied length to a vector supplied + * to Cantera is too small. + * + * @ingroup errorhandling + */ + class ArraySizeError : public CanteraError { + public: + //! Constructor + /*! + * The length needed is supplied by the argument, reqd, and the + * length supplied is given by the argument sz. + * + * @param proc String name for the function within which the error was + * generated. + * @param sz This is the length supplied to Cantera. + * @param reqd This is the required length needed by Cantera + */ + ArraySizeError(std::string proc, int sz, int reqd); + }; + + //! An element index is out of range. + /*! + * + * @ingroup errorhandling + */ + class ElementRangeError : public CanteraError { + public: + //! Constructor + /*! + * This class indicates an out-of-bounds index. + * + * @param func String name for the function within which the error was + * generated. + * @param m This is the value of the out-of-bounds index. + * @param mmax This is the maximum allowed value of the index. The + * minimum allowed value is assumed to be 0. + */ + ElementRangeError(std::string func, int m, int mmax); + }; + + //! Print a warning when a deprecated method is called. + /*! + * These methods are slated to go away in future releases of Cantera. + * The developer should work towards eliminating the use of these + * methods in the near future. + * + * @param classnm Class the method belongs to + * @param oldnm Name of the deprecated method + * @param newnm Name of the method users should use instead + * + * @ingroup errorhandling + */ + void deprecatedMethod(std::string classnm, std::string oldnm, std::string newnm); + + //! Throw an error condition for a procedure that has been removed. + /*! + * + * @param func String name for the function within which the error was + * generated. + * @param version Version of Cantera that first removed this function. + * + * @ingroup errorhandling + */ + void removeAtVersion(std::string func, std::string version); } #endif diff --git a/Cantera/src/global.h b/Cantera/src/global.h index 37007b8a1..bf6789ffb 100755 --- a/Cantera/src/global.h +++ b/Cantera/src/global.h @@ -25,24 +25,69 @@ namespace Cantera { class XML_Node; class Logger; - // Return the number of errors that have been encountered so far - int nErrors(); + //! Return the number of errors that have been encountered so far + /*! + * @ingroup errorhandling + */ + int nErrors(); - // The last error message - std::string lastErrorMessage(); + //! Returns the last error message + /*! + * @return String containing the description of the last error + * message. + * + * @ingroup errorhandling + */ + std::string lastErrorMessage(); - // Set an error condition in the application class without - // throwing an exception. - void setError(std::string r, std::string msg); + //! Set an error condition in the application class without throwing an exception. + /*! + * This routine adds an error message to the end of the stack + * of errors that Cantera accumulates in the Application + * class. + * @param r Procedure name which is generating the error condition + * @param msg Descriptive message of the error condition. + * + * \ingroup errorhandling + */ + void setError(std::string r, std::string msg); - // Prints all of the error messages to stream f - void showErrors(std::ostream& f); + //! Prints all of the error messages to an ostream + /*! + * Print all of the error messages using function writelog. + * Write out all of the saved error messages to the ostream f + * Cantera saves a stack of exceptions that it + * has caught in the Application class. This routine writes + * out all of the error messages to the ostream + * and then clears them from internal storage. + * + * @param f ostream which will receive the error messages + * + * \ingroup errorhandling + */ + void showErrors(std::ostream& f); - // Print all of the error messages using function writelog. - void showErrors(); + //! Print all of the error messages using function writelog. + /*! + * Print all of the error messages using function writelog. + * Write out all of the saved error messages to the log device. + * Cantera saves a stack of exceptions that it + * has caught in the Application class. This routine writes + * out all of the error messages to the log, usually stdout, + * and then clears them from internal storage. + * \ingroup errorhandling + */ + void showErrors(); - // Discard the last error message - void popError(); + //! Discard the last error message + /*! + * Cantera saves a stack of exceptions that it + * has caught in the Application class. This routine eliminates + * the last exception to be added to that stack. + * + * \ingroup errorhandling + */ + void popError(); /// Find an input file. std::string findInputFile(std::string name); diff --git a/Cantera/src/misc.cpp b/Cantera/src/misc.cpp index a65f5652d..d5c14b978 100755 --- a/Cantera/src/misc.cpp +++ b/Cantera/src/misc.cpp @@ -2,7 +2,7 @@ /** * @file misc.cpp * - * + * $Id$ */ #ifdef WIN32 @@ -276,7 +276,7 @@ namespace Cantera { string sleep() { appinit(); return app()->sleep; } - /** + /* * Return the number of errors that have been encountered so far. * \ingroup errorhandling */ @@ -284,7 +284,7 @@ namespace Cantera { return static_cast(app()->errorMessage.size()); } - /** + /* * popError eliminates the last error message that Cantera * has saved. Cantera saves a stack of exceptions that it * has caught in the Application class. This routine eliminates @@ -299,7 +299,7 @@ namespace Cantera { } } - /** + /* * Retrieve the last error message. * This routine will retrieve the last error message and return * it in the return string. @@ -320,7 +320,7 @@ namespace Cantera { } } - /** + /* * Prints all of the error messages to stream f. * Write out to ostream, f, all of the saved error messages. * Cantera saves a stack of exceptions that it @@ -329,7 +329,7 @@ namespace Cantera { * clears them from internal storage. * \ingroup errorhandling */ - void showErrors(ostream& f) { + void showErrors(std::ostream& f) { appinit(); int i = static_cast(s_app->errorMessage.size()); if (i == 0) return; @@ -349,7 +349,7 @@ namespace Cantera { s_app->errorRoutine.clear(); } - /** + /* * Print all of the error messages using function writelog. * Write out all of the saved error messages to the log device. * Cantera saves a stack of exceptions that it @@ -377,7 +377,7 @@ namespace Cantera { s_app->errorRoutine.clear(); } - /** + /* * Set an error condition in the application class without * throwing an exception. * This routine adds an error message to the end of the stack @@ -385,7 +385,7 @@ namespace Cantera { * class. * \ingroup errorhandling */ - void setError(string r, string msg) { + void setError(std::string r, std::string msg) { appinit(); s_app->errorMessage.push_back(msg); s_app->errorRoutine.push_back(r); @@ -593,15 +593,15 @@ namespace Cantera { // exceptions - CanteraError::CanteraError(string proc, string msg) { + CanteraError::CanteraError(std::string proc, std::string msg) { setError(proc, msg); } - ArraySizeError::ArraySizeError(string proc, int sz, int reqd) : + ArraySizeError::ArraySizeError(std::string proc, int sz, int reqd) : CanteraError(proc, "Array size ("+int2str(sz)+ ") too small. Must be at least "+int2str(reqd)) {} - ElementRangeError::ElementRangeError(string func, int m, int mmax) : + ElementRangeError::ElementRangeError(std::string func, int m, int mmax) : CanteraError(func, "Element index " + int2str(m) + " outside valid range of 0 to " + int2str(mmax-1)) {} @@ -613,11 +613,11 @@ namespace Cantera { // ////////////////////////////////////////////////////////// - /// Print a warning when a deprecated method is called. - /// @param classnm Class the method belongs to - /// @param oldnm Name of the deprecated method - /// @param newnm Name of the method users should use instead - void deprecatedMethod(string classnm, string oldnm, string newnm) { + // Print a warning when a deprecated method is called. + // @param classnm Class the method belongs to + // @param oldnm Name of the deprecated method + // @param newnm Name of the method users should use instead + void deprecatedMethod(std::string classnm, std::string oldnm, std::string newnm) { writelog(">>>> WARNING: method "+oldnm+" of class "+classnm +" is deprecated.\n"); writelog(" Use method "+newnm+" instead.\n"); @@ -626,12 +626,12 @@ namespace Cantera { } - void removeAtVersion(string func, string version) { - if (version >= "CANTERA_VERSION") { - writelog("Removed procedure: "+func+"\n"); - writelog("Removed in version: "+version+"\n"); - throw CanteraError("removeAtVersion","procedure has been removed."); - } + void removeAtVersion(std::string func, std::string version) { + //if (version >= "CANTERA_VERSION") { + writelog("Removed procedure: "+func+"\n"); + writelog("Removed in version: "+version+"\n"); + throw CanteraError("removeAtVersion: "+ func,"procedure has been removed."); + // } } diff --git a/Cantera/src/thermo/IdealSolidSolnPhase.cpp b/Cantera/src/thermo/IdealSolidSolnPhase.cpp index 48a78baad..ffc340c16 100644 --- a/Cantera/src/thermo/IdealSolidSolnPhase.cpp +++ b/Cantera/src/thermo/IdealSolidSolnPhase.cpp @@ -40,7 +40,7 @@ namespace Cantera { } } - IdealSolidSolnPhase::IdealSolidSolnPhase(string inputFile, string id, + IdealSolidSolnPhase::IdealSolidSolnPhase(std::string inputFile, std::string id, int formGC) : ThermoPhase(), m_formGC(formGC), @@ -58,7 +58,7 @@ namespace Cantera { constructPhaseFile(inputFile, id); } - IdealSolidSolnPhase::IdealSolidSolnPhase(XML_Node& root, string id, + IdealSolidSolnPhase::IdealSolidSolnPhase(XML_Node& root, std::string id, int formGC) : ThermoPhase(), m_formGC(formGC), @@ -1062,7 +1062,7 @@ namespace Cantera { * with the correct id. */ void IdealSolidSolnPhase:: - constructPhaseXML(XML_Node& phaseNode, string id) { + constructPhaseXML(XML_Node& phaseNode, std::string id) { string subname = "IdealSolidSolnPhase::constructPhaseXML"; if (id.size() > 0) { string idp = phaseNode.id(); @@ -1136,7 +1136,7 @@ namespace Cantera { * phase element will be used. */ void IdealSolidSolnPhase:: - constructPhaseFile(string inputFile, string id) { + constructPhaseFile(std::string inputFile, std::string id) { if (inputFile.size() == 0) { throw CanteraError("IdealSolidSolnPhase::constructPhaseFile", "input file is null"); @@ -1192,7 +1192,7 @@ namespace Cantera { * to see if phaseNode is pointing to the phase * with the correct id. */ - void IdealSolidSolnPhase::initThermoXML(XML_Node& phaseNode, string id) { + void IdealSolidSolnPhase::initThermoXML(XML_Node& phaseNode, std::string id) { /* * Initialize all of the lengths now that we know how many species * there are in the phase. diff --git a/Cantera/src/thermo/MolalityVPSSTP.cpp b/Cantera/src/thermo/MolalityVPSSTP.cpp index 9833e4cdc..b2eaa076b 100644 --- a/Cantera/src/thermo/MolalityVPSSTP.cpp +++ b/Cantera/src/thermo/MolalityVPSSTP.cpp @@ -340,7 +340,7 @@ namespace Cantera { * * Set the molalities of the solutes by name */ - void MolalityVPSSTP::setMolalitiesByName(const string& x) { + void MolalityVPSSTP::setMolalitiesByName(const std::string& x) { compositionMap xx; int kk = nSpecies(); for (int k = 0; k < kk; k++) { @@ -449,7 +449,7 @@ namespace Cantera { */ - doublereal MolalityVPSSTP::err(string msg) const { + doublereal MolalityVPSSTP::err(std::string msg) const { throw CanteraError("MolalityVPSSTP","Base class method " +msg+" called. Equation of state type: "+int2str(eosType())); return 0; @@ -523,7 +523,7 @@ namespace Cantera { } /** Set the temperature (K), pressure (Pa), and molality. */ - void MolalityVPSSTP::setState_TPM(doublereal t, doublereal p, const string& m) { + void MolalityVPSSTP::setState_TPM(doublereal t, doublereal p, const std::string& m) { setMolalitiesByName(m); setTemperature(t); setPressure(p); @@ -573,7 +573,7 @@ namespace Cantera { * to see if phaseNode is pointing to the phase * with the correct id. */ - void MolalityVPSSTP::initThermoXML(XML_Node& phaseNode, string id) { + void MolalityVPSSTP::initThermoXML(XML_Node& phaseNode, std::string id) { initLengths(); /* diff --git a/Cantera/src/thermo/VPStandardStateTP.cpp b/Cantera/src/thermo/VPStandardStateTP.cpp index 33f198de9..c3a4e193f 100644 --- a/Cantera/src/thermo/VPStandardStateTP.cpp +++ b/Cantera/src/thermo/VPStandardStateTP.cpp @@ -111,7 +111,7 @@ namespace Cantera { */ - doublereal VPStandardStateTP::err(string msg) const { + doublereal VPStandardStateTP::err(std::string msg) const { throw CanteraError("VPStandardStateTP","Base class method " +msg+" called. Equation of state type: "+int2str(eosType())); return 0; @@ -305,7 +305,7 @@ namespace Cantera { * This routine initializes the lengths in the current object and * then calls the parent routine. */ - void VPStandardStateTP::initThermoXML(XML_Node& phaseNode, string id) { + void VPStandardStateTP::initThermoXML(XML_Node& phaseNode, std::string id) { VPStandardStateTP::initLengths(); ThermoPhase::initThermoXML(phaseNode, id); } diff --git a/tools/doc/doxyinput/thermo.txt b/tools/doc/doxyinput/thermo.txt index aa7d69617..06a26e83a 100644 --- a/tools/doc/doxyinput/thermo.txt +++ b/tools/doc/doxyinput/thermo.txt @@ -10,7 +10,7 @@ represents each phase. A simple complete program that creates an object representing a gas mixture and prints its temperature is shown below. \include ex1.cpp -Class ThermoPhase is the base class for Cantera classes that represent +Class Cantera::ThermoPhase is the base class for Cantera classes that represent phases of matter. It defines the public interface for all classes that represent phases. For example, it specifies that they all have a method \c temperature() that returns the current temperature, a method