documentation

src/xml-cxx/xml.hxx

@@ -46,7 +46,10 @@
     All tags are by default specified as 0..n (optional and any number
     there of).
 
-    <code>
+    @code
+    #include <xml-cxx/xml.hxx>
+    #include <iostream>
+    [...]
     xml::Factory test(xml::Node("persons")             // root node
                       <<(xml::Node("person")           // child of persons
                          .attr("id", xml::mandatory)
@@ -55,11 +58,13 @@
                          <<(xml::Node("friends")       // friends of person
                             <<(xml::Node("friend")     // a friend
                                .attr("id", xml::mandatory)))));
+    [...]
     try {
       std::auto_ptr<xml::Node> persons(test.read(std::ifstream("file.xml)));
       // Here we can be sure, that our structure is valid,
       // but we must check optional elements before access, otherwise
       // we get an exception.
+      [...]
       for (xml::Node::size_type i(0); i<persons.children(); ++i) {
         std::cout<<"Person: "<<*persons[i]["name"]; // exception if no "name"
         if (persons[i]("friends")) // check if "friends" is set
@@ -68,17 +73,30 @@
           std::cout<<" has no friend list";
         std::cout<<std::endl;
       }
+      [...]
     } catch (const std::exception& x) {
       std::cerr<<"**** Error in file \"file.xml\":"<<std::endl
                <<x.what()<<std::endl;
     }
-    </code> */
+    @endcode */
 namespace xml {
   
   //============================================================================
-  enum NodeType {START, END, EMPTY, SPECIAL};
-  const bool mandatory = true;
-  const bool optional = false;
+  //! Type of an xml node.
+  /*! Only start nodes and empty nodes may have attributes. */
+  enum NodeType {
+    START, //!< start node, such as <code>&lt;node&gt;</code>
+    END, //!< end node, such as <code>&lt;/node&gt;</code>
+    EMPTY, //!< empty node, such as <code>&lt;node/&gt;</code>
+    SPECIAL //!< special node, such as
+    //! a comment <code>&lt;!-- ... --&gt;</code>,
+    //! a xml start indication <code>&lt;?xml?&gt;</code>
+    //! or a document type declaration <code>&lt;!DOCTYPE ...&gt;</code>
+  };
+  //! Declares an attribute to be mandatory.
+  const bool mandatory(true);
+  //! Declares an attribute to be optional.
+  const bool optional(false);
 
   //================================================================= EXCEPTIONS
   struct Tag;
@@ -243,26 +261,19 @@ namespace xml {
       //! Attribute values ar mainly a std::pair.
       /*! In addition to a normal std::pair, attributes offer an
           assignment operator to set the value, and can be constructed
-          as empty attribute, given only a key. */
+          as empty attribute, given only a key.
+          @note Simply use xml::Attr instead of xml::Attributes::Value. */
       class Value: public value_type {
         public:
-          //! Construct an empty attribute.
+          Value(const value_type& o) throw();
           Value(const std::string& name) throw();
-          //! Construct an attribute with name an value.
           Value(const std::string& name, const std::string& namevalue) throw();
-          //! Assign a value.
-          value_type& operator=(const std::string& value) throw();
-          //! Get the attribute name.
+          Value& operator=(const std::string& value) throw();
           const std::string& name() const throw();
-          //! Get the attribute value.
           const std::string& value() const throw();
-          //! Get the attribute value.
           std::string& value() throw();
-          //! Convert the attribute to a boolean.
           operator bool() const throw();
-          //! Convert the attribute to a number.
           operator unsigned long() const throw();
-          //! Convert the attribute to a space separated list.
           operator List() const throw();
           List toList(const std::string& separators=" \t\n\r") const throw();
         private:
@@ -270,16 +281,16 @@ namespace xml {
       };
       Attributes() throw();
       Attributes(const std::string& empty) throw();
-      Attributes& operator<<(const value_type& v) throw();
+      Attributes(const std::string& key, const std::string& value) throw();
+      Attributes& operator<<(const Value& v) throw();
       Attributes& operator<<(const std::string& key) throw();
-      Attributes& operator=(const std::string& value) throw();
-    private:
-      iterator _active;
   };
+  //! Simplification: Use xml::Attr instead of xml::Attributes::Value.
   typedef Attributes::Value Attr;
 
 
   //----------------------------------------------------------------------------
+  //! @internal structure for parsing tags
   struct Tag {
       std::string name;
       NodeType type;
@@ -289,6 +300,9 @@ namespace xml {
   };
 
   //----------------------------------------------------------------------------
+  //! An xml Node.
+  /*! XML Nodes may contain either text or other nodes, but not both
+      at the same time. */
   class Node {
     private:
       typedef std::vector<Node*> Contents;

src/xml.cxx

@@ -126,36 +126,55 @@ namespace xml {
   //============================================================================
 
   //----------------------------------------------------------------------------
+  //! Copy an attribute.
+  Attributes::Value::Value(const value_type& o) throw():
+      Attributes::value_type(o) {
+  }
+  //! Construct an empty attribute.
   Attributes::Value::Value(const std::string& name) throw():
       Attributes::value_type(name, std::string()) {
   }
+  //! Construct an attribute with name an value.
   Attributes::Value::Value(const std::string& name,
                            const std::string& value) throw():
       Attributes::value_type(name, value) {
   }
+  //! Assign a value.
+  Attributes::Value& Attributes::Value::operator=(const std::string& value)
+      throw() {
+    second = value;
+    return *this;
+  }
+  //! Get the attribute name.
   const std::string& Attributes::Value::name() const throw() {
     return first;
   }
+  //! Get the attribute value.
   const std::string& Attributes::Value::value() const throw() {
     return second;
   }
+  //! Get the attribute value.
   std::string& Attributes::Value::value() throw() {
     return second;
   }
+  //! Convert the attribute to a boolean.
   Attributes::Value::operator bool() const throw() {
     /*! @return @c true if the value is set and not equal to one of:
         @c false @c no @c 0. */
     return !(second.size()||second=="false"||second=="no"||second=="0");
   }
+  //! Convert the attribute to a number.
   Attributes::Value::operator unsigned long() const throw() {
     std::stringstream ss(second);
     int i(0);
     ss>>i;
     return i;
   }
+  //! Convert the attribute to a space separated list.
   Attributes::Value::operator List() const throw() {
     return toList();
   }
+  //! Convert the attribute to a space separated list.
   Attributes::List Attributes::Value::toList(const std::string& separators)
       const throw() {
     List l;
@@ -166,30 +185,31 @@ namespace xml {
     return l;
   }
   //----------------------------------------------------------------------------
-  Attributes::value_type& Attributes::Value::operator=(const std::string& value)
-      throw() {
-    second = value;
-    return *this;
-  }
-  Attributes::Attributes() throw(): _active(end()) {}
+  //! Empty attribute list
+  Attributes::Attributes() throw() {}
+  //! Attribute list with first one empty attribute given.
   Attributes::Attributes(const std::string& empty) throw() {
-    _active = insert(Value(empty)).first;
+    insert(Value(empty));
   }
-  Attributes& Attributes::operator<<(const value_type& v) throw() {
-    _active = insert(v).first;
-    return *this;
+  //! Attribute list with first attribute given.
+  Attributes::Attributes(const std::string& key,
+                         const std::string& value) throw() {
+    insert(Value(key, value));
   }
-  Attributes& Attributes::operator<<(const std::string& key) throw() {
-    _active = insert(Value(key)).first;
+  //! Add a new key-value pair to the attribute list.
+  Attributes& Attributes::operator<<(const Attributes::Value& v) throw() {
+    insert(v);
     return *this;
   }
-  Attributes& Attributes::operator=(const std::string& value) throw() {
-    if (_active==end()) return *this;
-    _active->second = value;
-    _active = end();
+  //! Add a new empty key to the attribute list.
+  Attributes& Attributes::operator<<(const std::string& key) throw() {
+    insert(Value(key));
     return *this;
   }
   //----------------------------------------------------------------------------
+  //! Nodes must be given a name.
+  /*! Unnamed nodes are not allowed, therefore there's no default
+      constructor. */
   Node::Node(std::string name) throw():
       _name(name), _parent(0) {
   }
@@ -210,6 +230,7 @@ namespace xml {
   Node::~Node() throw() {
     clear();
   }
+  //! Clones But clears the parent.
   std::auto_ptr<Node> Node::clone() const throw() {
     std::auto_ptr<Node> res(new Node(*this));
     res->_parent = 0;