From 2dc2b214239a33c8f93c1cb6d5620f922f28cf88 Mon Sep 17 00:00:00 2001 From: Harry Moffat Date: Tue, 6 Jan 2009 21:30:08 +0000 Subject: [PATCH] doxygen update - eliminated warnings --- Cantera/src/base/xml.cpp | 79 ++++++++++++++++++++++++++++++++++------ Cantera/src/base/xml.h | 44 ++++++++++++++-------- 2 files changed, 96 insertions(+), 27 deletions(-) diff --git a/Cantera/src/base/xml.cpp b/Cantera/src/base/xml.cpp index 430c1532e..39fd774e2 100755 --- a/Cantera/src/base/xml.cpp +++ b/Cantera/src/base/xml.cpp @@ -12,7 +12,6 @@ // Copyright 2001 California Institute of Technology -// simple xml functions // turn off warnings under Windows #ifdef WIN32 @@ -41,9 +40,13 @@ namespace Cantera { //! Classs representing a generic XML error condition class XML_Error : public CanteraError { - public: + 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. */ XML_Error(int line=0) : @@ -54,31 +57,66 @@ namespace Cantera { m_msg += " at line " + int2str(line+1); } m_msg += ".\n"; - //setError("XML_Error",m_msg); } + //! destructor virtual ~XML_Error() {} + protected: //! Line number of the file int m_line; + //! String message for the error std::string m_msg; }; + //! Class representing a specific type of XML file formatting error + /*! + * An XML tag is not matched + */ class XML_TagMismatch : public XML_Error { public: - XML_TagMismatch(string opentag, string closetag, - int line=0) : XML_Error(line) { + + //! Constructor + /*! + * 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. + */ + XML_TagMismatch(std::string opentag, std::string closetag, + int line=0) : + XML_Error(line) + { m_msg += "<" + opentag + "> paired with .\n"; - setError("XML_TagMismatch",m_msg); + setError("XML_TagMismatch", m_msg); } + + //! Destructor virtual ~XML_TagMismatch() {} }; + //! Class representing a specific type of XML file formatting error + /*! + * An XML_Node doesn't have a required child node + */ class XML_NoChild : public XML_Error { public: - XML_NoChild(const XML_Node* p, string parent, - string child, int line=0) : XML_Error(line) { + + //! Constructor + /*! + * 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. + */ + XML_NoChild(const XML_Node* p, std::string parent, + std::string child, int line=0) : + XML_Error(line) + { m_msg += " The XML Node \"" + parent + "\", does not contain a required\n" + " XML child node named \"" @@ -88,18 +126,37 @@ namespace Cantera { p->write(ss,1); m_msg += ss.str() + "\n"; #endif - setError("XML_NoChild",m_msg); + setError("XML_NoChild", m_msg); } + + //! Destructor virtual ~XML_NoChild() {} }; + //! Class representing a specific type of XML file formatting error + /*! + * An XML_Node's units attribute has the wrong type of units. + */ class XML_IllegalUnits : public XML_Error { public: - XML_IllegalUnits(string name, string units, int line=0) : XML_Error(line) { + + //! Constructor + /*! + * Wrong units string. + * + * @param name Name of the current XML node + * @param units Units string in the "units" attribute + * @param line Line number where the error occurred. + */ + XML_IllegalUnits(std::string name, std::string units, int line=0) : + XML_Error(line) + { m_msg += "Illegal units (" + units + ") specified for node " + name + ".\n"; - setError("XML_IllegalUnits",m_msg); + setError("XML_IllegalUnits", m_msg); } + + //! Destructor virtual ~XML_IllegalUnits() {} }; diff --git a/Cantera/src/base/xml.h b/Cantera/src/base/xml.h index 9b795d108..351fc32bd 100755 --- a/Cantera/src/base/xml.h +++ b/Cantera/src/base/xml.h @@ -59,7 +59,7 @@ namespace Cantera { //! space. /*! * White space is defined by the ISO C function isspace(), and - * includes tabs, spaces, \n. \r, \v, and \f. + * includes tabs, spaces, \\n. \\r, \\v, and \\f. * * @param aline Input line to be stripped * @@ -70,18 +70,31 @@ namespace Cantera { */ std::string strip(const std::string& aline) const; - /// Looks for a substring within 'aline' enclosed in double - /// quotes, and returns this substring (without the quotes) if - /// found. If not, an empty string is returned. - /// @todo why is this a class method? + //! Looks for a substring within 'aline' enclosed in double + //! quotes, and returns this substring (without the quotes) if + //! found. If not, an empty string is returned. + /*! + * + * @param aline This is the input string to be searched + * + * @todo why is this a class method? + */ std::string inquotes(const std::string& aline) const; - - /** - * Searches a string for the first occurrence of a valid - * quoted string. Quotes can start with either a single + + //! 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, '\\'. + * + * @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. */ int findQuotedString(const std::string& aline, std::string &rstring) const; @@ -206,7 +219,7 @@ namespace Cantera { //! same time add a value to the child /*! * Resulting XML string: - * value + * \ value \ * * @param name Name of the child XML_Node object * @param value Value of the XML_Node - string @@ -221,7 +234,7 @@ namespace Cantera { * to the output of the value. * * Resulting XML string: - * value + * \ value \ * * @param name Name of the child XML_Node object * @param value Value of the XML_Node - double. @@ -285,7 +298,7 @@ namespace Cantera { * @param cname Name of the child node to the current * node, for which you want the value */ - std::string operator()(std::string loc) const; + std::string operator()(std::string cname) const; //! Return the value of an XML node as a single double /*! @@ -427,10 +440,9 @@ namespace Cantera { //! Return an unchangeable reference to the vector of children of the current node /*! - * Each of the individual XML_Node child pointers, however, + * Each of the individual XML_Node child pointers, however, * is to a changeable xml node object. * - * @param n Number of the child to return */ const std::vector& children() const; @@ -668,9 +680,9 @@ namespace Cantera { * This is the string contents of the XML node. For * example. The xml node named eps: * - * + * \ * valueString - * + * \ * * has a m_value string containing "valueString". */