more docu

src/xml-cxx/xml.hxx

@@ -393,16 +393,11 @@ namespace xml {
       bool operator()(const std::string& child) const throw();
       Node& operator<<(const Node& o) throw(cannot_have_children);
       Node& operator<<(const Attributes& o) throw();
-      //! Get the number of children.
       size_type children() const throw();
-      //! Get the n-th child.
       const Node& operator[](size_type child) const throw(out_of_range);
-      //! Get the n-th child.
       Node& operator[](size_type child) throw(out_of_range);
-      //! Get the first named child.
       const Node& operator[](const std::string& child) const
           throw(access_error);
-      //! Get the first named child.
       Node& operator[](const std::string& child) throw(access_error);
       std::string operator*() const throw();
       Node& operator=(const std::string& contents) throw(tag_expected,

src/xml.cxx

@@ -202,7 +202,8 @@ namespace xml {
     return l;
   }
   //! Get the first value of an attribute containing a list of values.
-  /*! @copydoc xml::Attributes::Value::toList */
+  /*! @copydoc xml::Attributes::Value::toList
+      @return the first element of the list. */
   std::string Attributes::Value::front(const std::string& separators) const
       throw(empty_attribute_list) {
     List l(toList(separators));
@@ -242,7 +243,8 @@ namespace xml {
   }
   //! Copy node, reset parent.
   /*! The parent is reset, the node does not belong to the same parent
-      as the source of the copy. */
+      as the source of the copy.
+      @see xml::Node::clone for more information on the parenting. */
   Node::Node(const Node& o) throw():
       _attributes(o._attributes), _name(o.name()), _parent(0),
       _min(o._min), _max(o._max) {
@@ -252,7 +254,8 @@ namespace xml {
   }
   //! Assign new node, keep parent.
   /*! The parent remains unchanged, the node does not belong to the
-      same parent as the source of the copy. */
+      same parent as the source of the copy.
+      @see xml::Node::clone for more information on the parenting. */
   Node& Node::operator=(const Node& o) throw() {
     _attributes=o._attributes;
     _name = o.name();
@@ -459,7 +462,7 @@ namespace xml {
     _max = max;
     return *this;
   }
-  //! Get all children of a given node name
+  //! Get all immediate children of a given node name.
   Node::List Node::list(const std::string& name) const throw() {
     List res;
     for (Contents::const_iterator it(_contents.begin());
@@ -467,50 +470,72 @@ namespace xml {
       if ((*it)->_name==name) res.push_back(*it);
     return res;
   }
+  //! Check if at least one child node of a given name exists.
   bool Node::operator()(const std::string& child) const throw() {
     return find(child);
   }
+  //! Append a child at the end.
+  /*! @copydoc xml::Node::append */
   Node& Node::operator<<(const Node& o) throw(cannot_have_children) {
     return append(o);
   }
+  //! Add an empty attribute.
+  /*! @copydoc xml::Node::set */
   Node& Node::operator<<(const Attributes& o) throw() {
     return set(o);
   }
+  //! Get the number of children.
   Node::size_type Node::children() const throw() {
     return _contents.size();
   }
+  //! Get a child by child-number (the n-th child).
+  /*! @param child number of the child to return: <code>child&gt;=0</code> and
+             <code>child&lt;xml::Node::children()</code> */
   const Node& Node::operator[](Node::size_type child) const
       throw(out_of_range) try {
     return *_contents.at(child);
   } catch (...) {
     throw out_of_range(*this, child);
   }
+  /*! @copydoc xml::Node::operator[](Node::size_type child) const */
   Node& Node::operator[](Node::size_type child) throw(out_of_range) try {
     return *_contents.at(child);
   } catch (...) {
     throw out_of_range(*this, child);
   }
+  //! Get the first child of a given node name.
+  /*! @return the first child with matching node name */
   const Node& Node::operator[](const std::string& child) const
       throw(access_error) {
     const Node* const t(find(child));
     if (!t) throw access_error(*this, child);
     return *t;
   }
+  /*! @copydoc xml::Node::operator[](const std::string& child) const */
   Node& Node::operator[](const std::string& child) throw(access_error) {
     Node* const t(find(child));
     if (!t) throw access_error(*this, child);
     return *t;
   }
+  //! Get the textual contents of a node.
+  /*! @copydoc xml::Node::text() */
   std::string Node::operator*() const throw() {
     return text();
   }
+  //! Set a text (forbidden in xml::Node)
+  /*! @copydoc xml::Node::text(const std::string& txt) */
   Node& Node::operator=(const std::string& contents) throw(tag_expected,
                                                            type_mismatch) {
     return text(contents);
   }
+  //! Write node in XML format to a stream.
+  /*! @copydoc xml::Node::out */
   std::ostream& operator<<(std::ostream& o, const Node& t) throw() {
     return t.out(o);
   }
+  //! Get a pointer to the first child of a given node name.
+  /*! This method does not throw an exception if the element does not
+      exist, but returns @c 0. */
   Node* Node::find(const std::string& child) const throw() {
     for (Contents::const_iterator it(_contents.begin());
          it!=_contents.end(); ++it) {
@@ -518,6 +543,14 @@ namespace xml {
     }
     return 0;
   }
+  //! Clone a node, but assign a new parent.
+  /*! If you clone (or copy) a node, the parent is not copied. This is
+      because otherwise the new now would need to be appended to the
+      parent's child list. That's most probably not
+      intended. Therefore, in a normal copy operation (copy-construct
+      or copy-assign) the parent is set to @c 0 (no parent). Then the
+      new node can be appended to a parent if needed. In this method,
+      the new parent can be given in the same step. */
   std::auto_ptr<Node> Node::clone(Node* p) const throw() {
     std::auto_ptr<Node> c(clone());
     c->_parent = p;
@@ -525,10 +558,15 @@ namespace xml {
   }
 
   //----------------------------------------------------------------------------
+  /*! @copydoc Node::Node(std::string name,
+                          Node::size_type min, Node::size_type max) */
   String::String(std::string name,
                  Node::size_type min, Node::size_type max) throw():
       Node(name, min, max) {
   }
+  //! Pass the text in the node.
+  /*! @copydoc Node::Node(std::string name,
+                          Node::size_type min, Node::size_type max) */
   String::String(std::string name, const std::string& text,
                  Node::size_type min, Node::size_type max) throw():
       Node(name, min, max), _text(text) {
@@ -539,6 +577,8 @@ namespace xml {
   std::string String::text() const throw() {
     return _text;
   }
+  //! An xml::String contains text: Set the text.
+  /*! Never throws an exception. */
   String& String::text(const std::string& txt) throw(tag_expected,
                                                      type_mismatch) {
     _text = txt;
@@ -560,14 +600,18 @@ namespace xml {
     }
     return o;
   }
+  //! An xml::String has no child nodes: Always throws an exception.
   String& String::append(const Node& o) throw(cannot_have_children) {
     throw cannot_have_children(*this, o);
   }
+  //! An xml::String contains text: Set the text.
   Node& String::operator=(const std::string& contents) throw() {
     return text(contents);
   }
 
   //----------------------------------------------------------------------------
+  /*! @copydoc Node::Node(std::string name,
+                          Node::size_type min, Node::size_type max) */
   UnsignedInteger::UnsignedInteger(std::string name, unsigned long i,
                                    size_type min, size_type max) throw():
       String(name,
@@ -577,6 +621,8 @@ namespace xml {
   std::auto_ptr<Node> UnsignedInteger::clone() const throw() {
     return std::auto_ptr<Node>(new UnsignedInteger(*this));
   }
+  //! An xml::UnsignedInteger must only contain an number.
+  /*! En exception is thrown, if the contents does not match a number. */
   UnsignedInteger& UnsignedInteger::text(const std::string& txt)
       throw(tag_expected, type_mismatch) {
     std::string::size_type