From 650e88e2c3cdc03cd469e1079470958666304aca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20W=C3=A4ckerlin?= Date: Tue, 21 Apr 2009 07:12:24 +0000 Subject: [PATCH] more docu --- src/xml-cxx/xml.hxx | 5 ----- src/xml.cxx | 54 +++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 50 insertions(+), 9 deletions(-) diff --git a/src/xml-cxx/xml.hxx b/src/xml-cxx/xml.hxx index 10b5702..704cc07 100644 --- a/src/xml-cxx/xml.hxx +++ b/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, diff --git a/src/xml.cxx b/src/xml.cxx index 9f52bb6..365261d 100644 --- a/src/xml.cxx +++ b/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: child>=0 and + child<xml::Node::children() */ 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::clone(Node* p) const throw() { std::auto_ptr 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 UnsignedInteger::clone() const throw() { return std::auto_ptr(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