Thread: [xml-cppdom-checkins] SF.net SVN: xml-cppdom:[639] trunk/cppdom

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Revision: 639
          http://xml-cppdom.svn.sourceforge.net/xml-cppdom/?rev=639&view=rev
Author:   patrickh
Date:     2010-03-06 16:15:59 +0000 (Sat, 06 Mar 2010)

Log Message:
-----------
Improve Doxygen usage. No functional changes.

Modified Paths:
--------------
    trunk/cppdom/SpiritParser.h
    trunk/cppdom/cppdom.h

Modified: trunk/cppdom/SpiritParser.h
===================================================================

--- trunk/cppdom/SpiritParser.h	2010-03-06 16:03:29 UTC (rev 638)
+++ trunk/cppdom/SpiritParser.h	2010-03-06 16:15:59 UTC (rev 639)
@@ -187,11 +187,12 @@
 };
 
 /**
-* XML grammar.
-* Based on: http://www.w3.org/TR/2004/REC-xml-20040204/
-*
-* type: BUILDER_T must implement the interface concept similar to XmlBuilder above.
-*/
+ * XML grammar.
+ * Based on: http://www.w3.org/TR/2004/REC-xml-20040204/
+ *
+ * @tparam BUILDER_T must implement the interface concept similar to
+ *         XmlBuilder above.
+ */
 template<typename BUILDER_T>
 struct XmlGrammar : public grammar<XmlGrammar<BUILDER_T> >
 {
@@ -301,7 +302,8 @@
 };
 
 
-/** The actual parser class that we will use.
+/**
+ * The actual parser class that we will use.
  *
  * Provides a simple interface for using the builder and grammar.
  */

Modified: trunk/cppdom/cppdom.h
===================================================================
--- trunk/cppdom/cppdom.h	2010-03-06 16:03:29 UTC (rev 638)
+++ trunk/cppdom/cppdom.h	2010-03-06 16:15:59 UTC (rev 639)
@@ -115,27 +115,29 @@
 //! namespace of the cppdom project
 namespace cppdom
 {
-   // Declare a version string constant that can be used at run time.
+   /** Declare a version string constant that can be used at run time. */
    CPPDOM_EXPORT(const char*) getVersion();
 
-   // Helper methods
+   /** Helper methods. */
    template <class T> inline void ignore_unused_variable_warning(const T&) { }
 
-   // True if there are characters references: ex: &amp;
+   /** True if there are characters references: ex: &amp; */
    CPPDOM_EXPORT(bool) textContainsXmlEscaping(const std::string& data);
 
-   // True if there are chars needing escaping
+   /** True if there are chars needing escaping. */
    CPPDOM_EXPORT(bool) textNeedsXmlEscaping(const std::string& data, bool isCdata);
 
-    // Remove escaping from xml text
+   /** Removes escaping from XML text. */
    CPPDOM_EXPORT(std::string) removeXmlEscaping(const std::string& data, bool isCdata);
 
-   // Add escaping to xml text
+   /** Adds escaping to XML text. */
    CPPDOM_EXPORT(std::string) addXmlEscaping(const std::string& data, bool isCdata);
 
-   /** Method to split string base on seperator.
+   /**
+    * Method to split string base on seperator.
     *
-    * If separator does not exist in string, then just return that string in the output.
+    * If separator does not exist in string, then just return that string in
+    * the output.
     *
     * @example:
     *    std::string s = "apple, orange, cherry, peach, grapefruit, cantalope,watermelon";
@@ -159,7 +161,7 @@
       }
    }
 
-   //! xml parsing error codes enumeration
+   /** XML parsing error codes enumeration */
    enum ErrorCode
    {
       xml_unknown = 0,              /**< unspecified or unknown error */
@@ -175,7 +177,7 @@
       xml_attr_value_expected,      /**< expected value after an '=' in attribute */
       xml_save_invalid_nodetype,    /**< invalid nodetype encountered while saving */
 
-      xml_invalid_operation,        /**< Attempted to execute an xml operation that would cause invalid structure */
+      xml_invalid_operation,        /**< Attempted to execute an XML operation that would cause invalid structure */
       xml_invalid_argument,         /**< Attempted to pass an invalid argument */
    // added by kevin for 0.7 compatibility...
       xml_filename_invalid,
@@ -185,7 +187,8 @@
       xml_dummy                     /**< dummy error code */
    };
    
-   // typedefs
+   /** @name Typedefs */
+   //@{
    /** smart pointer to node */
    class Node;
    typedef cppdom_boost::shared_ptr<cppdom::Node> NodePtr;
@@ -197,34 +200,34 @@
    /** list of node smart pointer */
    typedef std::vector<NodePtr> NodeList;
    typedef NodeList::iterator NodeListIterator;
+   //@}
 
-
    // classes
 
    /**
-    * xml error class
-    * contains an ErrorCode and is thrown while parsing xml input
+    * XML error class.
+    * Contains an ErrorCode and is thrown while parsing XML input.
     */
    class CPPDOM_CLASS Error : public std::exception
    {
    public:
-      /** constructor */
+      /** Constructor. */
       Error(ErrorCode code, std::string localDesc, std::string location);
 
-      /** constructor that can take line num */
+      /** Constructor that can take line number. */
       Error(ErrorCode code, std::string localDesc, std::string file, unsigned line_num);
 
-      /** returns the error code */
+      /** Returns the error code. */
       ErrorCode getError() const;
 
       virtual ~Error() throw();
 
-      /** returns the string representation of the error code */
+      /** Returns the string representation of the error code. */
       std::string getStrError() const;
 
       std::string getString() const;
 
-      /** return additional error info */
+      /** Returns additional error info. */
       std::string getInfo() const;
 
       virtual const char* what() const throw();
@@ -237,29 +240,29 @@
 
 
    /**
-    * xml stream position
-    * represents the position in the xml input stream; usable if load()
-    *    throws an error on parsing xml content
+    * XML stream position.
+    * Represents the position in the XML input stream; usable if load()
+    * throws an error on parsing XML content.
     */
    class CPPDOM_CLASS Location
    {
    public:
-      /** Constructor */
+      /** Constructor. */
       Location();
 
-      /** returns current line */
+      /** Returns current line. */
       int getLine() const;
 
-      /** returns current position in a line */
+      /** Returns current position in a line. */
       int getPos() const;
 
-      /** advances a char */
+      /** Advances a char. */
       void step(int chars = 1);
 
-      /** indicates entering a new line */
+      /** Indicates entering a new line. */
       void newline();
 
-      /** reset location */
+      /** Resets location. */
       void reset();
 
    protected:
@@ -268,44 +271,47 @@
    };
 
 
-   // typedefs
-   /** smart pointer for Context */
+   /** @name Typedefs */
+   //@{
+   /** Smart pointer for Context */
    typedef cppdom_boost::shared_ptr<class Context> ContextPtr;
 
-   /** smart pointer to the event handler */
+   /** Smart pointer to the event handler */
    typedef cppdom_boost::shared_ptr<class EventHandler> EventHandlerPtr;
+   //@}
 
    /**
-    * xml parsing context class.
-    * the class is the parsing context for the parsed xml document.
-    * the class has a tagname lookup table and an entity map
+    * XML parsing context class.
+    * The class is the parsing context for the parsed XML document.
+    * The class has a tagname lookup table and an entity map.
     */
    class CPPDOM_CLASS Context
    {
    public:
-      /** ctor */
+      /** Constructor. */
       Context();
-      /** dtor */
+
+      /** Destructor. */
       virtual ~Context();
 
-      /** returns the tagname by the tagname handle */
+      /** Returns the tagname by the tagname handle. */
       std::string getTagname(TagNameHandle handle);
 
-      /** inserts a tag name and returns a tag name handle to the string */
+      /** Inserts a tag name and returns a tag name handle to the string. */
       TagNameHandle insertTagname(const std::string& tagname);
 
-      /** returns the current location in the xml stream */
+      /** Returns the current location in the XML stream. */
       Location& getLocation();
 
-      /** @name event handling methods */
+      /** @name Event Handling Methods */
       //@{
-      /** sets the event handler; enables handling events */
+      /** Sets the event handler; enables handling events. */
       void setEventHandler(EventHandlerPtr ehptr);
 
-      /** returns the currently used eventhandler (per reference) */
+      /** Returns the currently used eventhandler (per reference). */
       EventHandler& getEventHandler();
 
-      /** returns if a valid event handler is set */
+      /** Returns if a valid event handler is set. */
       bool hasEventHandler() const;
       //@}
 
@@ -322,7 +328,7 @@
 
    /**
     * XML attribute class.
-    * Just wraps a string (this is really just and attribute VALUE)
+    * Just wraps a string (this is really just and attribute VALUE).
     * This is just meant to be a "magic" class to provide some syntactic
     * sugar related to autoconversions and get<value>() usefullness.
     */
@@ -345,8 +351,9 @@
 
 #ifndef CPPDOM_NO_MEMBER_TEMPLATES
       /**
-       * Set mData to the string value of val
-       * @note Requires a stream operation of type T
+       * Set mData to the string value of val.
+       *
+       * @note Requires a stream operation of type T.
        */
       template<class T>
       void setValue(const T& val)
@@ -370,8 +377,8 @@
       // specializations, found below.
 #ifdef _MSC_VER
       /**
-       * Specialization of getValue<T> for std::string so that more than just the
-       * first word of the attribute string is returned.
+       * Specialization of getValue<T> for std::string so that more than just
+       * the first word of the attribute string is returned.
        */
       template<>
       std::string getValue<std::string>() const
@@ -381,7 +388,7 @@
 #endif // ! _MSC_VER
 #endif // ! CPPDOM_NO_MEMBER_TEMPLATES
 
-      /** Autoconversion to string (so old code should work) */
+      /** Autoconversion to string (so old code should work). */
       operator std::string() const;
 
       bool operator==(const Attribute& rhs)
@@ -446,18 +453,19 @@
    };
 
 
-   /** xml node.
-   * A node has the following properties
-   * name - The element name of the node
-   * type - The type of the node. see NodeType
-   * children - Child elements of the node
-   * cdata - the cdata content if of type cdata
-   *
-   */
+   /**
+    * XML node.
+    *
+    * A node has the following properties:
+    *   * name - The element name of the node.
+    *   * type - The type of the node. see NodeType.
+    *   * children - Child elements of the node.
+    *   * cdata - the cdata content if of type cdata.
+    */
    class CPPDOM_CLASS Node
    {
    public:
-         /** node type enumeration */
+      /** Node type enumeration */
       enum Type
       {
          xml_nt_node,      /**< normal node, can contain subnodes */
@@ -467,15 +475,16 @@
       };
 
       friend class Parser;
+
    protected:
       /** Default Constructor */
       Node();
 
    public:
-      /** constructor, takes xml context pointer */
+      /** Constructor, takes XML context pointer. */
       explicit Node(ContextPtr pctx);
 
-      /** Construct a node with a given name */
+      /** Construct a node with a given name. */
       explicit Node(std::string nodeName, ContextPtr ctx);
 
       Node(const Node& node);
@@ -492,11 +501,14 @@
       /** assign operator */
       Node& operator=(const Node& node);
 
-      /** Returns true if the nodes are equal
-      * @param ignoreAttribs - Attributes to ignore in the comparison
-      * @param ignoreElements - Elements to ignore in the comparison
-      */
-      bool isEqual(NodePtr otherNode, const std::vector<std::string>& ignoreAttribs,
+      /**
+       * Returns true if the nodes are equal.
+       *
+       * @param ignoreAttribs  Attributes to ignore in the comparison.
+       * @param ignoreElements Elements to ignore in the comparison.
+       */
+      bool isEqual(NodePtr otherNode,
+                   const std::vector<std::string>& ignoreAttribs,
                    const std::vector<std::string>& ignoreElements,
                    bool dbgit=false, const unsigned debugIndent=0);
 
@@ -506,14 +518,15 @@
          return isEqual(otherNode, empty_strings, empty_strings );
       }
 
-      /** Returns the local name of the node (the element name) */
+      /** Returns the local name of the node (the element name). */
       std::string getName();
-      /** set the node name */
+
+      /** Sets the node name. */
       void setName(const std::string& name);
 
       /** @name Type information */
       //@{
-      /** returns type of node */
+      /** Returns type of node. */
       Node::Type getType() const;
 
       bool isNode()
@@ -525,26 +538,32 @@
       bool isCData()
       { return getType() == xml_nt_cdata;}
 
-      /** sets new nodetype */
+      /** Sets new nodetype. */
       void setType(Node::Type type);
       //@}
 
       /** @name Attribute information */
       //@{
-      /** Check if the node has a given attribute */
+      /** Checks if the node has a given attribute. */
       bool hasAttribute(const std::string& name) const;
 
       /**
-       * Get the named attribute
-       * @returns empty string ("") if not found, else the value
+       * Gets the named attribute.
+       *
        * @post Object does not change.
+       *
+       * @return Empty string ("") if not found, else the value.
        */
       Attribute getAttribute(const std::string& name) const;
 
       /**
-       * sets new attribute value
-       * @param attr - Attribute name to set.  There must not be ANY spaces in this name
-       * @post Element.attr is set to value.  If it didn't exist before, now it does.
+       * Sets new attribute value.
+       *
+       * @post Element.attr is set to value. If it did not exist before, now
+       *       it does.
+       *
+       * @param attr Attribute name to set. There must not be ANY spaces in
+       *             this name.
        */
       void setAttribute(const std::string& attr, const Attribute& value);
 
@@ -572,12 +591,14 @@
       /** Direct access to attribute map. */
       const Attributes& attrib() const;
 
-      /** returns attribute map of the node
+      /**
+       * Returns attribute map of the node.
        * @deprecated
        */
       Attributes& getAttrMap();
 
-      /** returns attribute map of the node
+      /**
+       * Returns attribute map of the node.
        * @deprecated
        */
       const Attributes& getAttrMap() const;
@@ -586,17 +607,24 @@
 
       /** @name Children and parents */
       //@{
-      /** Returns true if the node has a child of the given name.
-       * @param name    Name can be a single element name or a chain of the form "tag/tag/tag"
+      /**
+       * Returns true if the node has a child of the given name.
+       *
+       * @param name Name can be a single element name or a chain of the form
+       *             "tag/tag/tag".
        */
       bool hasChild(const std::string& name);
 
-      /** Returns the first child of the given local name.
+      /**
+       * Returns the first child of the given local name.
        */
       NodePtr getChild(const std::string& name);
 
-      /** Return first child of the given name.
-       * @param name    Name can be a single element name or a chain of the form "tag/tag/tag"
+      /**
+       * Return first child of the given name.
+       *
+       * @param name Name can be a single element name or a chain of the form
+       *             "tag/tag/tag".
        */
       NodePtr getChildPath(const std::string& path);
 
@@ -604,27 +632,32 @@
       NodeList& getChildren();
 
       /**
-       * Returns a list of all children (one level deep) with local name of childName
-       * \note currently no path-like childname can be passed, like in e.g. msxml
-       * If has standard compose() functions, could impl this by calling getChildren(pred)
+       * Returns a list of all children (one level deep) with local name of
+       * childName.
+       *
+       * @note Currently no path-like childname can be passed, such as in
+       *       MSXML. If has standard compose() functions, could impl this by
+       *       calling getChildren(pred).
        */
       NodeList getChildren(const std::string& name);
 
       /**
        * Returns list of all children.
+       *
        * @see getChildren
-       * @note Needed because of predicate template matching char*
+       * @note Needed because of predicate template matching char*.
        */
       NodeList getChildren(const char* name);
 
-      /** Return a list of children that pass the given STL predicate */
+      /** Return a list of children that pass the given STL predicate. */
       template<class Predicate>
       NodeList getChildrenPred(Predicate pred)
       {
          NodeList result(0);
          NodeList::const_iterator iter;
 
-         // search for all occurances of nodename and insert them into the new list
+         // search for all occurances of nodename and insert them into the new
+         // list.
          for(iter = mNodeList.begin(); iter != mNodeList.end(); ++iter)
          {
             if (pred(*iter))
@@ -657,40 +690,47 @@
       /** @name CData methods */
       //@{
       /**
-       * returns cdata string
-       * @note: For node type "cdata", this returns the local cdata.
-       *        For other nodes, this attempts to find the first child cdata
-       *        node and returns its data.
+       * Returns CDATA string.
+       *
+       * @note For node type "cdata", this returns the local cdata.
+       *       For other nodes, this attempts to find the first child cdata
+       *       node and returns its data.
        */
       std::string getCdata();
 
       /**
-       * Returns the full cdata of the node or immediate children.
-      * @note: For node type "cdata", this returns the local cdata.
-      *        For other nodes, combines the cdata of all cdata children.
-      */
+       * Returns the full CDATA of the node or immediate children.
+       *
+       * @note For node type "cdata", this returns the local cdata.
+       *       For other nodes, combines the cdata of all cdata children.
+       */
       std::string getFullCdata();
 
-      /** Sets the node cdata.
-      * @post For cdata type nodes, this sets the contained cdata
-      *       For other types, this sets the cdata of the first cdata node.
-      *       If none exists, then one is created called "cdata".
-      */
+      /**
+       * Sets the node CDATA.
+       *
+       * @post For CDATA type nodes, this sets the contained cdata
+       *       For other types, this sets the cdata of the first cdata node.
+       *       If none exists, then one is created called "cdata".
+       */
       void setCdata(const std::string& cdata);
       //@}
 
 
-      /** @name load/save functions */
+      /** @name Load/Save Functions */
       //@{
-      /** loads xml node from input stream */
+      /** Loads XML node from input stream. */
       void load(std::istream& in, ContextPtr& context);
 
-      /** saves node to xml output stream
-      * @param indent - The amount to indent
-      * @doIndent - If true, then indent the output
-      * @doNewline - If true then use newlines in output
-      */
-      void save(std::ostream& out, int indent=0, bool doIndent=true, bool doNewline=true);
+      /** 
+       * Saves node to xml output stream.
+       *
+       * @param indent    The amount to indent.
+       * @param doIndent  If true, then indent the output.
+       * @param doNewline If true then use newlines in output.
+       */
+      void save(std::ostream& out, int indent = 0, bool doIndent = true,
+                bool doNewline = true);
       //@}
 
       /** Returns the context used for this node. */
@@ -711,15 +751,15 @@
    };
 
 
-   /** XML document root node.
+   /**
+    * XML document root node.
     *
-    * Structure of a cppdom document
+    * Structure of a cppdom document:
     *
     * Nested tree of nodes.  Each node has a type (Node::Type).
     * Root node is of type document.  Standard nodes are type node.
     * Under standard nodes there can be cdata nodes.  These nodes are nodes
     * for containing the raw text inside an element.
-    *
     */
    class CPPDOM_CLASS Document: public Node
    {
@@ -729,36 +769,43 @@
 
       ~Document();
 
-      /** constructor taking xml context pointer */
+      /** Constructor taking XML context pointer. */
       explicit Document(ContextPtr context);
 
-      /** constructor taking xml context pointer */
+      /** Constructor taking XML context pointer. */
       explicit Document(std::string docName, ContextPtr context);
 
-      /** returns a list of processing instruction nodes */
+      /** Returns a list of processing instruction nodes. */
       NodeList& getPiList();
 
-      /** returns a list of document type definition rules to check the xml file */
+      /**
+       * Returns a list of document type definition rules to check the XML
+       * file.
+       */
       NodeList& getDtdList();
 
-      /** loads xml Document (node) from input stream */
+      /** Loads XML Document (node) from input stream. */
       void load(std::istream& in, ContextPtr& context);
 
-      /** saves node to xml output stream
-      * @param doIndent - If true, then indent the output.
-      * @param doNewline - If true, then use newlines in the output.
-      */
+      /**
+       * Saves node to xml output stream.
+       *
+       * @param doIndent  If true, then indent the output.
+       * @param doNewline If true, then use newlines in the output.
+       */
       void save(std::ostream& out, bool doIndent=true, bool doNewline=true);
 
       /**
-       * \exception throws cppdom::Error when the file name is invalid.
+       * @throw cppdom::Error Thrown when the file name is invalid.
        */
       void loadFile(const std::string& filename) throw(Error);
       void loadFileChecked(const std::string& filename);
 
-      /** Save the document to the given filename.
-      * @todo Fix this method.  It doesn't work
-      */
+      /**
+       * Saves the document to the given filename.
+       *
+       * @todo Fix this method.  It doesn't work
+       */
       void saveFile(std::string filename);
 
 
@@ -770,37 +817,39 @@
       NodeList mDtdRules;
    };
 
-   /** Interface for xml parsing event handler */
+   /** Interface for XML parsing event handler. */
    class CPPDOM_CLASS EventHandler
    {
    public:
-      /** ctor */
+      /** Constructor. */
       EventHandler() {}
 
-      /** virtual dtor */
+      /** Destructor. */
       virtual ~EventHandler() {}
 
-      /** called when parsing of an xml document starts */
+      /** Called when parsing of an xml document starts. */
       virtual void startDocument() {}
 
-      /** called when ended parsing a document */
+      /** Called when ended parsing a document. */
       virtual void endDocument() {}
 
-      /** called when parsing a processing instruction */
+      /** Called when parsing a processing instruction. */
       virtual void processingInstruction(Node& pinode)
       {  cppdom::ignore_unused_variable_warning(pinode);}
 
-      /** called when start parsing a node */
+      /** Called when start parsing a node. */
       virtual void startNode(const std::string& nodename)
       { cppdom::ignore_unused_variable_warning(nodename); }
-      /** called when an attribute list was parsed */
+
+      /** Called when an attribute list was parsed. */
       virtual void parsedAttributes(Attributes& attr)
       { cppdom::ignore_unused_variable_warning(attr); }
-      /** called when parsing of a node was finished */
+
+      /** Called when parsing of a node was finished. */
       virtual void endNode(Node& node)
       { cppdom::ignore_unused_variable_warning(node);}
 
-      /** called when a cdata section ended */
+      /** Called when a cdata section ended. */
       virtual void gotCdata(const std::string& cdata)
       { cppdom::ignore_unused_variable_warning(cdata); }
    };
@@ -809,10 +858,13 @@
    // ----------------------------------- //
    /** @name Helper methods */
    //@{
-   /** Merges data from one node to another.
+   /**
+    * Merges data from one node to another.
+    *
+    * @post All elements and attributes in fromNode will exist in toNode.
+    *
     * @param fromNode   Node to read data from.
     * @param toNode     Node to merge data onto.
-    * @post All elements and attributes in fromNode will exist in toNode.
     */
    CPPDOM_EXPORT(void) merge(NodePtr fromNode, NodePtr toNode);
    //@}


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.


