From f8b12adef47a840ae0997fad9545fc32894d0aa4 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 9 Nov 2015 19:35:52 -0500 Subject: [PATCH] Clean up comments in 'base' source and header files --- include/cantera/base/Array.h | 172 +++++------- include/cantera/base/FactoryBase.h | 10 +- include/cantera/base/clockWC.h | 65 +++-- include/cantera/base/ct_defs.h | 10 +- include/cantera/base/ctexceptions.h | 85 +++--- include/cantera/base/ctml.h | 405 +++++++++++++--------------- include/cantera/base/global.h | 78 +++--- include/cantera/base/logger.h | 48 ++-- include/cantera/base/plots.h | 4 +- include/cantera/base/stringUtils.h | 138 +++++----- include/cantera/base/utilities.h | 220 ++++++++------- include/cantera/base/xml.h | 314 +++++++++++---------- src/base/application.cpp | 14 +- src/base/application.h | 93 +++---- src/base/ct2ctml.cpp | 30 +-- src/base/ctml.cpp | 36 +-- src/base/global.cpp | 6 +- src/base/units.h | 9 +- src/base/xml.cpp | 53 ++-- 19 files changed, 832 insertions(+), 958 deletions(-) diff --git a/include/cantera/base/Array.h b/include/cantera/base/Array.h index a22e2b18e..2b4bc2ebb 100644 --- a/include/cantera/base/Array.h +++ b/include/cantera/base/Array.h @@ -14,13 +14,14 @@ namespace Cantera { -//! A class for 2D arrays stored in column-major -//! (Fortran-compatible) form. +//! A class for 2D arrays stored in column-major (Fortran-compatible) form. /*! - * In this form, the data entry for an n row, m col - * matrix is + * In this form, the data entry for an n row, m col matrix is + * * index = i + (n-1) * j - * where + * + * where + * * J(i,j) = data_start + index * i = row * j = column @@ -28,17 +29,17 @@ namespace Cantera class Array2D { public: - //! Type definition for the iterator class that is - //! can be used by Array2D types. + //! Type definition for the iterator class that is can be used by Array2D + //! types. /*! - * this is just equal to vector_fp iterator. + * This is just equal to vector_fp::iterator. */ typedef vector_fp::iterator iterator; - //! Type definition for the const_iterator class that is - //! can be used by Array2D types. + //! Type definition for the const_iterator class that is can be used by + //! Array2D types. /*! - * this is just equal to vector_fp const_iterator. + * This is just equal to vector_fp::const_iterator. */ typedef vector_fp::const_iterator const_iterator; @@ -51,14 +52,13 @@ public: m_ncols(0) { } - //! Constructor. + //! Constructor. /*! - * Create an \c m by \c n array, and initialize - * all elements to \c v. + * Create an \c m by \c n array, and initialize all elements to \c v. * - * @param m Number of rows - * @param n Number of columns - * @param v Default fill value. The default is 0.0 + * @param m Number of rows + * @param n Number of columns + * @param v Default fill value. The default is 0.0 */ Array2D(const size_t m, const size_t n, const doublereal v = 0.0) : m_data(0), m_nrows(m), m_ncols(n) { @@ -66,15 +66,15 @@ public: std::fill(m_data.begin(), m_data.end(), v); } - //! Constructor. + //! Constructor. /*! - * Create an \c m by \c n array, initialized with the contents - * of the array \c values. + * Create an \c m by \c n array, initialized with the contents of the array + * \c values. * - * @param m Number of rows - * @param n Number of columns - * @param values Initial values of the array. Must be of length m*n, - * and stored in column-major order. + * @param m Number of rows + * @param n Number of columns + * @param values Initial values of the array. Must be of length m*n, and + * stored in column-major order. */ Array2D(const size_t m, const size_t n, const doublereal* values) : m_data(0), m_nrows(m), m_ncols(n) { @@ -82,10 +82,6 @@ public: std::copy(values, values + m_nrows*m_ncols, m_data.begin()); } - //! Copy constructor - /*! - * @param y Array2D to make the copy from - */ Array2D(const Array2D& y) : m_data(0), m_nrows(0), @@ -96,10 +92,8 @@ public: m_data = y.m_data; } - //! assignment operator - /*! - * @param y Array2D to get the values from - */ + virtual ~Array2D() {} + Array2D& operator=(const Array2D& y) { if (&y == this) { return *this; @@ -125,11 +119,10 @@ public: //! Append a column to the existing matrix using a std vector /*! - * This operation will add a column onto the existing matrix. + * This operation will add a column onto the existing matrix. * - * @param c This vector is the entries in the - * column to be added. It must have a length - * equal to m_nrows or greater. + * @param c This vector is the entries in the column to be added. It must + * have a length equal to m_nrows or greater. */ void appendColumn(const vector_fp& c) { m_ncols++; @@ -142,11 +135,10 @@ public: //! Append a column to the existing matrix /*! - * This operation will add a column onto the existing matrix. + * This operation will add a column onto the existing matrix. * - * @param c This vector of doubles is the entries in the - * column to be added. It must have a length - * equal to m_nrows or greater. + * @param c This vector of doubles is the entries in the column to be + * added. It must have a length equal to m_nrows or greater. */ void appendColumn(const doublereal* const c) { m_ncols++; @@ -159,8 +151,8 @@ public: //! Set the nth row to array rw /*! - * @param n Index of the row to be changed - * @param rw Vector for the row. Must have a length of m_ncols. + * @param n Index of the row to be changed + * @param rw Vector for the row. Must have a length of m_ncols. */ void setRow(size_t n, const doublereal* const rw) { for (size_t j = 0; j < m_ncols; j++) { @@ -170,9 +162,9 @@ public: //! Get the nth row and return it in a vector /*! - * @param n Index of the row to be returned. - * @param rw Return Vector for the operation. - * Must have a length of m_ncols. + * @param n Index of the row to be returned. + * @param rw Return Vector for the operation. Must have a length of + * m_ncols. */ void getRow(size_t n, doublereal* const rw) { for (size_t j = 0; j < m_ncols; j++) { @@ -182,11 +174,10 @@ public: //! Set the values in column m to those in array col /*! - * A(i,m) = col(i) + * A(i,m) = col(i) * - * @param m Column to set - * @param col pointer to a col vector. Vector - * must have a length of m_nrows. + * @param m Column to set + * @param col pointer to a col vector. Vector must have a length of m_nrows. */ void setColumn(size_t m, doublereal* const col) { for (size_t i = 0; i < m_nrows; i++) { @@ -198,8 +189,8 @@ public: /*! * col(i) = A(i,m) * - * @param m Column to set - * @param col pointer to a col vector that will be returned + * @param m Column to set + * @param col pointer to a col vector that will be returned */ void getColumn(size_t m, doublereal* const col) { for (size_t i = 0; i < m_nrows; i++) { @@ -207,23 +198,15 @@ public: } } - /** - * Destructor. Does nothing, since no memory allocated on the - * heap. - */ - virtual ~Array2D() {} - //! Evaluate z = a*x + y. /*! - * This function evaluates the AXPY operation, and stores - * the result in the object's Array2D object. - * It's assumed that all 3 objects have the same dimensions, - * but no error checking is done. - * - * @param a scalar to multiply x with - * @param x First Array2D object to be used - * @param y Second Array2D object to be used + * This function evaluates the AXPY operation, and stores the result in the + * object's Array2D object. It's assumed that all 3 objects have the same + * dimensions, but no error checking is done. * + * @param a scalar to multiply x with + * @param x First Array2D object to be used + * @param y Second Array2D object to be used */ void axpy(doublereal a, const Array2D& x, const Array2D& y) { auto b = begin(); @@ -243,8 +226,7 @@ public: /*! * @param i row index * @param j column index. - * - * @return Returns a reference to A(i,j) which may be assigned. + * @returns a reference to A(i,j) which may be assigned. */ doublereal& operator()(size_t i, size_t j) { return value(i,j); @@ -252,10 +234,9 @@ public: //! Allows retrieving elements using the syntax x = A(i,j). /*! - * @param i Index for the row to be retrieved - * @param j Index for the column to be retrieved. - * - * @return Returns the value of the matrix entry + * @param i Index for the row to be retrieved + * @param j Index for the column to be retrieved. + * @returns the value of the matrix entry */ doublereal operator()(size_t i, size_t j) const { return value(i,j); @@ -263,13 +244,12 @@ public: //! Returns a changeable reference to position in the matrix /*! - * This is a key entry. Returns a reference to the matrix's (i,j) - * element. This may be used as an L value. + * Returns a reference to the matrix's (i,j) element. This may be used as an + * L value. * * @param i The row index * @param j The column index - * - * @return Returns a changeable reference to the matrix entry + * @returns a changeable reference to the matrix entry */ doublereal& value(size_t i, size_t j) { return m_data[m_nrows*j + i]; @@ -277,8 +257,7 @@ public: //! Returns the value of a single matrix entry /*! - * This is a key entry. Returns the value of the matrix position (i,j) - * element. + * Returns the value of the matrix position (i,j) element. * * @param i The row index * @param j The column index @@ -330,9 +309,8 @@ public: //! Return a pointer to the top of column j, columns are contiguous //! in memory /*! - * @param j Value of the column - * - * @return Returns a pointer to the top of the column + * @param j Value of the column + * @returns a pointer to the top of the column */ doublereal* ptrColumn(size_t j) { return &m_data[m_nrows*j]; @@ -341,9 +319,8 @@ public: //! Return a const pointer to the top of column j, columns are contiguous //! in memory /*! - * @param j Value of the column - * - * @return Returns a const pointer to the top of the column + * @param j Value of the column + * @returns a const pointer to the top of the column */ const doublereal* ptrColumn(size_t j) const { return &m_data[m_nrows*j]; @@ -362,13 +339,12 @@ protected: //! Output the current contents of the Array2D object /*! - * Example of usage: + * Example of usage: * s << m << endl; * - * @param s Reference to the ostream to write to - * @param m Object of type Array2D that you are querying - * - * @return Returns a reference to the ostream. + * @param s Reference to the ostream to write to + * @param m Object of type Array2D that you are querying + * @returns a reference to the ostream. */ inline std::ostream& operator<<(std::ostream& s, const Array2D& m) { @@ -384,27 +360,25 @@ inline std::ostream& operator<<(std::ostream& s, const Array2D& m) return s; } -//! Overload the times equals operator for multiplication -//! of a matrix and a scalar. +//! Overload the times equals operator for multiplication of a matrix and a +//! scalar. /*! - * Scaled every element of the matrix by the scalar input + * Scaled every element of the matrix by the scalar input * - * @param m Matrix - * @param a scalar + * @param m Matrix + * @param a scalar */ inline void operator*=(Array2D& m, doublereal a) { scale(m.begin(), m.end(), m.begin(), a); } -//! Overload the plus equals operator for addition -//! of one matrix with another +//! Overload the plus equals operator for addition of one matrix with another /*! - * Adds each element of the second matrix into the first - * matrix + * Adds each element of the second matrix into the first matrix * - * @param x First matrix - * @param y Second matrix, which is a const + * @param x First matrix + * @param y Second matrix, which is a const */ inline void operator+=(Array2D& x, const Array2D& y) { diff --git a/include/cantera/base/FactoryBase.h b/include/cantera/base/FactoryBase.h index d133b9d3b..a6ea596e6 100644 --- a/include/cantera/base/FactoryBase.h +++ b/include/cantera/base/FactoryBase.h @@ -12,9 +12,9 @@ namespace Cantera { //! Base class for factories. -/*! This class maintains a registry of - * all factories that derive from it, and deletes them all when - * its static method deleteFactories is invoked. +/*! + * This class maintains a registry of all factories that derive from it, and + * deletes them all when its static method deleteFactories is invoked. */ class FactoryBase { @@ -24,8 +24,8 @@ public: virtual ~FactoryBase() { } - //! static function that deletes all factories - //! in the internal registry maintained in a static variable + //! static function that deletes all factories in the internal registry + //! maintained in a static variable static void deleteFactories() { for (const auto& f : s_vFactoryRegistry) { f->deleteFactory(); diff --git a/include/cantera/base/clockWC.h b/include/cantera/base/clockWC.h index b1d88ebb8..eeb7e806a 100644 --- a/include/cantera/base/clockWC.h +++ b/include/cantera/base/clockWC.h @@ -19,30 +19,27 @@ namespace Cantera //! The class provides the wall clock timer in seconds /*! - * This routine relies on the ANSI C routine, clock(), for - * its basic operation. Therefore, it should be fairly - * portable. + * This routine relies on the ANSI C routine, clock(), for its basic operation. + * Therefore, it should be fairly portable. * - * The clock will rollover if the calculation is long enough. - * The wraparound time is roughly 72 minutes for a 32 bit system. - * This object senses that by seeing if the raw tick counter is - * has decreased from the last time. If it senses a wraparound has - * occurred, it increments an internal counter to account for this. - * Therefore, for long calculations, this object must be called - * at regular intervals for the seconds timer to be accurate. + * The clock will rollover if the calculation is long enough. The wraparound + * time is roughly 72 minutes for a 32 bit system. This object senses that by + * seeing if the raw tick counter is has decreased from the last time. If it + * senses a wraparound has occurred, it increments an internal counter to + * account for this. Therefore, for long calculations, this object must be + * called at regular intervals for the seconds timer to be accurate. * - * An example of how to use the timer is given below. timeToDoCalcs - * contains the wall clock time calculated for the operation. + * An example of how to use the timer is given below. timeToDoCalcs contains the + * wall clock time calculated for the operation. * - * @code - * clockWC wc; - * do_hefty_calculations_atLeastgreaterThanAMillisecond(); - * double timeToDoCalcs = wc.secondsWC(); - * @endcode + * @code + * clockWC wc; + * do_hefty_calculations_atLeastgreaterThanAMillisecond(); + * double timeToDoCalcs = wc.secondsWC(); + * @endcode * - * In general, the process to be timed must take more than a millisecond - * for this clock to enough of a significant resolution to be - * accurate. + * In general, the process to be timed must take more than a millisecond for + * this clock to enough of a significant resolution to be accurate. * * @ingroup globalUtilFuncs * @@ -56,18 +53,17 @@ public: */ clockWC(); - //! Resets the internal counters and returns the wall clock time - //! in seconds + //! Resets the internal counters and returns the wall clock time in seconds double start(); //! Returns the wall clock time in seconds since the last reset. /*! - * Returns system cpu and wall clock time in seconds. This is a strictly - * Ansi C timer, since clock() is defined as an Ansi C function. On some - * machines clock() returns type unsigned long (HP) and on others (SUN) - * it returns type long. An attempt to recover the actual time for clocks - * which have rolled over is made also. However, it only works if this - * function is called fairly regularily during the solution procedure. + * Returns system cpu and wall clock time in seconds. This is a strictly + * Ansi C timer, since clock() is defined as an Ansi C function. On some + * machines clock() returns type unsigned long (HP) and on others (SUN) + * it returns type long. An attempt to recover the actual time for clocks + * which have rolled over is made also. However, it only works if this + * function is called fairly regularily during the solution procedure. */ double secondsWC(); @@ -77,21 +73,20 @@ private: //! Number of clock rollovers since the last initialization /*! - * The clock will rollover if the calculation is long enough. - * This object senses that by seeing if the raw tick counter is - * has decreased from the last time. + * The clock will rollover if the calculation is long enough. This object + * senses that by seeing if the raw tick counter is has decreased from the + * last time. */ unsigned int clock_rollovers; - //! Counter containing the value of the number of ticks from - //! the first call (or the reset call). + //! Counter containing the value of the number of ticks from the first call + //! (or the reset call). clock_t start_ticks; //! internal constant containing clock ticks per second const double inv_clocks_per_sec; - //! internal constant containing the total number of ticks - //! per rollover. + //! internal constant containing the total number of ticks per rollover. const double clock_width; }; } diff --git a/include/cantera/base/ct_defs.h b/include/cantera/base/ct_defs.h index af0baa1c8..6eb08d0f3 100644 --- a/include/cantera/base/ct_defs.h +++ b/include/cantera/base/ct_defs.h @@ -134,16 +134,16 @@ const doublereal Undef = -999.1234; //! Small number to compare differences of mole fractions against. /*! - * This number is used for the interconversion of mole fraction and mass fraction quantities - * when the molecular weight of a species is zero. It's also used for the matrix inversion - * of transport properties when mole fractions must be positive. + * This number is used for the interconversion of mole fraction and mass + * fraction quantities when the molecular weight of a species is zero. It's also + * used for the matrix inversion of transport properties when mole fractions + * must be positive. */ const doublereal Tiny = 1.e-20; //! Map connecting a string name with a double. /*! - * This is used mostly to assign concentrations and mole fractions - * to species. + * This is used mostly to assign concentrations and mole fractions to species. */ typedef std::map compositionMap; diff --git a/include/cantera/base/ctexceptions.h b/include/cantera/base/ctexceptions.h index 3f21b51b1..c36a5ea83 100644 --- a/include/cantera/base/ctexceptions.h +++ b/include/cantera/base/ctexceptions.h @@ -22,47 +22,45 @@ namespace Cantera * \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. + * 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. + * 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. + * 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 demo1a.cpp + * \include demo1a.cpp * - * The function showErrors() will print out the fatal error - * condition to standard output. + * The function showErrors() will print out the fatal error condition to + * standard output. * - * A group of defines may be used during debugging to assert - * conditions which should be true. These are named AssertTrace(), - * AssertThrow(), and AssertThrowMsg(). Examples of their usage is - * given below. + * A group of defines may be used during debugging to assert conditions which + * should be true. These are named AssertTrace(), AssertThrow(), and + * AssertThrowMsg(). Examples of their usage is given below. * * @code - * AssertTrace(p == OneAtm); - * AssertThrow(p == OneAtm, "Kinetics::update"); - * AssertThrowMsg(p == OneAtm, "Kinetics::update", - * "Algorithm limited to atmospheric pressure"); + * AssertTrace(p == OneAtm); + * AssertThrow(p == OneAtm, "Kinetics::update"); + * AssertThrowMsg(p == OneAtm, "Kinetics::update", + * "Algorithm limited to atmospheric pressure"); * @endcode * - * Their first argument is a boolean. If the boolean is not true, a - * CanteraError is thrown, with descriptive information indicating - * where the error occurred. The Assert* checks are skipped if the NDEBUG - * preprocessor symbol is defined, e.g. with the compiler option -DNDEBUG. + * Their first argument is a boolean. If the boolean is not true, a CanteraError + * is thrown, with descriptive information indicating where the error occurred. + * The Assert* checks are skipped if the NDEBUG preprocessor symbol is defined, + * e.g. with the compiler option -DNDEBUG. */ //! Base class for exceptions thrown by Cantera classes. /*! - * This class is the base class for exceptions thrown by Cantera. - * It inherits from std::exception so that normal error handling - * operations from applications may automatically handle the - * errors in their own way. + * This class is the base class for exceptions thrown by Cantera. It inherits + * from std::exception so that normal error handling operations from + * applications may automatically handle the errors in their own way. * * @ingroup errorhandling */ @@ -112,7 +110,8 @@ public: } protected: - //! Protected default constructor discourages throwing errors containing no information. + //! Protected default constructor discourages throwing errors containing no + //! information. CanteraError() : saved_(false) {}; //! Constructor used by derived classes that override getMessage() @@ -130,10 +129,10 @@ private: //! Array size error. /*! - * This error is thrown if a supplied length to a vector supplied - * to Cantera is too small. + * This error is thrown if a supplied length to a vector supplied to Cantera is + * too small. * - * @ingroup errorhandling + * @ingroup errorhandling */ class ArraySizeError : public CanteraError { @@ -213,7 +212,7 @@ public: //! Provides a std::string variable containing the file and line number /*! - * This is a std:string containing the file name and the line number + * This is a std:string containing the file name and the line number */ #define STR_TRACE (std::string(__FILE__) + ":" + XSTR_TRACE_LINE(__LINE__)) @@ -231,9 +230,9 @@ public: //! Assertion must be true or an error is thrown /*! - * Assertion must be true or else a CanteraError is thrown. A diagnostic string containing the - * file and line number, indicating where the error - * occurred is added to the thrown object. + * Assertion must be true or else a CanteraError is thrown. A diagnostic string + * containing the file and line number, indicating where the error occurred is + * added to the thrown object. * * @param expr Boolean expression that must be true * @@ -243,24 +242,24 @@ public: # define AssertTrace(expr) ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, std::string("failed assert: ") + #expr)) #endif -//! Assertion must be true or an error is thrown +//! Assertion must be true or an error is thrown /*! - * Assertion must be true or else a CanteraError is thrown. A diagnostic string indicating where the error - * occurred is added to the thrown object. + * Assertion must be true or else a CanteraError is thrown. A diagnostic string + * indicating where the error occurred is added to the thrown object. * * @param expr Boolean expression that must be true - * @param procedure Character string or std:string expression indicating the procedure where the assertion failed + * @param procedure Character string or std:string expression indicating the + * procedure where the assertion failed * @ingroup errorhandling */ #ifndef AssertThrow # define AssertThrow(expr, procedure) ((expr) ? (void) 0 : throw CanteraError(procedure, std::string("failed assert: ") + #expr)) #endif -//! Assertion must be true or an error is thrown +//! Assertion must be true or an error is thrown /*! - * Assertion must be true or else a CanteraError is thrown. A - * diagnostic string indicating where the error occurred is added - * to the thrown object. + * Assertion must be true or else a CanteraError is thrown. A diagnostic string + * indicating where the error occurred is added to the thrown object. * * @param expr Boolean expression that must be true * @param procedure Character string or std:string expression indicating diff --git a/include/cantera/base/ctml.h b/include/cantera/base/ctml.h index 58d05c718..07513d2b1 100644 --- a/include/cantera/base/ctml.h +++ b/include/cantera/base/ctml.h @@ -22,23 +22,22 @@ class Array2D; */ const std::string CTML_Version = "1.4.1"; -//! This function adds a child node with the name, "integer", with a value -//! consisting of a single integer +//! This function adds a child node with the name, "integer", with a value +//! consisting of a single integer /*! - * This function will add a child node to the current XML node, with the - * name "integer". It will have a title attribute, and the body - * of the XML node will be filled out with a single integer + * This function will add a child node to the current XML node, with the name + * "integer". It will have a title attribute, and the body of the XML node will + * be filled out with a single integer * - * Example: + * Example: * - * Code snippet: * @code - * const XML_Node &node; - * std::string titleString = "maxIterations"; - * int value = 1000; - * std::string typeString = "optional"; - * std::string units = ""; - * addInteger(node, titleString, value, typeString, units); + * const XML_Node &node; + * std::string titleString = "maxIterations"; + * int value = 1000; + * std::string typeString = "optional"; + * std::string units = ""; + * addInteger(node, titleString, value, typeString, units); * @endcode * * Creates the following the snippet in the XML file: @@ -49,42 +48,41 @@ const std::string CTML_Version = "1.4.1"; * <\integer> * <\parentNode> * - * @param node reference to the XML_Node object of the parent XML element - * @param titleString String name of the title attribute - * @param value Value - single integer - * @param unitsString String name of the Units attribute. The default is to - * have an empty string. - * @param typeString String type. This is an optional parameter. The default - * is to have an empty string. + * @param node reference to the XML_Node object of the parent XML element + * @param titleString String name of the title attribute + * @param value Value - single integer + * @param unitsString String name of the Units attribute. The default is to + * have an empty string. + * @param typeString String type. This is an optional parameter. The default + * is to have an empty string. * - * @todo I don't think this is used. Figure out what is used for writing integers, - * and codify that. unitsString shouldn't be here, since it's an int. - * typeString should be codified as to its usage. + * @todo I don't think this is used. Figure out what is used for writing + * integers, and codify that. unitsString shouldn't be here, since it's an + * int. typeString should be codified as to its usage. */ void addInteger(XML_Node& node, const std::string& titleString, const int value, const std::string& unitsString="", const std::string& typeString=""); -//! This function adds a child node with the name, "float", with a value -//! consisting of a single floating point number +//! This function adds a child node with the name, "float", with a value +//! consisting of a single floating point number /*! - * This function will add a child node to the current XML node, with the - * name "float". It will have a title attribute, and the body - * of the XML node will be filled out with a single float + * This function will add a child node to the current XML node, with the name + * "float". It will have a title attribute, and the body of the XML node will be + * filled out with a single float * * Example: * - * Code snippet: - * @code - * const XML_Node &node; - * std::string titleString = "activationEnergy"; - * doublereal value = 50.3; - * doublereal maxval = 1.0E3; - * doublereal minval = 0.0; - * std::string typeString = "optional"; - * std::string unitsString = "kcal/gmol"; - * addFloat(node, titleString, value, unitsString, typeString, minval, maxval); - * @endcode + * @code + * const XML_Node &node; + * std::string titleString = "activationEnergy"; + * doublereal value = 50.3; + * doublereal maxval = 1.0E3; + * doublereal minval = 0.0; + * std::string typeString = "optional"; + * std::string unitsString = "kcal/gmol"; + * addFloat(node, titleString, value, unitsString, typeString, minval, maxval); + * @endcode * * Creates the following the snippet in the XML file: * @@ -94,44 +92,41 @@ void addInteger(XML_Node& node, const std::string& titleString, * <\float> * <\parentNode> * - * @param node reference to the XML_Node object of the parent XML element - * @param titleString String name of the title attribute - * @param value Value - single integer - * @param unitsString String name of the Units attribute. The default is to - * have an empty string. - * @param typeString String type. This is an optional parameter. The default - * is to have an empty string. - * @param minval Minimum allowed value of the float. The default is the - * special double, Undef, which means to ignore the - * entry. - * @param maxval Maximum allowed value of the float. The default is the - * special double, Undef, which means to ignore the - * entry. + * @param node reference to the XML_Node object of the parent XML element + * @param titleString String name of the title attribute + * @param value Value - single integer + * @param unitsString String name of the Units attribute. The default is to + * have an empty string. + * @param typeString String type. This is an optional parameter. The default + * is to have an empty string. + * @param minval Minimum allowed value of the float. The default is the + * special double, Undef, which means to ignore the entry. + * @param maxval Maximum allowed value of the float. The default is the + * special double, Undef, which means to ignore the entry. */ void addFloat(XML_Node& node, const std::string& titleString, const doublereal value, const std::string& unitsString="", const std::string& typeString="", const doublereal minval=Undef, const doublereal maxval=Undef); -//! This function adds a child node with the name, "floatArray", with a value -//! consisting of a comma separated list of floats +//! This function adds a child node with the name, "floatArray", with a value +//! consisting of a comma separated list of floats /*! - * This function will add a child node to the current XML node, with the - * name "floatArray". It will have a title attribute, and the body of the - * XML node will be filled out with a comma separated list of doublereals. + * This function will add a child node to the current XML node, with the name + * "floatArray". It will have a title attribute, and the body of the XML node + * will be filled out with a comma separated list of doublereals. * - * Example: + * Example: * - * Code snippet: - * @code - * const XML_Node &node; - * std::string titleString = "additionalTemperatures"; - * int n = 3; - * int Tcases[3] = [273.15, 298.15, 373.15]; - * std::string typeString = "optional"; - * std::string units = "Kelvin"; - * addFloatArray(node, titleString, n, &cases[0], typeString, units); - * @endcode + * @code + * const XML_Node &node; + * std::string titleString = "additionalTemperatures"; + * int n = 3; + * int Tcases[3] = [273.15, 298.15, 373.15]; + * std::string typeString = "optional"; + * std::string units = "Kelvin"; + * addFloatArray(node, titleString, n, &cases[0], typeString, units); + * @endcode * * Creates the following the snippet in the XML file: * @@ -141,21 +136,20 @@ void addFloat(XML_Node& node, const std::string& titleString, * <\floatArray> * <\parentNode> * - * @param node reference to the XML_Node object of the parent XML element - * @param titleString String name of the title attribute - * @param n Length of the doubles vector. - * @param values Pointer to a vector of doubles - * @param unitsString String name of the Units attribute. This is an optional - * parameter. The default is to have an empty string. - * @param typeString String type. This is an optional parameter. The default - * is to have an empty string. - * @param minval Minimum allowed value of the int. This is an optional - * parameter. The default is the - * special double, Undef, which means to ignore the - * entry. - * @param maxval Maximum allowed value of the int. This is an optional - * parameter. The default is the special double, - * Undef, which means to ignore the entry. + * @param node reference to the XML_Node object of the parent XML element + * @param titleString String name of the title attribute + * @param n Length of the doubles vector. + * @param values Pointer to a vector of doubles + * @param unitsString String name of the Units attribute. This is an optional + * parameter. The default is to have an empty string. + * @param typeString String type. This is an optional parameter. The default + * is to have an empty string. + * @param minval Minimum allowed value of the int. This is an optional + * parameter. The default is the special double, Undef, + * which means to ignore the entry. + * @param maxval Maximum allowed value of the int. This is an optional + * parameter. The default is the special double, + * Undef, which means to ignore the entry. */ void addFloatArray(XML_Node& node, const std::string& titleString, const size_t n, const doublereal* const values, @@ -172,16 +166,15 @@ void addFloatArray(XML_Node& node, const std::string& titleString, * * Example: * - * Code snipet: - * @code - * const XML_Node &node; - * std::string titleString = "additionalTemperatures"; - * int n = 3; - * int Tcases[3] = [273.15, 298.15, 373.15]; - * std::string typeString = "optional"; - * std::string units = "Kelvin"; - * addNamedFloatArray(node, titleString, n, &cases[0], typeString, units); - * @endcode + * @code + * const XML_Node &node; + * std::string titleString = "additionalTemperatures"; + * int n = 3; + * int Tcases[3] = [273.15, 298.15, 373.15]; + * std::string typeString = "optional"; + * std::string units = "Kelvin"; + * addNamedFloatArray(node, titleString, n, &cases[0], typeString, units); + * @endcode * * Creates the following the snippet in the XML file: * @@ -221,11 +214,10 @@ void addNamedFloatArray(XML_Node& parentNode, const std::string& name, const siz * * Example: * - * Code snippet: - * @code - * const XML_Node &node; - * addString(node, "titleString", "valueString", "typeString"); - * @endcode + * @code + * const XML_Node &node; + * addString(node, "titleString", "valueString", "typeString"); + * @endcode * * Creates the following the snippet in the XML file: * @@ -256,15 +248,14 @@ void addString(XML_Node& node, const std::string& titleString, * * Example: * - * Code snippet: - * @code - * const XML_Node &State_XMLNode; - * vector_fp v; - * bool convert = true; - * unitsString = ""; - * nodeName="floatArray"; - * getFloatArray(State_XMLNode, v, convert, unitsString, nodeName); - * @endcode + * @code + * const XML_Node &State_XMLNode; + * vector_fp v; + * bool convert = true; + * unitsString = ""; + * nodeName="floatArray"; + * getFloatArray(State_XMLNode, v, convert, unitsString, nodeName); + * @endcode * * reads the corresponding XML file: * @@ -283,21 +274,21 @@ void addString(XML_Node& node, const std::string& titleString, * @param convert Conversion to SI is carried out if this boolean is * True. The default is true. * @param unitsString String name of the type attribute. This is an optional - * parameter. The default is to have an empty string. - * The only string that is recognized is actEnergy. - * Anything else has no effect. This affects what - * units converter is used. - * @param nodeName XML Name of the XML node to read. - * The default value for the node name is floatArray - * @return Returns the number of floats read into v. + * parameter. The default is to have an empty string. The + * only string that is recognized is actEnergy. Anything + * else has no effect. This affects what units converter is + * used. + * @param nodeName XML Name of the XML node to read. The default value for + * the node name is floatArray + * @returns the number of floats read into v. */ size_t getFloatArray(const XML_Node& node, vector_fp & v, const bool convert=true, const std::string& unitsString="", const std::string& nodeName = "floatArray"); -//! This function interprets the value portion of an XML element -//! as a string. It then separates the string up into tokens -//! according to the location of white space. +//! This function interprets the value portion of an XML element as a string. It +//! then separates the string up into tokens according to the location of white +//! space. /*! * The separate tokens are returned in the string vector * @@ -314,16 +305,14 @@ void getStringArray(const XML_Node& node, std::vector& v); * * H:4 C:1 * - * The string is first separated into a string vector according to the - * location of white space. Then each string is again separated into two parts - * according to the location of a colon in the string. The first part of the - * string is used as the key, while the second part of the string is used as - * the value, in the return map. It is an error to not find a colon in each - * string pair. + * The string is first separated into a string vector according to the location + * of white space. Then each string is again separated into two parts according + * to the location of a colon in the string. The first part of the string is + * used as the key, while the second part of the string is used as the value, in + * the return map. It is an error to not find a colon in each string pair. * * @param node Current node - * @param m Output Map containing the pairs of values found - * in the XML Node + * @param m Output Map containing the pairs of values found in the XML Node */ void getMap(const XML_Node& node, std::map& m); @@ -352,14 +341,13 @@ void getMap(const XML_Node& node, std::map& m); * @param node XML Node * @param key Vector of keys for each entry * @param val Vector of values for each entry - * - * @return Returns the number of pairs found + * @returns the number of pairs found */ int getPairs(const XML_Node& node, std::vector& key, std::vector& val); -//! This function interprets the value portion of an XML element -//! as a series of "Matrix ids and entries" separated by white space. +//! This function interprets the value portion of an XML element as a series of +//! "Matrix ids and entries" separated by white space. /*! * Each pair consists of non-whitespace characters. The first two ":" found in * the pair string is used to separate the string into three parts. The first @@ -389,11 +377,11 @@ int getPairs(const XML_Node& node, std::vector& key, * @param keyStringRow Key string for the row * @param keyStringCol Key string for the column entries * @param returnValues Return Matrix. - * @param convert If this is true, and if the node has a units - * attribute, then conversion to SI units is carried - * out. Default is true. - * @param matrixSymmetric If true entries are made so that the matrix - * is always symmetric. Default is false. + * @param convert If this is true, and if the node has a units attribute, + * then conversion to SI units is carried out. Default is + * true. + * @param matrixSymmetric If true entries are made so that the matrix is always + * symmetric. Default is false. */ void getMatrixValues(const XML_Node& node, const std::vector& keyStringRow, @@ -410,11 +398,11 @@ void getMatrixValues(const XML_Node& node, * addInteger(). One value per XML_node is expected. * * Example: - * @code - * const XML_Node &State_XMLNode; - * std::map v; - * getInteger(State_XMLNode, v); - * @endcode + * @code + * const XML_Node &State_XMLNode; + * std::map v; + * getInteger(State_XMLNode, v); + * @endcode * reads the corresponding XML file: * * @@ -429,8 +417,8 @@ void getMatrixValues(const XML_Node& node, * v["i2"] = 2 * v["i3"] = 3 * - * @param node Current XML node to get the values from - * @param v Output map of the results. + * @param node Current XML node to get the values from + * @param v Output map of the results. */ void getIntegers(const XML_Node& node, std::map& v); @@ -444,14 +432,13 @@ void getIntegers(const XML_Node& node, std::map& v); * * Example: * - * Code snippet: - * @code - * const XML_Node &State_XMLNode; - * doublereal pres = OneAtm; - * if (state_XMLNode.hasChild("pressure")) { - * pres = getFloat(State_XMLNode, "pressure", "toSI"); - * } - * @endcode + * @code + * const XML_Node &State_XMLNode; + * doublereal pres = OneAtm; + * if (state_XMLNode.hasChild("pressure")) { + * pres = getFloat(State_XMLNode, "pressure", "toSI"); + * } + * @endcode * * reads the corresponding XML file: * @@ -478,15 +465,14 @@ doublereal getFloat(const XML_Node& parent, const std::string& name, * * Example: * - * Code snippet: - * @code - * const XML_Node &State_XMLNode; - * doublereal pres = OneAtm; - * if (state_XMLNode.hasChild("pressure")) { - * XML_Node *pres_XMLNode = State_XMLNode.getChild("pressure"); - * pres = getFloatCurrent(pres_XMLNode, "toSI"); - * } - * @endcode + * @code + * const XML_Node &State_XMLNode; + * doublereal pres = OneAtm; + * if (state_XMLNode.hasChild("pressure")) { + * XML_Node *pres_XMLNode = State_XMLNode.getChild("pressure"); + * pres = getFloatCurrent(pres_XMLNode, "toSI"); + * } + * @endcode * * Reads the corresponding XML file: * @@ -501,7 +487,7 @@ doublereal getFloat(const XML_Node& parent, const std::string& name, */ doublereal getFloatCurrent(const XML_Node& currXML, const std::string& type=""); -//! Get an optional floating-point value from a child element. +//! Get an optional floating-point value from a child element. /*! * Returns a doublereal value for the child named 'name' of element 'parent'. * If 'type' is supplied and matches a known unit type, unit conversion to SI @@ -509,12 +495,11 @@ doublereal getFloatCurrent(const XML_Node& currXML, const std::string& type=""); * * Example: * - * Code snippet: - * @code - * const XML_Node &State_XMLNode; - * doublereal pres = OneAtm; - * bool exists = getOptionalFloat(State_XMLNode, "pressure", pres, "toSI"); - * @endcode + * @code + * const XML_Node &State_XMLNode; + * doublereal pres = OneAtm; + * bool exists = getOptionalFloat(State_XMLNode, "pressure", pres, "toSI"); + * @endcode * * reads the corresponding XML file: * @@ -524,13 +509,12 @@ doublereal getFloatCurrent(const XML_Node& currXML, const std::string& type=""); * * @param parent reference to the XML_Node object of the parent XML element * @param name Name of the XML child element - * @param fltRtn Float Return. It will be overridden if the XML - * element exists. + * @param fltRtn Float Return. It will be overridden if the XML element exists. * @param type String type. Currently known types are "toSI" and * "actEnergy", and "" , for no conversion. The default value is * "", which implies that no conversion is allowed. * - * @return returns true if the child element named "name" exists + * @returns true if the child element named "name" exists */ bool getOptionalFloat(const XML_Node& parent, const std::string& name, doublereal& fltRtn, const std::string& type=""); @@ -542,14 +526,13 @@ bool getOptionalFloat(const XML_Node& parent, const std::string& name, * * Example: * - * Code snippet: - * @code - * const XML_Node &State_XMLNode; - * int number = 1; - * if (state_XMLNode.hasChild("NumProcs")) { - * number = getInteger(State_XMLNode, "numProcs"); - * } - * @endcode + * @code + * const XML_Node &State_XMLNode; + * int number = 1; + * if (state_XMLNode.hasChild("NumProcs")) { + * number = getInteger(State_XMLNode, "numProcs"); + * } + * @endcode * * reads the corresponding XML file: * @@ -570,14 +553,13 @@ int getInteger(const XML_Node& parent, const std::string& name); * * Example: * - * Code snippet: - * @code - * const XML_Node &State_XMLNode; - * doublereal pres = OneAtm; - * if (state_XMLNode.hasChild("pressure")) { - * pres = getFloatDefaultUnits(State_XMLNode, "pressure", "Pa", "toSI"); - * } - * @endcode + * @code + * const XML_Node &State_XMLNode; + * doublereal pres = OneAtm; + * if (state_XMLNode.hasChild("pressure")) { + * pres = getFloatDefaultUnits(State_XMLNode, "pressure", "Pa", "toSI"); + * } + * @endcode * * reads the corresponding XML file: * @@ -606,12 +588,11 @@ doublereal getFloatDefaultUnits(const XML_Node& parent, * * Example: * - * Code snippet: - * @code - * std::string modelName = ""; - * bool exists = getOptionalModel(transportNode, "compositionDependence", + * @code + * std::string modelName = ""; + * bool exists = getOptionalModel(transportNode, "compositionDependence", * modelName); - * @endcode + * @endcode * * reads the corresponding XML file: * @@ -634,8 +615,7 @@ bool getOptionalModel(const XML_Node& parent, const std::string& nodeName, /*! * @param node Current node from which to conduct the search * @param title Name of the title attribute - * @return Returns a pointer to the matched child node. Returns 0 if no node - * is found. + * @returns a pointer to the matched child node. Returns 0 if no node is found. */ XML_Node* getByTitle(const XML_Node& node, const std::string& title); @@ -650,12 +630,11 @@ XML_Node* getByTitle(const XML_Node& node, const std::string& title); * * Example: * - * Code snipet: - * @code - * const XML_Node &node; - * getString(XML_Node& node, std::string titleString, std::string valueString, - * std::string typeString); - * @endcode + * @code + * const XML_Node &node; + * getString(XML_Node& node, std::string titleString, std::string valueString, + * std::string typeString); + * @endcode * * Reads the following the snippet in the XML file: * @@ -678,13 +657,13 @@ void getString(const XML_Node& node, const std::string& titleString, /*! * If the child XML_node named "name" doesn't exist, the empty string is returned. * - * Code snippet: - * @code - * const XML_Node &parent; - * string nameString = "vacancy_species"; - * string valueString = getChildValue(parent, nameString - * std::string typeString); - * @endcode + * Example: + * @code + * const XML_Node &parent; + * string nameString = "vacancy_species"; + * string valueString = getChildValue(parent, nameString + * std::string typeString); + * @endcode * * returns `valueString = "O(V)"` from the following the snippet in the XML file: * @@ -701,28 +680,28 @@ std::string getChildValue(const XML_Node& parent, //! Convert a cti file into a ctml file /*! - * @param file Pointer to the file - * @param debug Turn on debug printing + * @param file Pointer to the file + * @param debug Turn on debug printing * - * @ingroup inputfiles + * @ingroup inputfiles */ void ct2ctml(const char* file, const int debug = 0); //! Get a string with the ctml representation of a cti file. /*! - * @param file Path to the input file in CTI format - * @return String containing the XML representation of the input file + * @param file Path to the input file in CTI format + * @return String containing the XML representation of the input file * - * @ingroup inputfiles + * @ingroup inputfiles */ std::string ct2ctml_string(const std::string& file); //! Get a string with the ctml representation of a cti input string. /*! - * @param cti String containing the cti representation - * @return String containing the XML representation of the input + * @param cti String containing the cti representation + * @return String containing the XML representation of the input * - * @ingroup inputfiles + * @ingroup inputfiles */ std::string ct_string2ctml_string(const std::string& cti); diff --git a/include/cantera/base/global.h b/include/cantera/base/global.h index 65f5ea625..785506735 100644 --- a/include/cantera/base/global.h +++ b/include/cantera/base/global.h @@ -6,10 +6,8 @@ * * @ingroup utils * - * These functions store - * some parameters in global storage that are accessible at all times - * from the calling application. - * Contains module definitions for + * These functions store some parameters in global storage that are accessible + * at all times from the calling application. Contains module definitions for * - inputfiles (see \ref inputfiles) * - logs (see \ref logs) * - textlogs (see \ref textlogs) @@ -120,9 +118,9 @@ void thread_complete(); //! Returns root directory where %Cantera is installed /*! - * @return Returns a string containing the name of the base directory where - * %Cantera is installed. If the environmental variable CANTERA_ROOT is - * defined, this function will return its value, preferentially. + * @returns a string containing the name of the base directory where %Cantera is + * installed. If the environmental variable CANTERA_ROOT is defined, this + * function will return its value, preferentially. * * @ingroup inputfiles */ @@ -225,55 +223,39 @@ void close_XML_File(const std::string& file); //! XML tree or in another input file specified by the file //! part of the file_ID string. /*! - * Searches are based on the - * ID attribute of the XML element only. + * Searches are based on the ID attribute of the XML element only. * - * @param file_ID This is a concatenation of two strings separated - * by the "#" character. The string before the - * pound character is the file name of an XML - * file to carry out the search. The string after - * the # character is the ID attribute - * of the XML element to search for. - * The string is interpreted as a file string if - * no # character is in the string. - * - * @param root If the file string is empty, searches for the - * XML element with matching ID attribute are - * carried out from this XML node. - * - * @return - * Returns the XML_Node, if found. Returns null if not found. + * @param file_ID This is a concatenation of two strings separated by the "#" + * character. The string before the pound character is the file + * name of an XML file to carry out the search. The string after + * the # character is the ID attribute of the XML element to + * search for. The string is interpreted as a file string if no # + * character is in the string. + * @param root If the file string is empty, searches for the XML element with + * matching ID attribute are carried out from this XML node. + * @returns the XML_Node, if found. Returns null if not found. */ XML_Node* get_XML_Node(const std::string& file_ID, XML_Node* root); -//! This routine will locate an XML node in either the input -//! XML tree or in another input file specified by the file -//! part of the file_ID string. +//! This routine will locate an XML node in either the input XML tree or in +//! another input file specified by the file part of the file_ID string. /*! - * Searches are based on the - * XML element name and the ID attribute of the XML element. - * An exact match of both is usually required. However, the - * ID attribute may be set to "", in which case the first - * XML element with the correct element name will be returned. + * Searches are based on the XML element name and the ID attribute of the XML + * element. An exact match of both is usually required. However, the ID + * attribute may be set to "", in which case the first XML element with the + * correct element name will be returned. * * @param nameTarget This is the XML element name to look for. - * - * @param file_ID This is a concatenation of two strings separated - * by the "#" character. The string before the - * pound character is the file name of an XML - * file to carry out the search. The string after - * the # character is the ID attribute - * of the XML element to search for. - * The string is interpreted as a file string if - * no # character is in the string. - * - * @param root If the file string is empty, searches for the - * XML element with matching ID attribute are - * carried out from this XML node. - * - * @return - * Returns the XML_Node, if found. Returns null if not found. + * @param file_ID This is a concatenation of two strings separated by the "#" + * character. The string before the pound character is the file + * name of an XML file to carry out the search. The string after + * the # character is the ID attribute of the XML element to + * search for. The string is interpreted as a file string if no # + * character is in the string. + * @param root If the file string is empty, searches for the XML element with + * matching ID attribute are carried out from this XML node. + * @returns the XML_Node, if found. Returns null if not found. */ XML_Node* get_XML_NameID(const std::string& nameTarget, const std::string& file_ID, diff --git a/include/cantera/base/logger.h b/include/cantera/base/logger.h index 85aa90b8a..b058ce884 100644 --- a/include/cantera/base/logger.h +++ b/include/cantera/base/logger.h @@ -13,21 +13,18 @@ namespace Cantera { -/// /// Base class for 'loggers' that write text messages to log files. /// -/// This class is used to direct log messages to application- or -/// environment-specific output. The default is to simply print -/// the messages to the standard output stream or standard error -/// stream, but classes may be derived from Logger that implement -/// other output options. This is important when Cantera is used -/// in applications that do not display the standard output, such -/// as MATLAB. The Cantera MATLAB interface derives a class from -/// Logger that implements these methods with MATLAB-specific -/// procedures, insuring that the messages will be passed through -/// to the user. It would also be possible to derive a class that -/// displayed the messages in a pop-up window, or redirected them -/// to a file, etc. +/// This class is used to direct log messages to application- or environment- +/// specific output. The default is to simply print the messages to the standard +/// output stream or standard error stream, but classes may be derived from +/// Logger that implement other output options. This is important when Cantera +/// is used in applications that do not display the standard output, such as +/// MATLAB. The Cantera MATLAB interface derives a class from Logger that +/// implements these methods with MATLAB-specific procedures, insuring that the +/// messages will be passed through to the user. It would also be possible to +/// derive a class that displayed the messages in a pop-up window, or redirected +/// them to a file, etc. /// /// To install a logger, call function setLogger (global.h / misc.cpp). /// @@ -47,10 +44,9 @@ public: //! Write a log message. /*! - * The default behavior is to write to - * the standard output. Note that no end-of-line character is - * appended to the message, and so if one is desired it must - * be included in the string. + * The default behavior is to write to the standard output. Note that no + * end-of-line character is appended to the message, and so if one is + * desired it must be included in the string. * * @param msg String message to be written to cout */ @@ -60,8 +56,8 @@ public: //! Write an end of line character and flush output. /*! - * Some systems treat endl and \n differently. The endl - * statement causes a flushing of stdout to the screen. + * Some systems treat endl and \n differently. The endl statement causes a + * flushing of stdout to the screen. */ virtual void writeendl() { std::cout << std::endl; @@ -69,14 +65,12 @@ public: //! Write an error message and quit. /*! - * The default behavior is - * to write to the standard error stream, and then call - * exit(). Note that no end-of-line character is appended to - * the message, and so if one is desired it must be included - * in the string. Note that this default behavior will - * terminate the application Cantera is invoked from (MATLAB, - * Excel, etc.) If this is not desired, then derive a class - * and reimplement this method. + * The default behavior is to write to the standard error stream, and then + * call exit(). Note that no end-of-line character is appended to the + * message, and so if one is desired it must be included in the string. Note + * that this default behavior will terminate the application Cantera is + * invoked from (MATLAB, Excel, etc.) If this is not desired, then derive a + * class and reimplement this method. * * @param msg Error message to be written to cerr. */ diff --git a/include/cantera/base/plots.h b/include/cantera/base/plots.h index 0e6031335..e8c5b96ec 100644 --- a/include/cantera/base/plots.h +++ b/include/cantera/base/plots.h @@ -14,7 +14,7 @@ namespace Cantera { -//! Write a Plotting file +//! Write a Plotting file /*! * @param fname Output file name * @param fmt Either TEC or XL or CSV @@ -27,7 +27,7 @@ void writePlotFile(const std::string& fname, const std::string& fmt, const std::string& plotTitle, const std::vector &names, const Array2D& data); -//! Write a Tecplot data file. +//! Write a Tecplot data file. /*! * @param s output stream * @param title plot title diff --git a/include/cantera/base/stringUtils.h b/include/cantera/base/stringUtils.h index 59bfc1158..f42387246 100644 --- a/include/cantera/base/stringUtils.h +++ b/include/cantera/base/stringUtils.h @@ -22,168 +22,164 @@ namespace Cantera */ std::string fp2str(const double x, const std::string& fmt="%g"); -//! Convert an int to a string using a format converter +//! Convert an int to a string using a format converter /*! - * @param n int to be converted - * @param fmt format converter for an int int the printf command + * @param n int to be converted + * @param fmt format converter for an int int the printf command */ std::string int2str(const int n, const std::string& fmt="%d"); -//! Convert an unsigned integer to a string +//! Convert an unsigned integer to a string /*! - * @param n int to be converted + * @param n int to be converted */ std::string int2str(const size_t n); -//! Convert a vector to a string (separated by commas) +//! Convert a vector to a string (separated by commas) /*! - * @param v vector to be converted - * @param fmt Format to be used (printf style) for each element - * @param sep Separator + * @param v vector to be converted + * @param fmt Format to be used (printf style) for each element + * @param sep Separator */ std::string vec2str(const vector_fp& v, const std::string& fmt="%g", const std::string& sep=", "); //! Strip the leading and trailing white space from a string /*! - * The command isprint() is used to determine printable characters. + * The command isprint() is used to determine printable characters. * - * @param s Input string - * @return Returns a copy of the string, stripped of leading and trailing - * white space + * @param s Input string + * @returns a copy of the string, stripped of leading and trailing white space */ std::string stripws(const std::string& s); //! Strip non-printing characters wherever they are /*! - * @param s Input string - * @return Returns a copy of the string, stripped of all non- - * printing characters. + * @param s Input string + * @returns a copy of the string, stripped of all non- printing characters. */ std::string stripnonprint(const std::string& s); //! Cast a copy of a string to lower case /*! - * @param s Input string - * @return Returns a copy of the string, - * with all characters lowercase. + * @param s Input string + * @returns a copy of the string, with all characters lowercase. */ std::string lowercase(const std::string& s); //! Parse a composition string into a map consisting of individual //! key:composition pairs. /*! - * Elements present in *names* but not in the composition string will have - * a value of 0. Elements present in the composition string but not in *names* - * will generate an exception. The composition is a double. Example: + * Elements present in *names* but not in the composition string will have + * a value of 0. Elements present in the composition string but not in *names* + * will generate an exception. The composition is a double. Example: * - * Input is + * Input is * * "ice:1 snow:2" * names = ["fire", "ice", "snow"] * - * Output is + * Output is * x["fire"] = 0 * x["ice"] = 1 * x["snow"] = 2 * - * @param ss original string consisting of multiple key:composition + * @param ss original string consisting of multiple key:composition * pairs on multiple lines - * @param names (optional) valid names for elements in the composition map. If + * @param names (optional) valid names for elements in the composition map. If * empty or unspecified, all values are allowed. - * @return map of names to values + * @return map of names to values */ compositionMap parseCompString(const std::string& ss, const std::vector& names=std::vector()); //! Translate a string into one integer value /*! - * No error checking is done on the conversion. The c stdlib function - * atoi() is used. + * No error checking is done on the conversion. The c stdlib function atoi() is + * used. * - * @param val String value of the integer - * @return Returns an integer + * @param val String value of the integer + * @return Returns an integer */ int intValue(const std::string& val); //! Translate a string into one doublereal value /*! - * No error checking is done on the conversion. + * No error checking is done on the conversion. * - * @param val String value of the double - * @return Returns a doublereal value + * @param val String value of the double + * @return Returns a doublereal value */ doublereal fpValue(const std::string& val); //! Translate a string into one doublereal value, with error checking /*! - * fpValueCheck is a wrapper around the C++ stringstream double parser. It - * does quite a bit more error checking than atof() or strtod(), and is quite - * a bit more restrictive. + * fpValueCheck is a wrapper around the C++ stringstream double parser. It + * does quite a bit more error checking than atof() or strtod(), and is quite + * a bit more restrictive. * - * First it interprets both E, e, d, and D as exponents. stringstreams only - * interpret e or E as an exponent character. + * First it interprets both E, e, d, and D as exponents. stringstreams only + * interpret e or E as an exponent character. * - * It only accepts a string as well formed if it consists as a single token. - * Multiple words will raise an exception. It will raise a CanteraError for - * NAN and inf entries as well, in contrast to atof() or strtod(). The user - * needs to know that a serious numerical issue has occurred. + * It only accepts a string as well formed if it consists as a single token. + * Multiple words will raise an exception. It will raise a CanteraError for + * NAN and inf entries as well, in contrast to atof() or strtod(). The user + * needs to know that a serious numerical issue has occurred. * - * It does not accept hexadecimal numbers. + * It does not accept hexadecimal numbers. * - * It always use the C locale, regardless of any locale settings. + * It always use the C locale, regardless of any locale settings. * - * @param val String representation of the number - * @return Returns a doublereal value + * @param val String representation of the number + * @return Returns a doublereal value */ doublereal fpValueCheck(const std::string& val); //! Parse a name string, separating out the phase name from the species name /*! - * Name strings must not contain these internal characters "; \n \t ," - * Only one colon is allowed, the one separating the phase name from the - * species name. Therefore, names may not include a colon. + * Name strings must not contain these internal characters "; \n \t ," Only one + * colon is allowed, the one separating the phase name from the species name. + * Therefore, names may not include a colon. * - * @param[in] nameStr Name string containing the phase name and the - * species name separated by a colon. The phase name - * is optional. example: "silane:SiH4" - * @param[out] phaseName Name of the phase, if specified. If not specified, - * a blank string is returned. - * @return Species name is returned. If nameStr is blank an - * empty string is returned. + * @param[in] nameStr Name string containing the phase name and the species + * name separated by a colon. The phase name is optional. + * example: "silane:SiH4" + * @param[out] phaseName Name of the phase, if specified. If not specified, a + * blank string is returned. + * @returns species name. If nameStr is blank an empty string is returned. */ std::string parseSpeciesName(const std::string& nameStr, std::string& phaseName); //! Line wrap a string via a copy operation /*! - * @param s Input string to be line wrapped - * @param len Length at which to wrap. The default is 70. + * @param s Input string to be line wrapped + * @param len Length at which to wrap. The default is 70. */ std::string wrapString(const std::string& s, const int len=70); //! Interpret one or two token string as a single double /*! - * This is similar to atof(). However, the second token is interpreted as an - * MKS units string and a conversion factor to MKS is applied. + * This is similar to atof(). However, the second token is interpreted as an + * MKS units string and a conversion factor to MKS is applied. * - * Example: "1.0 atm" results in the number 1.01325e5. + * Example: "1.0 atm" results in the number 1.01325e5. * - * @param strSI string to be converted. One or two tokens - * @return returns a converted double + * @param strSI string to be converted. One or two tokens + * @returns a converted double */ doublereal strSItoDbl(const std::string& strSI); -//! This function separates a string up into tokens -//! according to the location of white space. +//! This function separates a string up into tokens according to the location of +//! white space. /*! - * White space includes the new line character. tokens - * are stripped of leading and trailing white space. + * White space includes the new line character. tokens are stripped of leading + * and trailing white space. * - * The separate tokens are returned in a string vector, v. + * The separate tokens are returned in a string vector, v. * - * @param oval String to be broken up - * @param v Output vector of tokens. + * @param oval String to be broken up + * @param v Output vector of tokens. */ void tokenizeString(const std::string& oval, std::vector& v); diff --git a/include/cantera/base/utilities.h b/include/cantera/base/utilities.h index 563444d89..47f263894 100644 --- a/include/cantera/base/utilities.h +++ b/include/cantera/base/utilities.h @@ -8,9 +8,8 @@ /** * @defgroup utils Templated Utility Functions * - * These are templates to perform various simple operations on arrays. - * Note that the compiler will inline these, so using them carries no - * performance penalty. + * These are templates to perform various simple operations on arrays. Note that + * the compiler will inline these, so using them carries no performance penalty. */ #ifndef CT_UTILITIES_H @@ -26,24 +25,22 @@ namespace Cantera { //! Unary operator to multiply the argument by a constant. /*! - * The form of this operator is designed for use by std::transform. - * @see @ref scale(). + * The form of this operator is designed for use by std::transform. + * @see @ref scale(). */ template struct timesConstant : public std::unary_function { //! Constructor /*! - * @param c Constant of templated type T - * that will be stored internally within the object - * and used in the multiplication operation + * @param c Constant of templated type T that will be stored internally + * within the object and used in the multiplication operation */ timesConstant(T c) : m_c(c) {} //! Parenthesis operator returning a double /*! - * @param x Variable of templated type T that will be - * used in the multiplication operator - * @return Returns a value of type double from the internal - * multiplication + * @param x Variable of templated type T that will be used in the + * multiplication operator + * @returns a value of type double from the internal multiplication */ double operator()(T x) { return m_c * x; @@ -53,16 +50,14 @@ template struct timesConstant : public std::unary_function { T m_c; }; -//! Templated Inner product of two vectors of length 4. +//! Templated Inner product of two vectors of length 4. /*! - * If either \a x - * or \a y has length greater than 4, only the first 4 elements + * If either \a x or \a y has length greater than 4, only the first 4 elements * will be used. * * @param x first reference to the templated class V * @param y second reference to the templated class V - * @return - * This class returns a hard-coded type, doublereal. + * @return This class returns a hard-coded type, doublereal. */ template inline doublereal dot4(const V& x, const V& y) @@ -70,16 +65,14 @@ inline doublereal dot4(const V& x, const V& y) return x[0]*y[0] + x[1]*y[1] + x[2]*y[2] + x[3]*y[3]; } -//! Templated Inner product of two vectors of length 5 +//! Templated Inner product of two vectors of length 5 /*! - * If either \a x - * or \a y has length greater than 4, only the first 4 elements + * If either \a x or \a y has length greater than 4, only the first 4 elements * will be used. * * @param x first reference to the templated class V * @param y second reference to the templated class V - * @return - * This class returns a hard-coded type, doublereal. + * @return This class returns a hard-coded type, doublereal. */ template inline doublereal dot5(const V& x, const V& y) @@ -106,8 +99,7 @@ inline doublereal dot5(const V& x, const V& y) * iterator class InputIter. * @param y_begin Iterator pointing to the beginning of y, belonging to the * iterator class InputIter2. - * @return - * The return is hard-coded to return a double. + * @return The return is hard-coded to return a double. */ template inline doublereal dot(InputIter x_begin, InputIter x_end, @@ -116,7 +108,7 @@ inline doublereal dot(InputIter x_begin, InputIter x_end, return inner_product(x_begin, x_end, y_begin, 0.0); } -//! Multiply elements of an array by a scale factor. +//! Multiply elements of an array by a scale factor. /*! * \code * vector_fp in(8, 1.0), out(8); @@ -156,13 +148,13 @@ inline void scale(InputIter begin, InputIter end, * multiply_each(x, x+10, y); * \endcode * - * @param x_begin Iterator pointing to the beginning of the vector x, belonging to the - * iterator class InputIter. - * @param x_end Iterator pointing to the end of the vector x, belonging to the - * iterator class InputIter. The difference between end and begin - * determines the loop length - * @param y_begin Iterator pointing to the beginning of the vector y, belonging to the - * iterator class outputIter. + * @param x_begin Iterator pointing to the beginning of the vector x, + * belonging to the iterator class InputIter. + * @param x_end Iterator pointing to the end of the vector x, belonging to + * the iterator class InputIter. The difference between end and + * begin determines the loop length + * @param y_begin Iterator pointing to the beginning of the vector y, + * belonging to the iterator class outputIter. */ template inline void multiply_each(OutputIter x_begin, OutputIter x_end, @@ -191,11 +183,11 @@ inline void multiply_each(OutputIter x_begin, OutputIter x_end, * double amax = absmax(x, x+10); * \endcode * - * @param begin Iterator pointing to the beginning of the x vector, belonging to the - * iterator class InputIter. - * @param end Iterator pointing to the end of the x vector, belonging to the - * iterator class InputIter. The difference between end and begin - * determines the loop length + * @param begin Iterator pointing to the beginning of the x vector, + * belonging to the iterator class InputIter. + * @param end Iterator pointing to the end of the x vector, belonging to + * the iterator class InputIter. The difference between end and + * begin determines the loop length */ template inline doublereal absmax(InputIter begin, InputIter end) @@ -207,7 +199,8 @@ inline doublereal absmax(InputIter begin, InputIter end) return amax; } -//! Normalize the values in a sequence, such that they sum to 1.0 (templated version) +//! Normalize the values in a sequence, such that they sum to 1.0 (templated +//! version) /*! * The template arguments are: template * @@ -227,13 +220,13 @@ inline doublereal absmax(InputIter begin, InputIter end) * normalize(x, x+10, y); * \endcode * - * @param begin Iterator pointing to the beginning of the x vector, belonging to the - * iterator class InputIter. - * @param end Iterator pointing to the end of the x vector, belonging to the - * iterator class InputIter. The difference between end and begin - * determines the loop length - * @param out Iterator pointing to the beginning of the output vector, belonging to the - * iterator class OutputIter. + * @param begin Iterator pointing to the beginning of the x vector, + * belonging to the iterator class InputIter. + * @param end Iterator pointing to the end of the x vector, belonging to + * the iterator class InputIter. The difference between end and + * begin determines the loop length + * @param out Iterator pointing to the beginning of the output vector, + * belonging to the iterator class OutputIter. */ template inline void normalize(InputIter begin, InputIter end, @@ -262,13 +255,13 @@ inline void normalize(InputIter begin, InputIter end, * divide_each(x, x+10, y); * \endcode * - * @param x_begin Iterator pointing to the beginning of the x vector, belonging to the - * iterator class OutputIter. - * @param x_end Iterator pointing to the end of the x vector, belonging to the - * iterator class OutputIter. The difference between end and begin - * determines the number of inner iterations. - * @param y_begin Iterator pointing to the beginning of the yvector, belonging to the - * iterator class InputIter. + * @param x_begin Iterator pointing to the beginning of the x vector, + * belonging to the iterator class OutputIter. + * @param x_end Iterator pointing to the end of the x vector, belonging to + * the iterator class OutputIter. The difference between end + * and begin determines the number of inner iterations. + * @param y_begin Iterator pointing to the beginning of the yvector, belonging + * to the iterator class InputIter. */ template inline void divide_each(OutputIter x_begin, OutputIter x_end, @@ -279,17 +272,17 @@ inline void divide_each(OutputIter x_begin, OutputIter x_end, } } -//! Increment each entry in \a x by the corresponding entry in \a y. +//! Increment each entry in \a x by the corresponding entry in \a y. /*! * The template arguments are: template * - * @param x_begin Iterator pointing to the beginning of the x vector, belonging to the - * iterator class OutputIter. - * @param x_end Iterator pointing to the end of the x vector, belonging to the - * iterator class OutputIter. The difference between end and begin - * determines the number of inner iterations. - * @param y_begin Iterator pointing to the beginning of the yvector, belonging to the - * iterator class InputIter. + * @param x_begin Iterator pointing to the beginning of the x vector, + * belonging to the iterator class OutputIter. + * @param x_end Iterator pointing to the end of the x vector, belonging to + * the iterator class OutputIter. The difference between end + * and begin determines the number of inner iterations. + * @param y_begin Iterator pointing to the beginning of the yvector, belonging + * to the iterator class InputIter. */ template inline void sum_each(OutputIter x_begin, OutputIter x_end, @@ -321,13 +314,13 @@ inline void sum_each(OutputIter x_begin, OutputIter x_end, * OutputIter is an iterator for the destination vector * IndexIter is an iterator for the index into the destination vector. * - * @param begin Iterator pointing to the beginning of the source vector, belonging to the - * iterator class InputIter. - * @param end Iterator pointing to the end of the source vector, belonging to the - * iterator class InputIter. The difference between end and begin - * determines the number of inner iterations. - * @param result Iterator pointing to the beginning of the output vector, belonging to the - * iterator class outputIter. + * @param begin Iterator pointing to the beginning of the source vector, + * belonging to the iterator class InputIter. + * @param end Iterator pointing to the end of the source vector, belonging + * to the iterator class InputIter. The difference between end + * and begin determines the number of inner iterations. + * @param result Iterator pointing to the beginning of the output vector, + * belonging to the iterator class outputIter. * @param index Iterator pointing to the beginning of the index vector, belonging to the * iterator class IndexIter. */ @@ -340,8 +333,8 @@ inline void scatter_copy(InputIter begin, InputIter end, } } -//! Multiply selected elements in an array by a contiguous -//! sequence of multipliers. +//! Multiply selected elements in an array by a contiguous sequence of +//! multipliers. /*! * The template arguments are: template * @@ -356,15 +349,17 @@ inline void scatter_copy(InputIter begin, InputIter end, * scatter_mult(multipliers, multipliers + 3, data.begin(), index); * \endcode * - * @param mult_begin Iterator pointing to the beginning of the multiplier vector, belonging to the - * iterator class InputIter. - * @param mult_end Iterator pointing to the end of the multiplier vector, belonging to the - * iterator class InputIter. The difference between end and begin - * determines the number of inner iterations. - * @param data Iterator pointing to the beginning of the output vector, belonging to the - * iterator class RandAccessIter, that will be selectively multiplied. - * @param index Iterator pointing to the beginning of the index vector, belonging to the - * iterator class IndexIter. + * @param mult_begin Iterator pointing to the beginning of the multiplier + * vector, belonging to the iterator class InputIter. + * @param mult_end Iterator pointing to the end of the multiplier vector, + * belonging to the iterator class InputIter. The difference + * between end and begin determines the number of inner + * iterations. + * @param data Iterator pointing to the beginning of the output vector, + * belonging to the iterator class RandAccessIter, that will + * be selectively multiplied. + * @param index Iterator pointing to the beginning of the index vector, + * belonging to the iterator class IndexIter. */ template inline void scatter_mult(InputIter mult_begin, InputIter mult_end, @@ -379,15 +374,14 @@ inline void scatter_mult(InputIter mult_begin, InputIter mult_end, /*! * The template arguments are: template * - * A small number (1.0E-20) is added before taking the log. This templated - * class does the indicated sun. The template must be an iterator. + * A small number (1.0E-20) is added before taking the log. This templated + * class does the indicated sun. The template must be an iterator. * * @param begin Iterator pointing to the beginning, belonging to the * iterator class InputIter. * @param end Iterator pointing to the end, belonging to the * iterator class InputIter. - * @return - * The return from this class is a double. + * @return The return from this class is a double. */ template inline doublereal sum_xlogx(InputIter begin, InputIter end) @@ -403,10 +397,9 @@ inline doublereal sum_xlogx(InputIter begin, InputIter end) /*! * The template arguments are: template * - * This class is templated twice. The first template, InputIter1 - * is the iterator that points to $x_k$. The second iterator - * InputIter2, point to $Q_k$. - * A small number (1.0E-20) is added before taking the log. + * This class is templated twice. The first template, InputIter1 is the iterator + * that points to $x_k$. The second iterator InputIter2, point to $Q_k$. A small + * number (1.0E-20) is added before taking the log. * * @param begin Iterator pointing to the beginning, belonging to the * iterator class InputIter1. @@ -414,8 +407,7 @@ inline doublereal sum_xlogx(InputIter begin, InputIter end) * iterator class InputIter1. * @param Q_begin Iterator pointing to the beginning of Q_k, belonging to the * iterator class InputIter2. - * @return - * The return from this class is hard coded to a doublereal. + * @return The return from this class is hard coded to a doublereal. */ template inline doublereal sum_xlogQ(InputIter1 begin, InputIter1 end, @@ -430,8 +422,8 @@ inline doublereal sum_xlogQ(InputIter1 begin, InputIter1 end, //! Templated evaluation of a polynomial of order 6 /*! - * @param x Value of the independent variable - First template parameter - * @param c Pointer to the polynomial - Second template parameter + * @param x Value of the independent variable - First template parameter + * @param c Pointer to the polynomial - Second template parameter */ template R poly6(D x, R* c) @@ -442,8 +434,8 @@ R poly6(D x, R* c) //! Templated evaluation of a polynomial of order 8 /*! - * @param x Value of the independent variable - First template parameter - * @param c Pointer to the polynomial - Second template parameter + * @param x Value of the independent variable - First template parameter + * @param c Pointer to the polynomial - Second template parameter */ template R poly8(D x, R* c) @@ -454,8 +446,8 @@ R poly8(D x, R* c) //! Templated evaluation of a polynomial of order 5 /*! - * @param x Value of the independent variable - First template parameter - * @param c Pointer to the polynomial - Second template parameter + * @param x Value of the independent variable - First template parameter + * @param c Pointer to the polynomial - Second template parameter */ template R poly5(D x, R* c) @@ -466,8 +458,8 @@ R poly5(D x, R* c) //! Evaluates a polynomial of order 4. /*! - * @param x Value of the independent variable. - * @param c Pointer to the polynomial coefficient array. + * @param x Value of the independent variable. + * @param c Pointer to the polynomial coefficient array. */ template R poly4(D x, R* c) @@ -478,8 +470,8 @@ R poly4(D x, R* c) //! Templated evaluation of a polynomial of order 3 /*! - * @param x Value of the independent variable - First template parameter - * @param c Pointer to the polynomial - Second template parameter + * @param x Value of the independent variable - First template parameter + * @param c Pointer to the polynomial - Second template parameter */ template R poly3(D x, R* c) @@ -489,14 +481,14 @@ R poly3(D x, R* c) //! Templated deep copy of a std vector of pointers /*! - * Performs a deep copy of a std vectors of pointers to an object. This template assumes that - * that the templated object has a functioning copy constructor. - * It also assumes that pointers are zero when they are not malloced. + * Performs a deep copy of a std vectors of pointers to an object. This template + * assumes that that the templated object has a functioning copy constructor. It + * also assumes that pointers are zero when they are not malloced. * - * @param fromVec Vector of pointers to a templated class. This will be - * deep-copied to the other vector - * @param toVec Vector of pointers to a templated class. This will be - * overwritten and on return will be a copy of the fromVec + * @param fromVec Vector of pointers to a templated class. This will be + * deep-copied to the other vector + * @param toVec Vector of pointers to a templated class. This will be + * overwritten and on return will be a copy of the fromVec */ template void deepStdVectorPointerCopy(const std::vector &fromVec, std::vector &toVec) @@ -523,18 +515,18 @@ void checkFinite(const double tmp); //! Check to see that all elements in an array are finite /*! - * Throws an exception if any element is NaN, +Inf, or -Inf - * @param name Name to be used in the exception message if the check fails - * @param values Array of *N* values to be checked - * @param N Number of elements in *values* + * Throws an exception if any element is NaN, +Inf, or -Inf + * @param name Name to be used in the exception message if the check fails + * @param values Array of *N* values to be checked + * @param N Number of elements in *values* */ void checkFinite(const std::string& name, double* values, size_t N); //! Const accessor for a value in a std::map. /*! - * This is a const alternative to operator[]. Roughly equivalent to the 'at' - * member function introduced in C++11. Throws std::out_of_range if the key - * does not exist. + * This is a const alternative to operator[]. Roughly equivalent to the 'at' + * member function introduced in C++11. Throws std::out_of_range if the key + * does not exist. */ template const U& getValue(const std::map& m, const T& key) { @@ -548,8 +540,8 @@ const U& getValue(const std::map& m, const T& key) { //! Const accessor for a value in a std::map. /* - * Similar to the two-argument version of getValue, but returns *default_val* - * if the key is not found instead of throwing an exception. + * Similar to the two-argument version of getValue, but returns *default_val* + * if the key is not found instead of throwing an exception. */ template const U& getValue(const std::map& m, const T& key, const U& default_val) { diff --git a/include/cantera/base/xml.h b/include/cantera/base/xml.h index e6b80ad7e..f0636ac1d 100644 --- a/include/cantera/base/xml.h +++ b/include/cantera/base/xml.h @@ -27,58 +27,54 @@ class XML_Reader public: //! Sole Constructor for the XML_Reader class /*! - * @param input Reference to the istream object containing - * the XML file + * @param input Reference to the istream object containing the XML file */ XML_Reader(std::istream& input); //! Read a single character from the input stream and returns it /*! - * All low level reads occur through this function. - * The function also keeps track of the line numbers. + * All low level reads occur through this function. The function also keeps + * track of the line numbers. * * @param ch Character to be returned. */ void getchr(char& ch); - //! Searches a string for the first occurrence of a valid - //! quoted string. + //! Searches a string for the first occurrence of a valid quoted string. /*! - * Quotes can start with either a single - * quote or a double quote, but must also end with the same - * type. Quotes may be commented out by preceding with a - * backslash character, '\\'. + * Quotes can start with either a single quote or a double quote, but must + * also end with the same type. Quotes may be commented out by preceding + * with a backslash character, '\\'. * - * @param aline This is the input string to be searched - * @param rstring Return value of the string that is found. - * The quotes are stripped from the string. - * @return Returns the integer position just after - * the quoted string. + * @param aline This is the input string to be searched + * @param rstring Return value of the string that is found. + * The quotes are stripped from the string. + * @returns the integer position just after the quoted string. */ int findQuotedString(const std::string& aline, std::string& rstring) const; - //! parseTag parses XML tags, i.e., the XML elements that are - //! in between angle brackets. + //! parseTag parses XML tags, i.e., the XML elements that are in between + //! angle brackets. /*! - * @param tag Tag to be parsed - input - * @param name Output string containing name of the XML - * @param[out] attribs map of attribute name and attribute value + * @param tag Tag to be parsed - input + * @param name Output string containing name of the XML + * @param[out] attribs map of attribute name and attribute value */ void parseTag(const std::string& tag, std::string& name, std::map& attribs) const; //! Reads an XML tag into a string /*! - * This function advances the input streams pointer + * This function advances the input streams pointer * - * @param attribs map of attribute name and attribute value - output - * @return Output string containing name of the XML + * @param attribs map of attribute name and attribute value - output + * @return Output string containing name of the XML */ std::string readTag(std::map& attribs); //! Return the value portion of an XML element /*! - * This function advances the input streams pointer + * This function advances the input streams pointer */ std::string readValue(); @@ -101,9 +97,9 @@ class XML_Node public: //! Constructor for XML_Node, representing a tree structure /*! - * @param nm Name of the node. - * @param parent Pointer to the parent for this node in the tree. - * A value of 0 indicates this is the top of the tree. + * @param nm Name of the node. + * @param parent Pointer to the parent for this node in the tree. + * A value of 0 indicates this is the top of the tree. */ explicit XML_Node(const std::string& nm="--", XML_Node* const parent=0); @@ -121,23 +117,25 @@ public: //! Merge an existing node as a child node to the current node /*! - * This will merge an XML_Node as a child to the current node. - * Note, this actually adds the node. Therefore, the current node is changed. - * There is no copy made of the child node. The child node should not be deleted in the future + * This will merge an XML_Node as a child to the current node. Note, this + * actually adds the node. Therefore, the current node is changed. There is + * no copy made of the child node. The child node should not be deleted in + * the future * - * @param node Reference to a child XML_Node object - * @return Returns a reference to the added child node + * @param node Reference to a child XML_Node object + * @returns a reference to the added child node */ XML_Node& mergeAsChild(XML_Node& node); - // Add a child node to the current node by making a copy of an existing node tree + // Add a child node to the current node by making a copy of an existing node + // tree /* - * This will add an XML_Node as a child to the current node. - * Note, this actually adds the node. Therefore, node is changed. - * A copy is made of the underlying tree + * This will add an XML_Node as a child to the current node. Note, this + * actually adds the node. Therefore, node is changed. A copy is made of the + * underlying tree * - * @param node Reference to a child XML_Node object - * @return returns a reference to the added node + * @param node Reference to a child XML_Node object + * @returns a reference to the added node */ XML_Node& addChild(const XML_Node& node); @@ -146,45 +144,45 @@ public: * This will add an XML_Node as a child to the current node. * The node will be blank except for the specified name. * - * @param sname Name of the new child - * @return Returns a reference to the added node + * @param sname Name of the new child + * @returns a reference to the added node */ XML_Node& addChild(const std::string& sname); - //! Add a child node to the current XML node, and at the - //! same time add a value to the child + //! Add a child node to the current XML node, and at the same time add a + //! value to the child /*! - * Resulting XML string: + * Resulting XML string: * * value * - * @param name Name of the child XML_Node object - * @param value Value of the XML_Node - string - * @return Returns a reference to the created child XML_Node object + * @param name Name of the child XML_Node object + * @param value Value of the XML_Node - string + * @returns a reference to the created child XML_Node object */ XML_Node& addChild(const std::string& name, const std::string& value); - //! Add a child node to the current XML node, and at the - //! same time add a formatted value to the child + //! Add a child node to the current XML node, and at the same time add a + //! formatted value to the child /*! - * This version supplies a formatting string (printf format) - * to the output of the value. + * This version supplies a formatting string (printf format) to the output + * of the value. * - * Resulting XML string: + * Resulting XML string: * * value * - * @param name Name of the child XML_Node object - * @param value Value of the XML_Node - double. - * @param fmt Format of the output for value - * @return Returns a reference to the created child XML_Node object + * @param name Name of the child XML_Node object + * @param value Value of the XML_Node - double. + * @param fmt Format of the output for value + * @returns a reference to the created child XML_Node object */ XML_Node& addChild(const std::string& name, const doublereal value, const std::string& fmt="%g"); //! Remove a child from this node's list of children /*! - * This function removes an XML_Node from the children of this node. + * This function removes an XML_Node from the children of this node. * * @param node Pointer to the node to be removed. Note, this node * isn't modified in any way. @@ -212,36 +210,36 @@ public: //! Return the value of an XML node as a string /*! - * This is a simple accessor routine + * This is a simple accessor routine */ std::string value() const; //! Return the value of an XML child node as a string /*! - * @param cname Name of the child node to the current - * node, for which you want the value + * @param cname Name of the child node to the current node, for which you + * want the value */ std::string value(const std::string& cname) const; //! The Overloaded parenthesis operator with one augment //! returns the value of an XML child node as a string /*! - * @param cname Name of the child node to the current - * node, for which you want the value + * @param cname Name of the child node to the current node, for which you + * want the value */ std::string operator()(const std::string& cname) const; //! Return the value of an XML node as a single double /*! - * This accesses the value string, and then tries to - * interpret it as a single double value. + * This accesses the value string, and then tries to interpret it as a + * single double value. */ doublereal fp_value() const; //! Return the value of an XML node as a single int /*! - * This accesses the value string, and then tries to - * interpret it as a single int value. + * This accesses the value string, and then tries to interpret it as a + * single int value. */ integer int_value() const; @@ -292,9 +290,9 @@ public: * an attribute with that name. * * @param attr attribute string to look up - * @return Returns a string representing the value of the attribute - * within the XML node. If there is no attribute - * with the given name, it returns the null string. + * @returns a string representing the value of the attribute within the XML + * node. If there is no attribute with the given name, it returns + * the null string. */ std::string operator[](const std::string& attr) const; @@ -305,24 +303,24 @@ public: * string. If no match is found, the empty string is returned. * * @param attr String containing the attribute to be searched for. - * @return Returns If a match is found, the attribute value is returned - * as a string. If no match is found, the empty string is + * @return If a match is found, the attribute value is returned as a + * string. If no match is found, the empty string is * returned. */ std::string attrib(const std::string& attr) const; //! Clear the current node and everything under it /*! - * The value, attributes and children are all zeroed. The name and the - * parent information is kept. + * The value, attributes and children are all zeroed. The name and the + * parent information is kept. */ void clear(); private: //! Returns a changeable value of the attributes map for the current node /*! - * Note this is a simple accessor routine. And, it is a private function. - * It's used in some internal copy and assignment routines + * Note this is a simple accessor routine. And, it is a private function. + * It's used in some internal copy and assignment routines */ std::map& attribs(); @@ -399,15 +397,15 @@ public: //! Return an unchangeable reference to the vector of children of the current node /*! - * Each of the individual XML_Node child pointers, however, - * is to a changeable XML node object. + * Each of the individual XML_Node child pointers, however, is to a + * changeable XML node object. */ const std::vector& children() const; //! Return the number of children /*! - * @param discardComments If true comments are discarded when adding up the number of children. - * Defaults to false. + * @param discardComments If true comments are discarded when adding up the + * number of children. Defaults to false. */ size_t nChildren(bool discardComments = false) const; @@ -418,10 +416,10 @@ public: //! argument, a, and that this attribute have the the string value listed //! in the second argument, v. /*! - * @param a attribute name - * @param v required value of the attribute + * @param a attribute name + * @param v required value of the attribute * - * If the condition is not true, an exception is thrown + * If the condition is not true, an exception is thrown */ void _require(const std::string& a, const std::string& v) const; @@ -434,10 +432,10 @@ public: * The ID attribute may be defaulted by setting it to "". In this case the * pointer to the first XML element matching the name only is returned. * - * @param nameTarget Name of the XML Node that is being searched for - * @param idTarget "id" attribute of the XML Node that the routine - * looks for - * @return Returns the pointer to the XML node that fits the criteria + * @param nameTarget Name of the XML Node that is being searched for + * @param idTarget "id" attribute of the XML Node that the routine + * looks for + * @returns the pointer to the XML node that fits the criteria * * @internal * This algorithm does a lateral search of first generation children @@ -453,16 +451,15 @@ public: * to the matching XML Node is returned. The search is only carried out on * the current element and the child elements of the current element. * - * The "id" attribute may be defaulted by setting it to "". - * In this case the pointer to the first XML element matching the name - * only is returned. + * The "id" attribute may be defaulted by setting it to "". In this case the + * pointer to the first XML element matching the name only is returned. * - * @param nameTarget Name of the XML Node that is being searched for - * @param idTarget "id" attribute of the XML Node that the routine - * looks for - * @param index Integer describing the index. The index is an - * attribute of the form index = "3" - * @return Returns the pointer to the XML node that fits the criteria + * @param nameTarget Name of the XML Node that is being searched for + * @param idTarget "id" attribute of the XML Node that the routine + * looks for + * @param index Integer describing the index. The index is an + * attribute of the form index = "3" + * @returns the pointer to the XML node that fits the criteria */ XML_Node* findNameIDIndex(const std::string& nameTarget, const std::string& idTarget, const int index) const; @@ -470,17 +467,15 @@ public: //! This routine carries out a recursive search for an XML node based //! on the XML element attribute, "id" /*! - * If exact match is found, the pointer - * to the matching XML Node is returned. If not, 0 is returned. + * If exact match is found, the pointer to the matching XML Node is + * returned. If not, 0 is returned. * - * The ID attribute may be defaulted by setting it to "". - * In this case the pointer to the first XML element matching the name - * only is returned. + * The ID attribute may be defaulted by setting it to "". In this case the + * pointer to the first XML element matching the name only is returned. * - * @param id "id" attribute of the XML Node that the routine - * looks for - * @param depth Depth of the search. - * @return Returns the pointer to the XML node that fits the criteria + * @param id "id" attribute of the XML Node that the routine looks for + * @param depth Depth of the search. + * @returns the pointer to the XML node that fits the criteria * * @internal * This algorithm does a lateral search of first generation children @@ -495,11 +490,11 @@ public: * the attribute, the pointer to the matching XML Node is returned. If * not, 0 is returned. * - * @param attr Attribute of the XML Node that the routine looks for - * @param val Value of the attribute - * @param depth Depth of the search. A value of 1 means that only the - * immediate children are searched. - * @return Returns the pointer to the XML node that fits the criteria + * @param attr Attribute of the XML Node that the routine looks for + * @param val Value of the attribute + * @param depth Depth of the search. A value of 1 means that only the + * immediate children are searched. + * @returns the pointer to the XML node that fits the criteria */ XML_Node* findByAttr(const std::string& attr, const std::string& val, int depth = 100000) const; @@ -507,14 +502,14 @@ public: //! This routine carries out a recursive search for an XML node based //! on the name of the node. /*! - * If exact match is found with respect to XML_Node name, the pointer - * to the matching XML Node is returned. If not, 0 is returned. - * This is the const version of the routine. + * If exact match is found with respect to XML_Node name, the pointer to the + * matching XML Node is returned. If not, 0 is returned. This is the const + * version of the routine. * - * @param nm Name of the XML node - * @param depth Depth of the search. A value of 1 means that only the - * immediate children are searched. - * @return Returns the pointer to the XML node that fits the criteria + * @param nm Name of the XML node + * @param depth Depth of the search. A value of 1 means that only the + * immediate children are searched. + * @returns the pointer to the XML node that fits the criteria */ const XML_Node* findByName(const std::string& nm, int depth = 100000) const; @@ -528,7 +523,7 @@ public: * @param nm Name of the XML node * @param depth Depth of the search. A value of 1 means that only the * immediate children are searched. - * @return Returns the pointer to the XML node that fits the criteria + * @returns the pointer to the XML node that fits the criteria */ XML_Node* findByName(const std::string& nm, int depth = 100000); @@ -540,18 +535,19 @@ public: */ std::vector getChildren(const std::string& name) const; - //! Return a changeable reference to a child of the current node, named by the argument + //! Return a changeable reference to a child of the current node, named by + //! the argument /*! - * Note the underlying data allows for more than one XML element with the same name. - * This routine returns the first child with the given name. + * Note the underlying data allows for more than one XML element with the + * same name. This routine returns the first child with the given name. * - * @param loc Name of the child to return + * @param loc Name of the child to return */ XML_Node& child(const std::string& loc) const; //! Write the header to the XML file to the specified ostream /*! - * @param s ostream to write the output to + * @param s ostream to write the output to */ void writeHeader(std::ostream& s); @@ -561,55 +557,52 @@ public: * is add an endl on to the output stream. write_int() is fine, but the * last endl wasn't being written. * - * @param s ostream to write to - * @param level Indentation level to work from - * @param numRecursivesAllowed Number of recursive calls allowed + * @param s ostream to write to + * @param level Indentation level to work from + * @param numRecursivesAllowed Number of recursive calls allowed */ void write(std::ostream& s, const int level = 0, int numRecursivesAllowed = 60000) const; //! Return the root of the current XML_Node tree /*! - * Returns a reference to the root of the current XML tree + * Returns a reference to the root of the current XML tree */ XML_Node& root() const; //! Set the root XML_Node value within the current node /*! - * @param root Value of the root XML_Node. + * @param root Value of the root XML_Node. */ void setRoot(const XML_Node& root); //! Main routine to create an tree-like representation of an XML file /*! - * Given an input stream, this routine will read matched XML tags - * representing the ctml file until an EOF is read from the file. - * This routine is called by the root XML_Node object. + * Given an input stream, this routine will read matched XML tags + * representing the ctml file until an EOF is read from the file. This + * routine is called by the root XML_Node object. * * @param f Input stream containing the ascii input file */ void build(std::istream& f); - //! Copy all of the information in the current XML_Node tree - //! into the destination XML_Node tree, doing a union operation as - //! we go + //! Copy all of the information in the current XML_Node tree into the + //! destination XML_Node tree, doing a union operation as we go /*! - * Note this is a const function because the current XML_Node and - * its children isn't altered by this operation. - * copyUnion() doesn't duplicate existing entries in the - * destination XML_Node tree. + * Note this is a const function because the current XML_Node and its + * children isn't altered by this operation. copyUnion() doesn't duplicate + * existing entries in the destination XML_Node tree. * - * @param node_dest This is the XML node to receive the information + * @param node_dest This is the XML node to receive the information */ void copyUnion(XML_Node* const node_dest) const; - //! Copy all of the information in the current XML_Node tree - //! into the destination XML_Node tree, doing a complete copy - //! as we go. + //! Copy all of the information in the current XML_Node tree into the + //! destination XML_Node tree, doing a complete copy as we go. /*! - * Note this is a const function because the current XML_Node and - * its children isn't altered by this operation. + * Note this is a const function because the current XML_Node and its + * children isn't altered by this operation. * - * @param node_dest This is the XML node to receive the information + * @param node_dest This is the XML node to receive the information */ void copy(XML_Node* const node_dest) const; @@ -622,48 +615,48 @@ public: private: //! Write an XML subtree to an output stream. /*! - * This is the main recursive routine. It doesn't put a final endl - * on. This is fixed up in the public method. A method to only write out a limited + * This is the main recursive routine. It doesn't put a final endl on. This + * is fixed up in the public method. A method to only write out a limited * amount of the XML tree has been added. * - * @param s ostream to write to - * @param level Indentation level to work from - * @param numRecursivesAllowed Number of recursive calls allowed + * @param s ostream to write to + * @param level Indentation level to work from + * @param numRecursivesAllowed Number of recursive calls allowed */ void write_int(std::ostream& s, int level = 0, int numRecursivesAllowed = 60000) const; protected: //! XML node name of the node. /*! - * For example, if we were in the XML_Node where + * For example, if we were in the XML_Node where * * * * - * Then, this string would be equal to "phase". "dim" and "id" - * are attributes of the XML_Node. + * Then, this string would be equal to "phase". "dim" and "id" are + * attributes of the XML_Node. */ std::string m_name; //! Value of the XML node /*! - * This is the string contents of the XML node. For - * example. The XML node named eps: + * This is the string contents of the XML node. For example. The XML node + * named eps: * * * valueString * * - * has a m_value string containing "valueString". + * has a m_value string containing "valueString". */ std::string m_value; //! Map containing an index between the node name and the //! pointer to the node /*! - * m_childindex[node.name()] = XML_Node *pointer + * m_childindex[node.name()] = XML_Node *pointer * - * This object helps to speed up searches. + * This object helps to speed up searches. */ std::multimap m_childindex; @@ -687,8 +680,8 @@ protected: //! Lock for this node /*! - * Currently, unimplemented functionality. If locked, - * it means you can't delete this node. + * Currently, unimplemented functionality. If locked, + * it means you can't delete this node. */ bool m_locked; @@ -711,9 +704,8 @@ protected: * * @param root Starting XML_Node* pointer for the search * @param phaseName Name of the phase to search for - * - * @return Returns the XML_Node pointer if the phase is found. - * If the phase is not found, it returns 0 + * @returns the XML_Node pointer if the phase is found. If the phase is not + * found, it returns 0 */ XML_Node* findXMLPhase(XML_Node* root, const std::string& phaseName); diff --git a/src/base/application.cpp b/src/base/application.cpp index 9845f593c..8a0667f3b 100644 --- a/src/base/application.cpp +++ b/src/base/application.cpp @@ -198,10 +198,9 @@ XML_Node* Application::get_XML_File(const std::string& file, int debug) return cache.first; } } - /* - * Check whether or not the file is XML (based on the file extension). If - * not, it will be first processed with the preprocessor. - */ + + // Check whether or not the file is XML (based on the file extension). If + // not, it will be first processed with the preprocessor. string::size_type idot = path.rfind('.'); string ext; if (idot != string::npos) { @@ -407,10 +406,9 @@ void Application::setDefaultDirectories() dirs.push_back(s.substr(start,end)); } - // CANTERA_DATA is defined in file config.h. This file is written - // during the build process (unix), and points to the directory - // specified by the 'prefix' option to 'configure', or else to - // /usr/local/cantera. + // CANTERA_DATA is defined in file config.h. This file is written during the + // build process (unix), and points to the directory specified by the + // 'prefix' option to 'configure', or else to /usr/local/cantera. #ifdef CANTERA_DATA string datadir = string(CANTERA_DATA); dirs.push_back(datadir); diff --git a/src/base/application.h b/src/base/application.h index 176e74583..1033d0454 100644 --- a/src/base/application.h +++ b/src/base/application.h @@ -16,22 +16,21 @@ class XML_Node; /*! * @defgroup globalData Global Data * - * Global data are available anywhere. There are two kinds. - * Cantera has an assortment of constant values for physical parameters. - * Also, Cantera maintains a collection of global data which is specific - * to each process that invokes Cantera functions. This process-specific - * data is stored in the class Application. + * Global data are available anywhere. There are two kinds. Cantera has an + * assortment of constant values for physical parameters. Also, Cantera + * maintains a collection of global data which is specific to each process that + * invokes Cantera functions. This process-specific data is stored in the class + * Application. */ //! Class to hold global data. /*! - * Class Application is the top-level - * class that stores data that should persist for the duration of - * the process. The class should not be instantiated directly; - * instead, it is instantiated as needed by the functions declared - * here. At most one instance is created, and it is not destroyed - * until the process terminates. + * Class Application is the top-level class that stores data that should persist + * for the duration of the process. The class should not be instantiated + * directly; instead, it is instantiated as needed by the functions declared + * here. At most one instance is created, and it is not destroyed until the + * process terminates. * * @ingroup textlogs * @ingroup globalData @@ -43,10 +42,6 @@ protected: class Messages { public: - //! Constructor for the Messages class - /*! Constructor for the Messages class which is a subclass - * of the Application class. - */ Messages(); Messages(const Messages& r); @@ -104,11 +99,10 @@ protected: //! Prints all of the error messages using writelog /*! - * Print all of the error messages using function writelog. - * Cantera saves a stack of exceptions that it - * has caught in the Application class. This routine writes - * out all of the error messages - * and then clears them from internal storage. + * Print all of the error messages using function writelog. Cantera + * saves a stack of exceptions that it has caught in the Application + * class. This routine writes out all of the error messages and then + * clears them from internal storage. * * @ingroup errorhandling */ @@ -134,8 +128,8 @@ protected: //! Install a logger. /*! - * Called by the language interfaces to install an appropriate logger. - * The logger is used for the writelog() function + * Called by the language interfaces to install an appropriate logger. + * The logger is used for the writelog() function * * @param logwriter Pointer to a logger object * @see Logger. @@ -167,7 +161,7 @@ protected: //! Provide a pointer dereferencing overloaded operator /*! - * @return returns a pointer to Messages + * @returns a pointer to Messages */ Messages* operator->(); @@ -243,26 +237,25 @@ public: //! Find an input file. /*! - * This routine will search for a file in the default locations specified - * for the application. See the routine setDefaultDirectories() listed - * above. + * This routine will search for a file in the default locations specified + * for the application. See the routine setDefaultDirectories() listed + * above. * - * The default set of directories specified for the application will be - * searched if a '/' or an '\\' is found in the name. If either is found - * then a relative path name is presumed, and the default directories are - * not searched. + * The default set of directories specified for the application will be + * searched if a '/' or an '\\' is found in the name. If either is found + * then a relative path name is presumed, and the default directories are + * not searched. * - * The presence of the file is determined by whether the file can be - * opened for reading by the current user. + * The presence of the file is determined by whether the file can be + * opened for reading by the current user. * - * @param name Name of the input file to be searched for + * @param name Name of the input file to be searched for + * @return The absolute path name of the first matching file is + * returned. If a relative path name is indicated, the relative path + * name is returned. * - * @return The absolute path name of the first matching file is - * returned. If a relative path name is indicated, the relative path - * name is returned. - * - * If the file is not found, a message is written to stdout and a - * CanteraError exception is thrown. + * If the file is not found, a message is written to stdout and a + * CanteraError exception is thrown. * * @ingroup inputfiles */ @@ -270,10 +263,9 @@ public: //! Return a pointer to the XML tree for a Cantera input file. /*! - * This routine will find the file and read the XML file into an - * XML tree structure. Then, a pointer will be returned. If the - * file has already been processed, then just the pointer will - * be returned. + * This routine will find the file and read the XML file into an XML tree + * structure. Then, a pointer will be returned. If the file has already been + * processed, then just the pointer will be returned. * * @param file String containing the relative or absolute file name * @param debug Debug flag @@ -282,12 +274,12 @@ public: //! Read a CTI or CTML string and fill up an XML tree. /*! - * Return a pointer to the XML tree corresponding to the specified - * CTI or XML string. If the given string has been processed before, - * the cached XML tree will be returned. Otherwise, the XML tree - * will be generated and stored in the cache. - * @param text CTI or CTML string - * @return Root of the corresponding XML tree + * Return a pointer to the XML tree corresponding to the specified CTI or + * XML string. If the given string has been processed before, the cached XML + * tree will be returned. Otherwise, the XML tree will be generated and + * stored in the cache. + * @param text CTI or CTML string + * @return Root of the corresponding XML tree */ XML_Node* get_XML_from_string(const std::string& text); @@ -376,7 +368,8 @@ protected: //! The second element of the value is used to store the last-modified time //! for the file, to enable change detection. std::map > xmlfiles; - //! Vector of deprecation warnings that have been emitted (to suppress duplicates) + //! Vector of deprecation warnings that have been emitted (to suppress + //! duplicates) std::set warnings; bool m_suppress_deprecation_warnings; diff --git a/src/base/ct2ctml.cpp b/src/base/ct2ctml.cpp index aac470034..70e34c3e2 100644 --- a/src/base/ct2ctml.cpp +++ b/src/base/ct2ctml.cpp @@ -27,16 +27,14 @@ namespace Cantera * Use the environment variable PYTHON_CMD if it is set. If not, return * the string 'python'. * - * Note, there are hidden problems here that really direct us to use - * a full pathname for the location of python. Basically the system - * call will use the shell /bin/sh, in order to launch python. - * This default shell may not be the shell that the user is employing. - * Therefore, the default path to python may be different during - * a system call than during the default user shell environment. - * This is quite a headache. The answer is to always set the - * PYTHON_CMD environmental variable in the user environment to - * an absolute path to locate the python executable. Then this - * issue goes away. + * Note, there are hidden problems here that really direct us to use a full + * pathname for the location of python. Basically the system call will use the + * shell /bin/sh, in order to launch python. This default shell may not be the + * shell that the user is employing. Therefore, the default path to python may + * be different during a system call than during the default user shell + * environment. This is quite a headache. The answer is to always set the + * PYTHON_CMD environmental variable in the user environment to an absolute path + * to locate the python executable. Then this issue goes away. */ static string pypath() { @@ -88,10 +86,8 @@ static std::string call_ctml_writer(const std::string& text, bool isfile) } #ifdef HAS_NO_PYTHON - /* - * Section to bomb out if python is not - * present in the computation environment. - */ + //! Section to bomb out if python is not present in the computation + //! environment. throw CanteraError("ct2ctml", "python cti to ctml conversion requested for file, " + file + ", but not available in this computational environment"); @@ -189,10 +185,8 @@ void ck2cti(const std::string& in_file, const std::string& thermo_file, const std::string& transport_file, const std::string& id_tag) { #ifdef HAS_NO_PYTHON - /* - * Section to bomb out if python is not - * present in the computation environment. - */ + //! Section to bomb out if python is not present in the computation + //! environment. string ppath = in_file; throw CanteraError("ct2ctml", "python ck to cti conversion requested for file, " + ppath + diff --git a/src/base/ctml.cpp b/src/base/ctml.cpp index db868ffcb..1536b8ba1 100644 --- a/src/base/ctml.cpp +++ b/src/base/ctml.cpp @@ -101,10 +101,10 @@ void addNamedFloatArray(XML_Node& node, const std::string& name, const size_t n, if (type != "") { f.addAttribute("type",type); } - /* - * Add vtype, which indicates the type of the value. Here we specify it as a list of floats separated - * by commas, with a length given by size attribute. - */ + + // Add vtype, which indicates the type of the value. Here we specify it as a + // list of floats separated by commas, with a length given by size + // attribute. f.addAttribute("vtype", "floatArray"); f.addAttribute("size", n); @@ -324,9 +324,8 @@ size_t getFloatArray(const XML_Node& node, vector_fp & v, v.clear(); doublereal vmin = Undef, vmax = Undef; doublereal funit = 1.0; - /* - * Get the attributes field, units, from the XML node - */ + + // Get the attributes field, units, from the XML node std::string units = readNode->attrib("units"); if (units != "" && convert) { if (unitsString == "actEnergy" && units != "") { @@ -351,14 +350,10 @@ size_t getFloatArray(const XML_Node& node, vector_fp & v, val = val.substr(icom+1,val.size()); v.push_back(fpValueCheck(numstr)); } else { - /* - * This little bit of code is to allow for the - * possibility of a comma being the last - * item in the value text. This was allowed in - * previous versions of Cantera, even though it - * would appear to be odd. So, we keep the - * possibility in for backwards compatibility. - */ + // This little bit of code is to allow for the possibility of a + // comma being the last item in the value text. This was allowed in + // previous versions of Cantera, even though it would appear to be + // odd. So, we keep the possibility in for backwards compatibility. if (!val.empty()) { v.push_back(fpValueCheck(val)); } @@ -429,10 +424,8 @@ void getMatrixValues(const XML_Node& node, "nrow != ncol for a symmetric matrix"); } - /* - * Get the attributes field, units, from the XML node - * and determine the conversion factor, funit. - */ + // Get the attributes field, units, from the XML node and determine the + // conversion factor, funit. doublereal funit = 1.0; if (convert && node["units"] != "") { funit = toSI(node["units"]); @@ -470,9 +463,8 @@ void getMatrixValues(const XML_Node& node, + key2); } double dval = fpValueCheck(rmm.substr(icolon+1, rmm.size())) * funit; - /* - * Finally, insert the value; - */ + + // Finally, insert the value; retnValues(irow, icol) = dval; if (matrixSymmetric) { retnValues(icol, irow) = dval; diff --git a/src/base/global.cpp b/src/base/global.cpp index ab5eeb4ce..b5e39feb7 100644 --- a/src/base/global.cpp +++ b/src/base/global.cpp @@ -169,8 +169,10 @@ string canteraRoot() //! split a string at a '#' sign. Used to separate a file name from an id string. /*! * @param src Original string to be split up. This is unchanged. - * @param file Output string representing the first part of the string, which is the filename. - * @param id Output string representing the last part of the string, which is the id. + * @param file Output string representing the first part of the string, + * which is the filename. + * @param id Output string representing the last part of the string, + * which is the id. */ static void split_at_pound(const std::string& src, std::string& file, std::string& id) { diff --git a/src/base/units.h b/src/base/units.h index e0a18af14..636cf7f99 100644 --- a/src/base/units.h +++ b/src/base/units.h @@ -61,11 +61,10 @@ public: } /** - * Return the multiplier required to convert a dimensional quantity - * with units specified by string 'units' to SI units. - * The list of recognized units is stored as a stl map - * called m_u[] and m_act_u for activity - * coefficients. These maps are initialized with likely values. + * Return the multiplier required to convert a dimensional quantity with + * units specified by string 'units' to SI units. The list of recognized + * units is stored as a stl map called m_u[] and m_act_u + * for activity coefficients. These maps are initialized with likely values. * * @param units_ String containing the units description */ diff --git a/src/base/xml.cpp b/src/base/xml.cpp index 2a1b8f343..8199dbcb2 100644 --- a/src/base/xml.cpp +++ b/src/base/xml.cpp @@ -25,9 +25,8 @@ class XML_Error : public CanteraError protected: //! Constructor /*! - * 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. + * 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 line Number number where the error occurred. */ @@ -64,11 +63,11 @@ class XML_TagMismatch : public XML_Error public: //! Constructor /*! - * An XML element must have the same opening and closing name. + * An XML element must have the same opening and closing name. * - * @param opentag String representing the opening of the XML bracket - * @param closetag String representing the closing of the XML bracket - * @param line Line number where the error occurred. + * @param opentag String representing the opening of the XML bracket + * @param closetag String representing the closing of the XML bracket + * @param line Line number where the error occurred. */ XML_TagMismatch(const std::string& opentag, const std::string& closetag, int line=0) : @@ -90,12 +89,12 @@ class XML_NoChild : public XML_Error public: //! Constructor /*! - * An XML element doesn't have the required child node + * 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 child Name of the required child node - * @param line Line number where the error occurred. + * @param p XML_Node to write a string error message + * @param parent Namf of the parent node + * @param child Name of the required child node + * @param line Line number where the error occurred. */ XML_NoChild(const XML_Node* p, const std::string& parent, std::string child, int line=0) : @@ -186,14 +185,12 @@ int XML_Reader::findQuotedString(const std::string& s, std::string& rstring) con if (iloc1 == string::npos) { return 0; } - /* - * Define the return string by the two endpoints. - * Strip the surrounding quotes as well - */ + + // Define the return string by the two endpoints. Strip the surrounding + // quotes as well rstring = s.substr(ilocStart + 1, iloc1 - 1); - /* - * Return the first character position past the quotes - */ + + // Return the first character position past the quotes return static_cast(iloc1)+1; } @@ -915,11 +912,9 @@ void XML_Node::write_int(std::ostream& s, int level, int numRecursivesAllowed) c string indent(level, ' '); if (m_iscomment) { - /* - * In the comment section, we test to see if there - * already is a space beginning and ending the comment. - * If there already is one, we don't add another one. - */ + // In the comment section, we test to see if there already is a space + // beginning and ending the comment. If there already is one, we don't + // add another one. s << endl << indent << "