Major header cleanup: removed redundant comments (single-line function/type descriptions are left for convenience), removed parse()/as_utf16(), removed deprecated function tests

git-svn-id: http://pugixml.googlecode.com/svn/trunk@746 99668b35-9821-0410-8761-19e4c4f06640

2 files changed, 350 insertions, 1579 deletions

diff --git a/src/pugixml.cpp b/src/pugixml.cpp
index 1790185..8b2f35c 100644
--- a/src/pugixml.cpp
+++ b/src/pugixml.cpp
@@ -4253,6 +4253,15 @@ namespace pugi
 		return temp;
 	}
 
+    xml_parse_result::xml_parse_result(): status(status_internal_error), offset(0), encoding(encoding_auto)
+    {
+    }
+
+    xml_parse_result::operator bool() const
+    {
+        return status == status_ok;
+    }
+
 	const char* xml_parse_result::description() const
 	{
 		switch (status)
@@ -4379,16 +4388,6 @@ namespace pugi
 		return load_buffer(contents, strlength(contents) * sizeof(char_t), options, encoding);
 	}
 
-	xml_parse_result xml_document::parse(char* xmlstr, unsigned int options)
-	{
-		return load_buffer_inplace(xmlstr, strlen(xmlstr), options, encoding_utf8);
-	}
-		
-	xml_parse_result xml_document::parse(const transfer_ownership_tag&, char* xmlstr, unsigned int options)
-	{
-		return load_buffer_inplace_own(xmlstr, strlen(xmlstr), options, encoding_utf8);
-	}
-
 	xml_parse_result xml_document::load_file(const char* path, unsigned int options, xml_encoding encoding)
 	{
 		reset();
@@ -4543,11 +4542,6 @@ namespace pugi
 	  	return result;
 	}
 	
-	std::wstring PUGIXML_FUNCTION as_utf16(const char* str)
-	{
-		return as_wide(str);
-	}
-
 	std::wstring PUGIXML_FUNCTION as_wide(const char* str)
 	{
 		assert(str);
@@ -8956,11 +8950,23 @@ namespace pugi
 		}
 	};
 
+    xpath_parse_result::xpath_parse_result(): error("Internal error"), offset(0)
+    {
+    }
+
+    xpath_parse_result::operator bool() const
+    {
+        return error == 0;
+    }
 	const char* xpath_parse_result::description() const
 	{
 		return error ? error : "No error";
 	}
 
+	xpath_variable::xpath_variable()
+    {
+    }
+
 	const char_t* xpath_variable::name() const
 	{
 		switch (_type)
diff --git a/src/pugixml.hpp b/src/pugixml.hpp
index 12b8f49..80fe6d8 100644
--- a/src/pugixml.hpp
+++ b/src/pugixml.hpp
@@ -81,228 +81,109 @@ namespace std
 // Character interface macros
 #ifdef PUGIXML_WCHAR_MODE
 #	define PUGIXML_TEXT(t) L ## t
-
-namespace pugi
-{
-	/// Character type used for all internal storage and operations; depends on PUGIXML_WCHAR_MODE
-	typedef wchar_t char_t;
-
-#ifndef PUGIXML_NO_STL
-	/// String type used for operations that work with STL string; depends on PUGIXML_WCHAR_MODE
-	typedef std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > string_t;
-#endif
-}
+#	define PUGIXML_CHAR wchar_t
 #else
 #	define PUGIXML_TEXT(t) t
+#	define PUGIXML_CHAR char
+#endif
 
 namespace pugi
 {
-	/// Character type used for all internal storage and operations; depends on PUGIXML_WCHAR_MODE
-	typedef char char_t;
+	// Character type used for all internal storage and operations; depends on PUGIXML_WCHAR_MODE
+	typedef PUGIXML_CHAR char_t;
 
-#	ifndef PUGIXML_NO_STL
-	// GCC 3.4 has a bug which prevents string_t instantiation using char_t, so we have to use char type explicitly
-	/// String type used for operations that work with STL string; depends on PUGIXML_WCHAR_MODE
-	typedef std::basic_string<char, std::char_traits<char>, std::allocator<char> > string_t;
-#	endif
-}
+#ifndef PUGIXML_NO_STL
+	// String type used for operations that work with STL string; depends on PUGIXML_WCHAR_MODE
+	typedef std::basic_string<PUGIXML_CHAR, std::char_traits<PUGIXML_CHAR>, std::allocator<PUGIXML_CHAR> > string_t;
 #endif
+}
 
-/// The PugiXML Parser namespace.
+// The PugiXML namespace
 namespace pugi
 {
-	/// Tree node classification.
+	// Tree node types
 	enum xml_node_type
 	{
-		node_null,			///< Undifferentiated entity
-		node_document,		///< A document tree's absolute root.
-		node_element,		///< E.g. '<...>'
-		node_pcdata,		///< E.g. '>...<'
-		node_cdata,			///< E.g. '<![CDATA[...]]>'
-		node_comment,		///< E.g. '<!--...-->'
-		node_pi,			///< E.g. '<?...?>'
-		node_declaration	///< E.g. '<?xml ...?>'
+		node_null,          // Empty (null) node handle
+		node_document,		// A document tree's absolute root
+		node_element,		// Element tag, i.e. '<node/>'
+		node_pcdata,		// Plain character data, i.e. 'text'
+		node_cdata,			// Character data, i.e. '<![CDATA[text]]>'
+		node_comment,		// Comment tag, i.e. '<!-- text -->'
+		node_pi,			// Processing instruction, i.e. '<?name?>'
+		node_declaration	// Document declaration, i.e. '<?xml version="1.0"?>'
 	};
 
 	// Parsing options
 
-	/**
-	 * Minimal parsing mode. Equivalent to turning all other flags off. This set of flags means
-	 * that pugixml does not add pi/cdata sections or comments to DOM tree and does not perform
-	 * any conversions for input data, meaning fastest parsing.
-	 */
-	const unsigned int parse_minimal			= 0x0000;
-
-	/**
-	 * This flag determines if processing instructions (nodes with type node_pi; such nodes have the
-	 * form of <? target content ?> or <? target ?> in XML) are to be put in DOM tree. If this flag is off,
-	 * they are not put in the tree, but are still parsed and checked for correctness.
-	 *
-	 * The corresponding node in DOM tree will have type node_pi, name "target" and value "content",
-	 * if any.
-	 *
-	 * Note that <?xml ...?> (document declaration) is not considered to be a PI.
-	 *
-	 * This flag is off by default.
-	 */
-	const unsigned int parse_pi					= 0x0001;
-
-	/**
-	 * This flag determines if comments (nodes with type node_comment; such nodes have the form of
-	 * <!-- content --> in XML) are to be put in DOM tree. If this flag is off, they are not put in
-	 * the tree, but are still parsed and checked for correctness.
-	 *
-	 * The corresponding node in DOM tree will have type node_comment, empty name and value "content".
-	 *
-	 * This flag is off by default.
-	 */
-	const unsigned int parse_comments			= 0x0002;
-
-	/**
-	 * This flag determines if CDATA sections (nodes with type node_cdata; such nodes have the form
-	 * of <![CDATA[[content]]> in XML) are to be put in DOM tree. If this flag is off, they are not
-	 * put in the tree, but are still parsed and checked for correctness.
-	 *
-	 * The corresponding node in DOM tree will have type node_cdata, empty name and value "content".
-	 *
-	 * This flag is on by default.
-	 */
-	const unsigned int parse_cdata				= 0x0004;
-
-	/**
-	 * This flag determines if nodes with PCDATA (regular text) that consist only of whitespace
-	 * characters are to be put in DOM tree. Often whitespace-only data is not significant for the
-	 * application, and the cost of allocating and storing such nodes (both memory and speed-wise)
-	 * can be significant. For example, after parsing XML string "<node> <a/> </node>", <node> element
-	 * will have 3 children when parse_ws_pcdata is set (child with type node_pcdata and value=" ",
-	 * child with type node_element and name "a", and another child with type node_pcdata and
-	 * value=" "), and only 1 child when parse_ws_pcdata is not set.
-	 * 
-	 * This flag is off by default.
-	 */
-	const unsigned int parse_ws_pcdata			= 0x0008;
-
-	/**
-	 * This flag determines if character and entity references are to be expanded during the parsing
-	 * process. Character references are &amp;#...; or &amp;#x...; (... is Unicode numeric representation of
-     * character in either decimal (&amp;#...;) or hexadecimal (&amp;#x...;) form), entity references are &amp;...;
-     * Note that as pugixml does not handle DTD, the only allowed entities are predefined ones - 
-     * &amp;lt;, &amp;gt;, &amp;amp;, &amp;apos; and &amp;quot;. If character/entity reference can not be expanded, it is
-     * leaved as is, so you can do additional processing later.
-     * Reference expansion is performed in attribute values and PCDATA content.
-     *
-     * This flag is on by default.
-     */
-	const unsigned int parse_escapes			= 0x0010;
-
-	/**
-	 * This flag determines if EOL handling (that is, replacing sequences 0x0d 0x0a by a single 0x0a
-	 * character, and replacing all standalone 0x0d characters by 0x0a) is to be performed on input
-	 * data (that is, comments contents, PCDATA/CDATA contents and attribute values).
-	 *
-	 * This flag is on by default.
-	 */
-	const unsigned int parse_eol				= 0x0020;
+	// Minimal parsing mode (equivalent to turning all other flags off).
+    // Only elements and PCDATA sections are added to the DOM tree, no text conversions are performed.
+	const unsigned int parse_minimal = 0x0000;
+
+	// This flag determines if processing instructions (node_pi) are added to the DOM tree. This flag is off by default.
+	const unsigned int parse_pi = 0x0001;
+
+	// This flag determines if comments (node_comment) are added to the DOM tree. This flag is off by default.
+	const unsigned int parse_comments = 0x0002;
+
+	// This flag determines if CDATA sections (node_cdata) are added to the DOM tree. This flag is on by default.
+	const unsigned int parse_cdata = 0x0004;
+
+	// This flag determines if plain character data (node_pcdata) that consist only of whitespace are added to the DOM tree.
+    // This flag is off by default; turning it on usually results in slower parsing and more memory consumption.
+	const unsigned int parse_ws_pcdata = 0x0008;
+
+	// This flag determines if character and entity references are expanded during parsing. This flag is on by default.
+	const unsigned int parse_escapes = 0x0010;
+
+	// This flag determines if EOL characters are normalized (converted to #xA) during parsing. This flag is on by default.
+	const unsigned int parse_eol = 0x0020;
 	
- 	/**
- 	 * This flag determines if attribute value normalization should be performed for all attributes.
- 	 * This means, that:
- 	 * 1. Whitespace characters (new line, tab and space) are replaced with space (' ')
- 	 * 2. Afterwards sequences of spaces are replaced with a single space
- 	 * 3. Leading/trailing whitespace characters are trimmed
- 	 * 
- 	 * This flag is off by default.
- 	 */
- 	const unsigned int parse_wnorm_attribute	= 0x0080;
-
- 	/**
- 	 * This flag determines if attribute value normalization should be performed for all attributes.
- 	 * This means, that whitespace characters (new line, tab and space) are replaced with space (' ').
- 	 * Note, that the actions performed while this flag is on are also performed if parse_wnorm_attribute
- 	 * is on, so this flag has no effect if parse_wnorm_attribute flag is set.
-	 * New line characters are always treated as if parse_eol is set, i.e. \r\n is converted to single space.
- 	 * 
- 	 * This flag is on by default.
- 	 */
- 	const unsigned int parse_wconv_attribute	= 0x0040;
+ 	// This flag determines if attribute values are normalized using CDATA normalization rules during parsing. This flag is on by default.
+ 	const unsigned int parse_wconv_attribute = 0x0040;
+
+ 	// This flag determines if attribute values are normalized using NMTOKENS normalization rules during parsing. This flag is off by default.
+ 	const unsigned int parse_wnorm_attribute = 0x0080;
 	
-	/**
-	 * This flag determines if XML document declaration (this node has the form of <?xml ... ?> in XML)
-	 * are to be put in DOM tree. If this flag is off, it is not put in the tree, but is still parsed
-	 * and checked for correctness.
-	 *
-	 * The corresponding node in DOM tree will have type node_declaration, name "xml" and attributes,
-	 * if any.
-	 *
-	 * This flag is off by default.
-	 */
-	const unsigned int parse_declaration		= 0x0100;
-
-	/**
-     * This is the default set of flags. It includes parsing CDATA sections (comments/PIs are not
-     * parsed), performing character and entity reference expansion, replacing whitespace characters
-     * with spaces in attribute values and performing EOL handling. Note, that PCDATA sections
-     * consisting only of whitespace characters are not parsed (by default) for performance reasons.
-     */
-	const unsigned int parse_default			= parse_cdata | parse_escapes | parse_wconv_attribute | parse_eol;
-
-	/**
-	 * These flags determine the encoding of input data for XML document. Default mode is encoding_auto,
-	 * which means that document encoding is auto-detected from BOM and necessary encoding conversions are
-	 * applied. You can override this mode by using any of the specific encodings.
-	 */
+    // This flag determines if document declaration (node_declaration) is added to the DOM tree. This flag is off by default.
+	const unsigned int parse_declaration = 0x0100;
+
+	// The default parsing mode.
+    // Elements, PCDATA and CDATA sections are added to the DOM tree, character/reference entities are expanded,
+    // End-of-Line characters are normalized, attribute values are normalized using CDATA normalization rules.
+	const unsigned int parse_default = parse_cdata | parse_escapes | parse_wconv_attribute | parse_eol;
+
+	// These flags determine the encoding of input data for XML document
 	enum xml_encoding
 	{
-		encoding_auto,      //!< Auto-detect input encoding using BOM or < / <? detection; use UTF8 if BOM is not found
-		encoding_utf8,      //!< UTF8 encoding
-		encoding_utf16_le,  //!< Little-endian UTF16
-		encoding_utf16_be,  //!< Big-endian UTF16
-		encoding_utf16,     //!< UTF16 with native endianness
-		encoding_utf32_le,  //!< Little-endian UTF32
-		encoding_utf32_be,  //!< Big-endian UTF32
-		encoding_utf32,     //!< UTF32 with native endianness
-		encoding_wchar      //!< The same encoding wchar_t has (either UTF16 or UTF32)
+		encoding_auto,      // Auto-detect input encoding using BOM or < / <? detection; use UTF8 if BOM is not found
+		encoding_utf8,      // UTF8 encoding
+		encoding_utf16_le,  // Little-endian UTF16
+		encoding_utf16_be,  // Big-endian UTF16
+		encoding_utf16,     // UTF16 with native endianness
+		encoding_utf32_le,  // Little-endian UTF32
+		encoding_utf32_be,  // Big-endian UTF32
+		encoding_utf32,     // UTF32 with native endianness
+		encoding_wchar      // The same encoding wchar_t has (either UTF16 or UTF32)
 	};
 
 	// Formatting flags
 	
-	/**
-	 * Indent the nodes that are written to output stream with as many indentation strings as deep
-	 * the node is in DOM tree.
-	 *
-	 * This flag is on by default.
-	 */
-	const unsigned int format_indent	= 0x01;
+	// Indent the nodes that are written to output stream with as many indentation strings as deep the node is in DOM tree. This flag is on by default.
+	const unsigned int format_indent = 0x01;
 	
-	/**
-	 * This flag determines if encoding-specific BOM is to be written to output stream.
-	 *
-	 * This flag is off by default.
-	 */
+	// Write encoding-specific BOM to the output stream. This flag is off by default.
 	const unsigned int format_write_bom = 0x02;
 
-	/**
-	 * If this flag is on, no indentation is performed and no line breaks are written to output file.
-	 * This means that the data is written to output stream as is.
-	 *
-	 * This flag is off by default.
-	 */
-	const unsigned int format_raw		= 0x04;
+	// Use raw output mode (no indentation and no line breaks are written). This flag is off by default.
+	const unsigned int format_raw = 0x04;
 	
-	/**
-	 * If this flag is on, no default XML declaration is written to output file.
-	 * This means that there will be no XML declaration in output stream unless there was one in XML document
-	 * (i.e. if it was parsed with parse_declaration flag).
-	 *
-	 * This flag is off by default.
-	 */
+	// Omit default XML declaration even if there is no declaration in the document. This flag is off by default.
 	const unsigned int format_no_declaration = 0x08;
 
-	/**
-	 * This is the default set of formatting flags. It includes indenting nodes depending on their
-	 * depth in DOM tree.
-	 */
-	const unsigned int format_default	= format_indent;
+	// The default set of formatting flags.
+    // Nodes are indented depending on their depth in DOM tree, a default declaration is output if document has none.
+	const unsigned int format_default = format_indent;
 		
 	// Forward declarations
 	struct xml_attribute_struct;
@@ -322,38 +203,21 @@ namespace pugi
 	class xpath_variable_set;
 	#endif
 
-	/**
-	 * Abstract writer class
-	 * \see xml_node::print
-	 */
+	// Writer interface for node printing (see xml_node::print)
 	class PUGIXML_CLASS xml_writer
 	{
 	public:
-		/**
-		 * Virtual destructor
-		 */
 		virtual ~xml_writer() {}
 
-		/**
-		 * Write memory chunk into stream/file/whatever
-		 *
-		 * \param data - data pointer
-		 * \param size - data size
-		 */
+		// Write memory chunk into stream/file/whatever
 		virtual void write(const void* data, size_t size) = 0;
 	};
 
-	/** xml_writer implementation for FILE*
-	 * \see xml_writer
-	 */
+	// xml_writer implementation for FILE*
 	class PUGIXML_CLASS xml_writer_file: public xml_writer
 	{
 	public:
-		/**
-		 * Construct writer instance
-		 *
-		 * \param file - this is FILE* object, void* is used to avoid header dependencies on stdio
-		 */
+        // Construct writer from a FILE* object; void* is used to avoid header dependencies on stdio
 		xml_writer_file(void* file);
 
 		virtual void write(const void* data, size_t size);
@@ -363,24 +227,12 @@ namespace pugi
 	};
 
 	#ifndef PUGIXML_NO_STL
-	/** xml_writer implementation for streams
-	 * \see xml_writer
-	 */
+	// xml_writer implementation for streams
 	class PUGIXML_CLASS xml_writer_stream: public xml_writer
 	{
 	public:
-		/**
-		 * Construct writer instance
-		 *
-		 * \param stream - output stream object
-		 */
+        // Construct writer from an output stream object
 		xml_writer_stream(std::basic_ostream<char, std::char_traits<char> >& stream);
-
-		/**
-		 * Construct writer instance
-		 *
-		 * \param stream - output stream object
-		 */
 		xml_writer_stream(std::basic_ostream<wchar_t, std::char_traits<wchar_t> >& stream);
 
 		virtual void write(const void* data, size_t size);
@@ -391,11 +243,7 @@ namespace pugi
 	};
 	#endif
 
-	/**
-	 * A light-weight wrapper for manipulating attributes in DOM tree.
-	 * Note: xml_attribute does not allocate any memory for the attribute it wraps; it only wraps a
-	 * pointer to existing attribute.
-	 */
+	// A light-weight handle for manipulating attributes in DOM tree
 	class PUGIXML_CLASS xml_attribute
 	{
 		friend class xml_attribute_iterator;
@@ -404,242 +252,67 @@ namespace pugi
 	private:
 		xml_attribute_struct* _attr;
 	
-    	/// \internal Safe bool type
     	typedef xml_attribute_struct* xml_attribute::*unspecified_bool_type;
 
-		/// \internal Initializing constructor
 		explicit xml_attribute(xml_attribute_struct* attr);
 
 	public:
-		/**
-		 * Default constructor. Constructs an empty attribute.
-		 */
+        // Default constructor. Constructs an empty attribute.
 		xml_attribute();
 		
-	public:
-    	/**
-    	 * Safe bool conversion.
-    	 * Allows xml_node to be used in a context where boolean variable is expected, such as 'if (node)'.
-    	 */
+    	// Safe bool conversion operator
     	operator unspecified_bool_type() const;
 
     	// Borland C++ workaround
     	bool operator!() const;
 
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
+		// Comparison operators (compares wrapped attribute pointers)
 		bool operator==(const xml_attribute& r) const;
-		
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator!=(const xml_attribute& r) const;
-		
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator<(const xml_attribute& r) const;
-		
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator>(const xml_attribute& r) const;
-		
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator<=(const xml_attribute& r) const;
-		
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator>=(const xml_attribute& r) const;
 
-	public:
-    	/**
-    	 * Get next attribute in attribute list of node that contains the attribute.
-    	 *
-    	 * \return next attribute, if any; empty attribute otherwise
-    	 */
-    	xml_attribute next_attribute() const;
+		// Check if attribute is empty
+		bool empty() const;
 
-    	/**
-    	 * Get previous attribute in attribute list of node that contains the attribute.
-    	 *
-    	 * \return previous attribute, if any; empty attribute otherwise
-    	 */
-    	xml_attribute previous_attribute() const;
+		// Get attribute name/value, or "" if attribute is empty
+		const char_t* name() const;
+		const char_t* value() const;
 
-		/**
-		 * Cast attribute value as int.
-		 *
-		 * \return attribute value as int, or 0 if conversion did not succeed or attribute is empty
-		 */
+		// Get attribute value as a number, or 0 if conversion did not succeed or attribute is empty
 		int as_int() const;
-
-		/**
-		 * Cast attribute value as unsigned int.
-		 *
-		 * \return attribute value as unsigned int, or 0 if conversion did not succeed or attribute is empty
-		 * \note values out of non-negative int range (usually [0, 2^31-1]) get clamped to range boundaries
-		 */
 		unsigned int as_uint() const;
-
-		/**
-		 * Cast attribute value as double.
-		 *
-		 * \return attribute value as double, or 0.0 if conversion did not succeed or attribute is empty
-		 */
 		double as_double() const;
-	
-		/**
-		 * Cast attribute value as float.
-		 *
-		 * \return attribute value as float, or 0.0f if conversion did not succeed or attribute is empty
-		 */
 		float as_float() const;
 
-		/**
-		 * Cast attribute value as bool. Returns true for attributes with values that start with '1',
-		 * 't', 'T', 'y', 'Y', returns false for other attributes.
-		 *
-		 * \return attribute value as bool, or false if conversion did not succeed or attribute is empty
-		 */
+        // Get attribute value as bool (returns true if first character is in '1tTyY' set), or false if attribute is empty
 		bool as_bool() const;
 
-		/// \internal Document order or 0 if not set
-		const void* document_order() const;
-
-	public:
-		/**
-         * Set attribute value to \a rhs.
-         *
-         * \param rhs - new attribute value
-         * \return self
-         */
-		xml_attribute& operator=(const char_t* rhs);
-	
-		/**
-         * Set attribute value to \a rhs.
-         *
-         * \param rhs - new attribute value
-         * \return self
-         */
-		xml_attribute& operator=(int rhs);
-	
-		/**
-         * Set attribute value to \a rhs.
-         *
-         * \param rhs - new attribute value
-         * \return self
-         */
-		xml_attribute& operator=(unsigned int rhs);
-
-		/**
-         * Set attribute value to \a rhs.
-         *
-         * \param rhs - new attribute value
-         * \return self
-         */
-		xml_attribute& operator=(double rhs);
-		
-		/**
-         * Set attribute value to either 'true' or 'false' (depends on whether \a rhs is true or false).
-         *
-         * \param rhs - new attribute value
-         * \return self
-         */
-		xml_attribute& operator=(bool rhs);
-
-		/**
-		 * Set attribute name to \a rhs.
-		 *
-		 * \param rhs - new attribute name
-		 * \return success flag (call fails if attribute is empty or there is not enough memory)
-		 */
+        // Set attribute name/value (returns false if attribute is empty or there is not enough memory)
 		bool set_name(const char_t* rhs);
-		
-		/**
-		 * Set attribute value to \a rhs.
-		 *
-		 * \param rhs - new attribute value
-		 * \return success flag (call fails if attribute is empty or there is not enough memory)
-		 */
 		bool set_value(const char_t* rhs);
 
-		/**
-		 * Set attribute value to \a rhs.
-		 *
-		 * \param rhs - new attribute value
-		 * \return success flag (call fails if attribute is empty or there is not enough memory)
-		 */
+        // Set attribute value with type conversion (numbers are converted to strings, boolean is converted to "true"/"false")
 		bool set_value(int rhs);
-
-		/**
-		 * Set attribute value to \a rhs.
-		 *
-		 * \param rhs - new attribute value
-		 * \return success flag (call fails if attribute is empty or there is not enough memory)
-		 */
 		bool set_value(unsigned int rhs);
-
-		/**
-		 * Set attribute value to \a rhs.
-		 *
-		 * \param rhs - new attribute value
-		 * \return success flag (call fails if attribute is empty or there is not enough memory)
-		 */
 		bool set_value(double rhs);
-
-		/**
-		 * Set attribute value to either 'true' or 'false' (depends on whether \a rhs is true or false).
-		 *
-		 * \param rhs - new attribute value
-		 * \return success flag (call fails if attribute is empty or there is not enough memory)
-		 */
 		bool set_value(bool rhs);
 
-	public:
-		/**
-		 * Check if attribute is empty.
-		 *
-		 * \return true if attribute is empty, false otherwise
-		 */
-		bool empty() const;
+		// Set attribute value (equivalent to set_value without error checking)
+		xml_attribute& operator=(const char_t* rhs);
+		xml_attribute& operator=(int rhs);
+		xml_attribute& operator=(unsigned int rhs);
+		xml_attribute& operator=(double rhs);
+		xml_attribute& operator=(bool rhs);
 
-	public:
-		/**
-		 * Get attribute name.
-		 *
-		 * \return attribute name, or "" if attribute is empty
-		 */
-		const char_t* name() const;
+        // Get next/previous attribute in the attribute list of the parent node
+    	xml_attribute next_attribute() const;
+    	xml_attribute previous_attribute() const;
 
-		/**
-		 * Get attribute value.
-		 *
-		 * \return attribute value, or "" if attribute is empty
-		 */
-		const char_t* value() const;
+		// This function is for internal use
+		const void* document_order() const;
 	};
 
 #ifdef __BORLANDC__
@@ -648,11 +321,7 @@ namespace pugi
 	bool PUGIXML_FUNCTION operator||(const xml_attribute& lhs, bool rhs);
 #endif
 
-	/**
-	 * A light-weight wrapper for manipulating nodes in DOM tree.
-	 * Note: xml_node does not allocate any memory for the node it wraps; it only wraps a pointer to
-	 * existing node.
-	 */
+	// A light-weight handle for manipulating nodes in DOM tree
 	class PUGIXML_CLASS xml_node
 	{
 		friend class xml_attribute_iterator;
@@ -661,411 +330,101 @@ namespace pugi
 	protected:
 		xml_node_struct* _root;
 
-    	/// \internal Safe bool type
     	typedef xml_node_struct* xml_node::*unspecified_bool_type;
 
-		/// \internal Initializing constructor
 		explicit xml_node(xml_node_struct* p);
 
 	public:
-		/**
-		 * Default constructor. Constructs an empty node.
-		 */
+		// Default constructor. Constructs an empty node.
 		xml_node();
 
-	public:
-    	/**
-    	 * Safe bool conversion.
-    	 * Allows xml_node to be used in a context where boolean variable is expected, such as 'if (node)'.
-    	 */
+    	// Safe bool conversion operator
 		operator unspecified_bool_type() const;
 
 		// Borland C++ workaround
 		bool operator!() const;
 	
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
+		// Comparison operators (compares wrapped node pointers)
 		bool operator==(const xml_node& r) const;
-
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator!=(const xml_node& r) const;
-
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator<(const xml_node& r) const;
-
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator>(const xml_node& r) const;
-
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator<=(const xml_node& r) const;
-		
-		/**
-		 * Compare wrapped pointer to the attribute to the pointer that is wrapped by \a r.
-		 *
-		 * \param r - value to compare to
-		 * \return comparison result
-		 */
 		bool operator>=(const xml_node& r) const;
 
-	public:
-		/**
-		 * Node iterator type (for child nodes).
-		 * \see xml_node_iterator
-		 */
-		typedef xml_node_iterator iterator;
-
-		/**
-		 * Node iterator type (for child nodes).
-		 * \see xml_attribute_iterator
-		 */
-		typedef xml_attribute_iterator attribute_iterator;
-
-		/**
-		 * Access the begin iterator for this node's collection of child nodes.
-		 *
-		 * \return iterator that points to the first child node, or past-the-end iterator if node is empty or has no children
-		 */
-		iterator begin() const;
-	
-		/**
-		 * Access the end iterator for this node's collection of child nodes.
-		 *
-		 * \return past-the-end iterator for child list
-		 */
-		iterator end() const;
-	
-		/**
-		 * Access the begin iterator for this node's collection of attributes.
-		 *
-		 * \return iterator that points to the first attribute, or past-the-end iterator if node is empty or has no attributes
-		 */
-		attribute_iterator attributes_begin() const;
-	
-		/**
-		 * Access the end iterator for this node's collection of attributes.
-		 *
-		 * \return past-the-end iterator for attribute list
-		 */
-		attribute_iterator attributes_end() const;
-
-	public:
-		/**
-		 * Check if node is empty.
-		 *
-		 * \return true if node is empty, false otherwise
-		 */
+		// Check if node is empty.
 		bool empty() const;
 
-	public:
-		/**
-		 * Get node type
-		 *
-		 * \return node type; node_null for empty nodes
-		 */
+		// Get node type
 		xml_node_type type() const;
 
-		/**
-		 * Get node name (element name for element nodes, PI target for PI)
-		 *
-		 * \return node name, if any; "" otherwise
-		 */
+		// Get node name/value, or "" if node is empty or it has no name/value
 		const char_t* name() const;
-
-		/**
-		 * Get node value (comment/PI/PCDATA/CDATA contents, depending on node type)
-		 *
-		 * \return node value, if any; "" otherwise
-		 */
 		const char_t* value() const;
 	
-		/**
-		 * Get child with the specified name
-		 *
-		 * \param name - child name
-		 * \return child with the specified name, if any; empty node otherwise
-		 */
-		xml_node child(const char_t* name) const;
-
-		/**
-		 * Get attribute with the specified name
-		 *
-		 * \param name - attribute name
-		 * \return attribute with the specified name, if any; empty attribute otherwise
-		 */
-		xml_attribute attribute(const char_t* name) const;
+		// Get attribute list
+		xml_attribute first_attribute() const;
+        xml_attribute last_attribute() const;
 
-		/**
-		 * Get first of following sibling nodes with the specified name
-		 *
-		 * \param name - sibling name
-		 * \return node with the specified name, if any; empty node otherwise
-		 */
-		xml_node next_sibling(const char_t* name) const;
+        // Get children list
+		xml_node first_child() const;
+        xml_node last_child() const;
 
-		/**
-		 * Get following sibling
-		 *
-		 * \return following sibling node, if any; empty node otherwise
-		 */
+        // Get next/previous sibling in the children list of the parent node
 		xml_node next_sibling() const;
-
-		/**
-		 * Get first of preceding sibling nodes with the specified name
-		 *
-		 * \param name - sibling name
-		 * \return node with the specified name, if any; empty node otherwise
-		 */
-		xml_node previous_sibling(const char_t* name) const;
-
-		/**
-		 * Get preceding sibling
-		 *
-		 * \return preceding sibling node, if any; empty node otherwise
-		 */
 		xml_node previous_sibling() const;
-
-		/**
-		 * Get parent node
-		 *
-		 * \return parent node if any; empty node otherwise
-		 */
+		
+        // Get parent node
 		xml_node parent() const;
 
-		/**
-		 * Get root of DOM tree this node belongs to.
-		 *
-		 * \return tree root
-		 */
+		// Get root of DOM tree this node belongs to
 		xml_node root() const;
 
-		/**
-		 * Get child value of current node; that is, value of the first child node of type PCDATA/CDATA
-		 *
-		 * \return child value of current node, if any; "" otherwise
-		 */
+		// Get child, attribute or next/previous sibling with the specified name
+		xml_node child(const char_t* name) const;
+		xml_attribute attribute(const char_t* name) const;
+		xml_node next_sibling(const char_t* name) const;
+		xml_node previous_sibling(const char_t* name) const;
+
+		// Get child value of current node; that is, value of the first child node of type PCDATA/CDATA
 		const char_t* child_value() const;
 
-		/**
-		 * Get child value of child with specified name. \see child_value
-		 * node.child_value(name) is equivalent to node.child(name).child_value()
-		 *
-		 * \param name - child name
-		 * \return child value of specified child node, if any; "" otherwise
-		 */
+		// Get child value of child with specified name. Equivalent to child(name).child_value().
 		const char_t* child_value(const char_t* name) const;
 
-	public:	
-		/**
-		 * Set node name to \a rhs (for PI/element nodes). \see name
-		 *
-		 * \param rhs - new node name
-		 * \return success flag (call fails if node is of the wrong type or there is not enough memory)
-		 */
+		// Set node name/value (returns false if node is empty, there is not enough memory, or node can not have name/value)
 		bool set_name(const char_t* rhs);
-		
-		/**
-		 * Set node value to \a rhs (for PI/PCDATA/CDATA/comment nodes). \see value
-		 *
-		 * \param rhs - new node value
-		 * \return success flag (call fails if node is of the wrong type or there is not enough memory)
-		 */
 		bool set_value(const char_t* rhs);
-
-		/**
-		 * Add attribute with specified name (for element nodes)
-		 *
-		 * \param name - attribute name
-		 * \return added attribute, or empty attribute if there was an error (wrong node type)
-		 */
+		
+		// Add attribute with specified name. Returns added attribute, or empty attribute on errors.
 		xml_attribute append_attribute(const char_t* name);
-
-		/**
-		 * Insert attribute with specified name after \a attr (for element nodes)
-		 *
-		 * \param name - attribute name
-		 * \param attr - attribute to insert a new one after
-		 * \return inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)
-		 */
 		xml_attribute insert_attribute_after(const char_t* name, const xml_attribute& attr);
-
-		/**
-		 * Insert attribute with specified name before \a attr (for element nodes)
-		 *
-		 * \param name - attribute name
-		 * \param attr - attribute to insert a new one before
-		 * \return inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)
-		 */
 		xml_attribute insert_attribute_before(const char_t* name, const xml_attribute& attr);
 
-		/**
-		 * Add a copy of the specified attribute (for element nodes)
-		 *
-		 * \param proto - attribute prototype which is to be copied
-		 * \return inserted attribute, or empty attribute if there was an error (wrong node type)
-		 */
+		// Add a copy of the specified attribute. Returns added attribute, or empty attribute on errors.
 		xml_attribute append_copy(const xml_attribute& proto);
-
-		/**
-		 * Insert a copy of the specified attribute after \a attr (for element nodes)
-		 *
-		 * \param proto - attribute prototype which is to be copied
-		 * \param attr - attribute to insert a new one after
-		 * \return inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)
-		 */
 		xml_attribute insert_copy_after(const xml_attribute& proto, const xml_attribute& attr);
-
-		/**
-		 * Insert a copy of the specified attribute before \a attr (for element nodes)
-		 *
-		 * \param proto - attribute prototype which is to be copied
-		 * \param attr - attribute to insert a new one before
-		 * \return inserted attribute, or empty attribute if there was an error (wrong node type, or attr does not belong to node)
-		 */
 		xml_attribute insert_copy_before(const xml_attribute& proto, const xml_attribute& attr);
 
-		/**
-		 * Add child node with specified type (for element nodes)
-		 *
-		 * \param type - node type
-		 * \return added node, or empty node if there was an error (wrong node type)
-		 */
+		// Add child node with specified type. Returns added node, or empty node on errors.
 		xml_node append_child(xml_node_type type = node_element);
-
-		/**
-		 * Insert child node with specified type after \a node (for element nodes)
-		 *
-		 * \param type - node type
-		 * \param node - node to insert a new one after
-		 * \return inserted node, or empty node if there was an error (wrong node type, or \a node is not a child of this node)
-		 */
 		xml_node insert_child_after(xml_node_type type, const xml_node& node);
-
-		/**
-		 * Insert child node with specified type before \a node (for element nodes)
-		 *
-		 * \param type - node type
-		 * \param node - node to insert a new one before
-		 * \return inserted node, or empty node if there was an error (wrong node type, or \a node is not a child of this node)
-		 */
 		xml_node insert_child_before(xml_node_type type, const xml_node& node);
 
-		/**
-		 * Add a copy of the specified node as a child (for element nodes)
-		 *
-		 * \param proto - node prototype which is to be copied
-		 * \return inserted node, or empty node if there was an error (wrong node type)
-		 */
+		// Add a copy of the specified node as a child. Returns added node, or empty node on errors.
 		xml_node append_copy(const xml_node& proto);
-
-		/**
-		 * Insert a copy of the specified node after \a node (for element nodes)
-		 *
-		 * \param proto - node prototype which is to be copied
-		 * \param node - node to insert a new one after
-		 * \return inserted node, or empty node if there was an error (wrong node type, or \a node is not a child of this node)
-		 */
 		xml_node insert_copy_after(const xml_node& proto, const xml_node& node);
-
-		/**
-		 * Insert a copy of the specified node before \a node (for element nodes)
-		 *
-		 * \param proto - node prototype which is to be copied
-		 * \param node - node to insert a new one before
-		 * \return inserted node, or empty node if there was an error (wrong node type, or \a node is not a child of this node)
-		 */
 		xml_node insert_copy_before(const xml_node& proto, const xml_node& node);
 
-		/**
-		 * Remove specified attribute
-		 *
-		 * \param a - attribute to be removed
-		 * \return success flag
-		 */
+		// Remove specified attribute
 		bool remove_attribute(const xml_attribute& a);
-
-		/**
-		 * Remove attribute with the specified name, if any
-		 *
-		 * \param name - attribute name
-		 * \return success flag
-		 */
 		bool remove_attribute(const char_t* name);
 
-		/**
-		 * Remove specified child
-		 *
-		 * \param n - child node to be removed
-		 * \return success flag
-		 */
+		// Remove specified child
 		bool remove_child(const xml_node& n);
-
-		/**
-		 * Remove child with the specified name, if any
-		 *
-		 * \param name - child name
-		 * \return success flag
-		 */
 		bool remove_child(const char_t* name);
 
-	public:
-		/**
-		 * Get first attribute
-		 *
-		 * \return first attribute, if any; empty attribute otherwise
-		 */
-		xml_attribute first_attribute() const;
-
-		/**
-		 * Get last attribute
-		 *
-		 * \return last attribute, if any; empty attribute otherwise
-		 */
-        xml_attribute last_attribute() const;
-
-		/**
-		 * Get first child
-		 *
-		 * \return first child, if any; empty node otherwise
-		 */
-		xml_node first_child() const;
-
-		/**
-		 * Get last child
-		 *
-		 * \return last child, if any; empty node otherwise
-		 */
-        xml_node last_child() const;
-		
-		/**
-		 * Find attribute using predicate
-		 *
-		 * \param pred - predicate, that takes xml_attribute and returns bool
-		 * \return first attribute for which predicate returned true, or empty attribute
-		 */
+		// Find attribute using predicate. Returns first attribute for which predicate returned true.
 		template <typename Predicate> xml_attribute find_attribute(Predicate pred) const
 		{
 			if (!_root) return xml_attribute();
@@ -1077,12 +436,7 @@ namespace pugi
 			return xml_attribute();
 		}
 
-		/**
-		 * Find child node using predicate
-		 *
-		 * \param pred - predicate, that takes xml_node and returns bool
-		 * \return first child node for which predicate returned true, or empty node
-		 */
+		// Find child node using predicate. Returns first child for which predicate returned true.
 		template <typename Predicate> xml_node find_child(Predicate pred) const
 		{
 			if (!_root) return xml_node();
@@ -1094,12 +448,7 @@ namespace pugi
 	        return xml_node();
 		}
 
-		/**
-		 * Find node from subtree using predicate
-		 *
-		 * \param pred - predicate, that takes xml_node and returns bool
-		 * \return first node from subtree for which predicate returned true, or empty node
-		 */
+		// Find node from subtree using predicate. Returns first node from subtree (depth-first), for which predicate returned true.
 		template <typename Predicate> xml_node find_node(Predicate pred) const
 		{
 			if (!_root) return xml_node();
@@ -1123,136 +472,57 @@ namespace pugi
 			return xml_node();
 		}
 
-		/**
-		 * Find child node with the specified name that has specified attribute
-		 *
-		 * \param name - child node name
-		 * \param attr_name - attribute name of child node
-		 * \param attr_value - attribute value of child node
-		 * \return first matching child node, or empty node
-		 */
+		// Find child node by attribute name/value
 		xml_node find_child_by_attribute(const char_t* name, const char_t* attr_name, const char_t* attr_value) const;
-
-		/**
-		 * Find child node that has specified attribute
-		 *
-		 * \param attr_name - attribute name of child node
-		 * \param attr_value - attribute value of child node
-		 * \return first matching child node, or empty node
-		 */
 		xml_node find_child_by_attribute(const char_t* attr_name, const char_t* attr_value) const;
 
 	#ifndef PUGIXML_NO_STL
-		/**
-		 * Get the absolute node path from root as a text string.
-		 *
-		 * \param delimiter - delimiter character to insert between element names
-		 * \return path string (e.g. '/bookstore/book/author').
-		 */
+		// Get the absolute node path from root as a text string.
 		string_t path(char_t delimiter = '/') const;
 	#endif
 
-		/**
-		 * Search for a node by path.
-		 * \param path - path string; e.g. './foo/bar' (relative to node), '/foo/bar' (relative 
-		 * to root), '../foo/bar'.
-		 * \param delimiter - delimiter character to use while tokenizing path
-		 * \return matching node, if any; empty node otherwise
-		 */
+		// Search for a node by path consisting of node names and . or .. elements.
 		xml_node first_element_by_path(const char_t* path, char_t delimiter = '/') const;
 
-		/**
-		 * Recursively traverse subtree with xml_tree_walker
-		 * \see xml_tree_walker::begin
-		 * \see xml_tree_walker::for_each
-		 * \see xml_tree_walker::end
-		 *
-		 * \param walker - tree walker to traverse subtree with
-		 * \return traversal result
-		 */
+		// Recursively traverse subtree with xml_tree_walker
 		bool traverse(xml_tree_walker& walker);
 	
 	#ifndef PUGIXML_NO_XPATH
-		/**
-		 * Select single node by evaluating XPath query
-		 * 
-		 * \param query - query string
-		 * \return first node from the resulting node set by document order, or empty node if none found
-		 */
+		// Select single node by evaluating XPath query. Returns first node from the resulting node set.
 		xpath_node select_single_node(const char_t* query, xpath_variable_set* variables = 0) const;
-
-		/**
-		 * Select single node by evaluating XPath query
-		 *
-		 * \param query - compiled query
-		 * \return first node from the resulting node set by document order, or empty node if none found
-		 */
 		xpath_node select_single_node(const xpath_query& query) const;
 
-		/**
-		 * Select node set by evaluating XPath query
-		 *
-		 * \param query - query string
-		 * \return resulting node set
-		 */
+		// Select node set by evaluating XPath query
 		xpath_node_set select_nodes(const char_t* query, xpath_variable_set* variables = 0) const;
-
-		/**
-		 * Select node set by evaluating XPath query
-		 *
-		 * \param query - compiled query
-		 * \return resulting node set
-		 */
 		xpath_node_set select_nodes(const xpath_query& query) const;
 	#endif
 		
-		/// \internal Document order or 0 if not set
-		const void* document_order() const;
-
-		/**
-		 * Print subtree to writer
-		 *
-		 * \param writer - writer object
-		 * \param indent - indentation string
-		 * \param flags - formatting flags
-		 * \param encoding - encoding used for writing
-		 * \param depth - starting depth (used for indentation)
-		 */
+		// Print subtree using a writer object
 		void print(xml_writer& writer, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;
 
 	#ifndef PUGIXML_NO_STL
-		/**
-		 * Print subtree to stream
-		 *
-		 * \param os - output stream
-		 * \param indent - indentation string
-		 * \param flags - formatting flags
-		 * \param encoding - encoding used for writing
-		 * \param depth - starting depth (used for indentation)
-		 */
+		// Print subtree to stream
 		void print(std::basic_ostream<char, std::char_traits<char> >& os, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;
-
-		/**
-		 * Print subtree to stream
-		 *
-		 * \param os - output stream
-		 * \param indent - indentation string
-		 * \param flags - formatting flags
-		 * \param encoding - encoding used for writing
-		 * \param depth - starting depth (used for indentation)
-		 */
 		void print(std::basic_ostream<wchar_t, std::char_traits<wchar_t> >& os, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, unsigned int depth = 0) const;
 	#endif
 
-		/**
-		 * Get node offset in parsed file/string (in bytes) for debugging purposes
-		 *
-		 * \return offset in bytes to start of node data, or -1 in case of error
-		 * \note This will return -1 if node information changed to the extent that it's no longer possible to calculate offset, for example
-		 * if element node name has significantly changed; this is guaranteed to return correct offset only for nodes that have not changed
-		 * since parsing.
-		 */
+		// Child nodes iterators
+		typedef xml_node_iterator iterator;
+
+		iterator begin() const;
+		iterator end() const;
+
+		// Attribute iterators
+		typedef xml_attribute_iterator attribute_iterator;
+
+		attribute_iterator attributes_begin() const;
+		attribute_iterator attributes_end() const;
+
+		// Get node offset in parsed file/string (in char_t units) for debugging purposes
 		ptrdiff_t offset_debug() const;
+
+		// This function is for internal use
+		const void* document_order() const;
 	};
 
 #ifdef __BORLANDC__
@@ -1261,10 +531,7 @@ namespace pugi
 	bool PUGIXML_FUNCTION operator||(const xml_node& lhs, bool rhs);
 #endif
 
-	/**
-	 * Child node iterator.
-	 * It's a bidirectional iterator with value type 'xml_node'.
-	 */
+	// Child node iterator (a bidirectional iterator over a collection of xml_node)
 	class PUGIXML_CLASS xml_node_iterator
 	{
 		friend class xml_node;
@@ -1273,13 +540,10 @@ namespace pugi
 		xml_node _wrap;
 		xml_node _parent;
 
-		/// \internal Initializing constructor
 		xml_node_iterator(xml_node_struct* ref, xml_node_struct* parent);
 
 	public:
-		/**
-		 * Iterator traits
-		 */
+		// Iterator traits
 		typedef ptrdiff_t difference_type;
 		typedef xml_node value_type;
 		typedef xml_node* pointer;
@@ -1289,81 +553,27 @@ namespace pugi
 		typedef std::bidirectional_iterator_tag iterator_category;
 	#endif
 
-		/**
-		 * Default constructor
-		 */
+        // Default constructor
 		xml_node_iterator();
 
-		/**
-		 * Initializing constructor
-		 *
-		 * \param node - node that iterator will point at
-		 */
+        // Construct an iterator which points to the specified node
 		xml_node_iterator(const xml_node& node);
 
-		/**
-		 * Check if this iterator is equal to \a rhs
-		 *
-		 * \param rhs - other iterator
-		 * \return comparison result
-		 */
+        // Iterator operators
 		bool operator==(const xml_node_iterator& rhs) const;
-		
-		/**
-		 * Check if this iterator is not equal to \a rhs
-		 *
-		 * \param rhs - other iterator
-		 * \return comparison result
-		 */
 		bool operator!=(const xml_node_iterator& rhs) const;
 
-		/**
-		 * Dereferencing operator
-		 *
-		 * \return reference to the node iterator points at
-		 */
 		xml_node& operator*();
-
-		/**
-		 * Member access operator
-		 *
-		 * \return pointer to the node iterator points at
-		 */
 		xml_node* operator->();
 
-		/**
-		 * Pre-increment operator
-		 *
-		 * \return self
-		 */
 		const xml_node_iterator& operator++();
-
-		/**
-		 * Post-increment operator
-		 *
-		 * \return old value
-		 */
 		xml_node_iterator operator++(int);
-		
-		/**
-		 * Pre-decrement operator
-		 *
-		 * \return self
-		 */
+
 		const xml_node_iterator& operator--();
-		
-		/**
-		 * Post-decrement operator
-		 *
-		 * \return old value
-		 */
 		xml_node_iterator operator--(int);
 	};
 
-	/**
-	 * Attribute iterator.
-	 * It's a bidirectional iterator with value type 'xml_attribute'.
-	 */
+	// Attribute iterator (a bidirectional iterator over a collection of xml_attribute)
 	class PUGIXML_CLASS xml_attribute_iterator
 	{
 		friend class xml_node;
@@ -1372,13 +582,10 @@ namespace pugi
 		xml_attribute _wrap;
 		xml_node _parent;
 
-		/// \internal Initializing constructor
 		xml_attribute_iterator(xml_attribute_struct* ref, xml_node_struct* parent);
 
 	public:
-		/**
-		 * Iterator traits
-		 */
+		// Iterator traits
 		typedef ptrdiff_t difference_type;
 		typedef xml_attribute value_type;
 		typedef xml_attribute* pointer;
@@ -1388,82 +595,27 @@ namespace pugi
 		typedef std::bidirectional_iterator_tag iterator_category;
 	#endif
 
-		/**
-		 * Default constructor
-		 */
+        // Default constructor
 		xml_attribute_iterator();
 
-		/**
-		 * Initializing constructor
-		 *
-		 * \param attr - attribute that iterator will point at
-		 * \param parent - parent node of the attribute
-		 */
+        // Construct an iterator which points to the specified attribute
 		xml_attribute_iterator(const xml_attribute& attr, const xml_node& parent);
 
-		/**
-		 * Check if this iterator is equal to \a rhs
-		 *
-		 * \param rhs - other iterator
-		 * \return comparison result
-		 */
+		// Iterator operators
 		bool operator==(const xml_attribute_iterator& rhs) const;
-		
-		/**
-		 * Check if this iterator is not equal to \a rhs
-		 *
-		 * \param rhs - other iterator
-		 * \return comparison result
-		 */
 		bool operator!=(const xml_attribute_iterator& rhs) const;
 
-		/**
-		 * Dereferencing operator
-		 *
-		 * \return reference to the node iterator points at
-		 */
 		xml_attribute& operator*();
-
-		/**
-		 * Member access operator
-		 *
-		 * \return pointer to the node iterator points at
-		 */
 		xml_attribute* operator->();
 
-		/**
-		 * Pre-increment operator
-		 *
-		 * \return self
-		 */
 		const xml_attribute_iterator& operator++();
-
-		/**
-		 * Post-increment operator
-		 *
-		 * \return old value
-		 */
 		xml_attribute_iterator operator++(int);
-		
-		/**
-		 * Pre-decrement operator
-		 *
-		 * \return self
-		 */
+
 		const xml_attribute_iterator& operator--();
-		
-		/**
-		 * Post-decrement operator
-		 *
-		 * \return old value
-		 */
 		xml_attribute_iterator operator--(int);
 	};
 
-	/**
-	 * Abstract tree walker class
-	 * \see xml_node::traverse
-	 */
+	// Abstract tree walker class (see xml_node::traverse)
 	class PUGIXML_CLASS xml_tree_walker
 	{
 		friend class xml_node;
@@ -1472,110 +624,69 @@ namespace pugi
 		int _depth;
 	
 	protected:
-		/**
-		 * Get node depth
-		 * 
-		 * \return node depth
-		 */
+		// Get current traversal depth
 		int depth() const;
 	
 	public:
-		/**
-		 * Default constructor
-		 */
 		xml_tree_walker();
-
-		/**
-		 * Virtual destructor
-		 */
 		virtual ~xml_tree_walker();
 
-	public:
-		/**
-		 * Callback that is called when traversal of node begins.
-		 *
-		 * \return returning false will abort the traversal
-		 */
-		virtual bool begin(xml_node&);
-
-		/**
-		 * Callback that is called for each node traversed
-		 *
-		 * \return returning false will abort the traversal
-		 */
-		virtual bool for_each(xml_node&) = 0;
-
-		/**
-		 * Callback that is called when traversal of node ends.
-		 *
-		 * \return returning false will abort the traversal
-		 */
-		virtual bool end(xml_node&);
-	};
+		// Callback that is called when traversal begins
+		virtual bool begin(xml_node& node);
+
+		// Callback that is called for each node traversed
+		virtual bool for_each(xml_node& node) = 0;
 
-	/**
-	 * Struct used to distinguish parsing with ownership transfer from parsing without it.
-	 * \see xml_document::parse
-	 */
-	struct transfer_ownership_tag {};
+		// Callback that is called when traversal ends
+		virtual bool end(xml_node& node);
+	};
 
-	/**
-	 * Parsing status enumeration, returned as part of xml_parse_result struct
-	 */
+	// Parsing status, returned as part of xml_parse_result object
 	enum xml_parse_status
 	{
-		status_ok = 0, ///< No error
-
-		status_file_not_found, ///< File was not found during load_file()
-		status_io_error, ///< Error reading from file/stream
-		status_out_of_memory, ///< Could not allocate memory
-		status_internal_error, ///< Internal error occurred
-
-		status_unrecognized_tag, ///< Parser could not determine tag type
-
-		status_bad_pi, ///< Parsing error occurred while parsing document declaration/processing instruction (<?...?>)
-		status_bad_comment, ///< Parsing error occurred while parsing comment (<!--...-->)
-		status_bad_cdata, ///< Parsing error occurred while parsing CDATA section (<![CDATA[...]]>)
-		status_bad_doctype, ///< Parsing error occurred while parsing document type declaration
-		status_bad_pcdata, ///< Parsing error occurred while parsing PCDATA section (>...<)
-		status_bad_start_element, ///< Parsing error occurred while parsing start element tag (<name ...>)
-		status_bad_attribute, ///< Parsing error occurred while parsing element attribute
-		status_bad_end_element, ///< Parsing error occurred while parsing end element tag (</name>)
-		status_end_element_mismatch ///< There was a mismatch of start-end tags (closing tag had incorrect name, some tag was not closed or there was an excessive closing tag)
+		status_ok = 0,              // No error
+
+		status_file_not_found,      // File was not found during load_file()
+		status_io_error,            // Error reading from file/stream
+		status_out_of_memory,       // Could not allocate memory
+		status_internal_error,      // Internal error occurred
+
+		status_unrecognized_tag,    // Parser could not determine tag type
+
+		status_bad_pi,              // Parsing error occurred while parsing document declaration/processing instruction
+		status_bad_comment,         // Parsing error occurred while parsing comment
+		status_bad_cdata,           // Parsing error occurred while parsing CDATA section
+		status_bad_doctype,         // Parsing error occurred while parsing document type declaration
+		status_bad_pcdata,          // Parsing error occurred while parsing PCDATA section
+		status_bad_start_element,   // Parsing error occurred while parsing start element tag
+		status_bad_attribute,       // Parsing error occurred while parsing element attribute
+		status_bad_end_element,     // Parsing error occurred while parsing end element tag
+		status_end_element_mismatch // There was a mismatch of start-end tags (closing tag had incorrect name, some tag was not closed or there was an excessive closing tag)
 	};
 
-	/**
-	 * Parser result
-	 */
+	// Parsing result
 	struct PUGIXML_CLASS xml_parse_result
 	{
-		/// Parsing status (\see xml_parse_status)
+		// Parsing status (see xml_parse_status)
 		xml_parse_status status;
 
-		/// Last parsed offset (in bytes from file/string start)
+		// Last parsed offset (in char_t units from start of input data)
 		ptrdiff_t offset;
 
-		/// Source document encoding
+		// Source document encoding
 		xml_encoding encoding;
 
-		xml_parse_result(): status(status_internal_error), offset(0), encoding(encoding_auto)
-		{
-		}
+        // Default constructor, initializes object to failed state
+		xml_parse_result();
 
-		/// Cast to bool operator
-		operator bool() const
-		{
-			return status == status_ok;
-		}
+		// Cast to bool operator
+		operator bool() const;
 
-		/// Get error description
+		// Get error description
 		const char* description() const;
 	};
 
-	/**
-	 * Document class (DOM tree root).
-	 * This class has non-copyable semantics (private copy constructor/assignment operator).
-	 */
+	// Document class (DOM tree root)
 	class PUGIXML_CLASS xml_document: public xml_node
 	{
 	private:
@@ -1583,6 +694,7 @@ namespace pugi
 
 		char _memory[192];
 		
+		// Non-copyable semantics
 		xml_document(const xml_document&);
 		const xml_document& operator=(const xml_document&);
 
@@ -1593,184 +705,48 @@ namespace pugi
 		xml_parse_result load_buffer_impl(void* contents, size_t size, unsigned int options, xml_encoding encoding, bool is_mutable, bool own);
 
 	public:
-		/**
-		 * Default constructor, makes empty document
-		 */
+		// Default constructor, makes empty document
 		xml_document();
 
-		/**
-		 * Destructor
-		 */
+		// Destructor, invalidates all node/attribute handles to this document
 		~xml_document();
 
 	public:
 	#ifndef PUGIXML_NO_STL
-		/**
-		 * Load document from stream.
-		 *
-		 * \param stream - stream with XML data
-		 * \param options - parsing options
-		 * \param encoding - source data encoding
-		 * \return parsing result
-		 */
+		// Load document from stream.
 		xml_parse_result load(std::basic_istream<char, std::char_traits<char> >& stream, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
-
-		/**
-		 * Load document from stream.
-		 *
-		 * \param stream - stream with XML data
-		 * \param options - parsing options
-		 * \return parsing result
-		 */
 		xml_parse_result load(std::basic_istream<wchar_t, std::char_traits<wchar_t> >& stream, unsigned int options = parse_default);
 	#endif
 
-		/**
-		 * Load document from string. String has to be zero-terminated. No encoding conversions are applied.
-		 *
-		 * \param contents - input string
-		 * \param options - parsing options
-		 * \return parsing result
-		 */
+		// Load document from zero-terminated string. No encoding conversions are applied.
 		xml_parse_result load(const char_t* contents, unsigned int options = parse_default);
 
-		/**
-		 * Parse the given XML string in-situ.
-		 * The string is modified; you should ensure that string data will persist throughout the
-		 * document's lifetime. Although, document does not gain ownership over the string, so you
-		 * should free the memory occupied by it manually.
-		 *
-		 * \param xmlstr - read/write string with XML data
-		 * \param options - parsing options
-		 * \return parsing result
-		 *
-		 * \deprecated This function is deprecated and will be removed in future versions; use xml_document::load_buffer_inplace instead
-		 */
-		PUGIXML_DEPRECATED xml_parse_result parse(char* xmlstr, unsigned int options = parse_default);
-		
-		/**
-		 * Parse the given XML string in-situ (gains ownership).
-		 * The string is modified; document gains ownership over the string, so you don't have to worry
-		 * about it's lifetime.
-		 * Call example: doc.parse(transfer_ownership_tag(), string, options);
-		 *
-		 * \param xmlstr - read/write string with XML data
-		 * \param options - parsing options
-		 * \return parsing result
-		 *
-		 * \deprecated This function is deprecated and will be removed in future versions; use xml_document::load_buffer_inplace_own instead
-		 */
-		PUGIXML_DEPRECATED xml_parse_result parse(const transfer_ownership_tag&, char* xmlstr, unsigned int options = parse_default);
-
-		/**
-		 * Load document from file
-		 *
-		 * \param path - file path
-		 * \param options - parsing options
-		 * \param encoding - source data encoding
-		 * \return parsing result
-		 */
+		// Load document from file
 		xml_parse_result load_file(const char* path, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
-
-		/**
-		 * Load document from file
-		 *
-		 * \param path - file path
-		 * \param options - parsing options
-		 * \param encoding - source data encoding
-		 * \return parsing result
-		 */
 		xml_parse_result load_file(const wchar_t* path, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
 
-		/**
-		 * Load document from buffer
-		 *
-		 * \param contents - buffer contents
-		 * \param size - buffer size in bytes
-		 * \param options - parsing options
-		 * \param encoding - source data encoding
-		 * \return parsing result
-		 */
+		// Load document from buffer. Copies/converts the buffer, so it may be deleted or changed after the function returns.
 		xml_parse_result load_buffer(const void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
 
-		/**
-		 * Load document from buffer in-situ.
-		 * The buffer is modified; you should ensure that buffer data will persist throughout the document's
-		 * lifetime. Document does not gain ownership over the buffer, so you should free the buffer memory manually.
-		 *
-		 * \param contents - buffer contents
-		 * \param size - buffer size in bytes
-		 * \param options - parsing options
-		 * \param encoding - source data encoding
-		 * \return parsing result
-		 */
+		// Load document from buffer, using the buffer for in-place parsing (the buffer is modified and used for storage of document data).
+        // You should ensure that buffer data will persist throughout the document's lifetime, and free the buffer memory manually once document is destroyed.
 		xml_parse_result load_buffer_inplace(void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
 
-		/**
-		 * Load document from buffer in-situ (gains buffer ownership).
-		 * The buffer is modified; you should ensure that buffer data will persist throughout the document's
-		 * lifetime. Document gains ownership over the buffer, so you should allocate the buffer with pugixml
-		 * allocation function.
-		 *
-		 * \param contents - buffer contents
-		 * \param size - buffer size in bytes
-		 * \param options - parsing options
-		 * \param encoding - source data encoding
-		 * \return parsing result
-		 */
+		// Load document from buffer, using the buffer for in-place parsing (the buffer is modified and used for storage of document data).
+        // You should allocate the buffer with pugixml allocation function; document will free the buffer when it is no longer needed (you can't use it anymore).
 		xml_parse_result load_buffer_inplace_own(void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
 
-		/**
-		 * Save XML to writer
-		 *
-		 * \param writer - writer object
-		 * \param indent - indentation string
-		 * \param flags - formatting flags
-		 * \param encoding - encoding used for writing
-		 */
+		// Save XML document to writer (semantics is slightly different from xml_node::print, see documentation for details).
 		void save(xml_writer& writer, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
 
 	#ifndef PUGIXML_NO_STL
-		/**
-		 * Save XML to stream
-		 *
-		 * \param stream - output stream
-		 * \param indent - indentation string
-		 * \param flags - formatting flags
-		 * \param encoding - encoding used for writing
-		 */
+		// Save XML document to stream (semantics is slightly different from xml_node::print, see documentation for details).
 		void save(std::basic_ostream<char, std::char_traits<char> >& stream, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
-
-		/**
-		 * Save XML to stream
-		 *
-		 * \param stream - output stream
-		 * \param indent - indentation string
-		 * \param flags - formatting flags
-		 */
 		void save(std::basic_ostream<wchar_t, std::char_traits<wchar_t> >& stream, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default) const;
 	#endif
 
-		/**
-		 * Save XML to file
-		 *
-		 * \param path - file path
-		 * \param indent - indentation string
-		 * \param flags - formatting flags
-		 * \param encoding - encoding used for writing
-		 * \return success flag
-		 */
+		// Save XML to file
 		bool save_file(const char* path, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
-
-		/**
-		 * Save XML to file
-		 *
-		 * \param path - file path
-		 * \param indent - indentation string
-		 * \param flags - formatting flags
-		 * \param encoding - encoding used for writing
-		 * \return success flag
-		 */
 		bool save_file(const wchar_t* path, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
 	};
 
@@ -1778,198 +754,155 @@ namespace pugi
 	class xpath_ast_node;
 	class xpath_allocator;
 	
-	/// XPath query return type classification
+	// XPath query return type
 	enum xpath_value_type
 	{
-		xpath_type_none,      ///< Unknown type (query failed to compile)
-		xpath_type_node_set,  ///< Node set (xpath_node_set)
-		xpath_type_number,    ///< Number
-		xpath_type_string,    ///< String
-		xpath_type_boolean    ///< Boolean
+		xpath_type_none,      // Unknown type (query failed to compile)
+		xpath_type_node_set,  // Node set (xpath_node_set)
+		xpath_type_number,    // Number
+		xpath_type_string,    // String
+		xpath_type_boolean    // Boolean
 	};
 
+    // XPath parsing result
 	struct PUGIXML_CLASS xpath_parse_result
 	{
-		/// Error message (0 if no error)
+		// Error message (0 if no error)
 		const char* error;
 
-		/// Last parsed offset (in characters from string start)
+		// Last parsed offset (in char_t units from string start)
 		ptrdiff_t offset;
 
-		xpath_parse_result(): error("Internal error"), offset(0)
-		{
-		}
+        // Default constructor, initializes object to failed state
+		xpath_parse_result();
 
-		/// Cast to bool operator
-		operator bool() const
-		{
-			return error == 0;
-		}
+		// Cast to bool operator
+		operator bool() const;
 
-		/// Get error description
+		// Get error description
 		const char* description() const;
 	};
 
-	/**
-	 * A class that holds XPath variable
-	 */
+	// A single XPath variable
 	class PUGIXML_CLASS xpath_variable
 	{
 		friend class xpath_variable_set;
 
 	protected:
-		// Non-copyable semantics
-		xpath_variable(const xpath_variable&);
-		xpath_variable& operator=(const xpath_variable&);
-		
 		xpath_value_type _type;
 		xpath_variable* _next;
 
-		xpath_variable() {}
-		~xpath_variable() {}
+		xpath_variable();
 
+		// Non-copyable semantics
+		xpath_variable(const xpath_variable&);
+		xpath_variable& operator=(const xpath_variable&);
+		
 	public:
+        // Get variable name
 		const char_t* name() const;
+
+        // Get variable type
 		xpath_value_type type() const;
 
+        // Get variable value; no type conversion is performed, default value (false, NaN, empty string, empty node set) is returned on type mismatch error
 		bool get_boolean() const;
 		double get_number() const;
 		const char_t* get_string() const;
 		const xpath_node_set& get_node_set() const;
 
+        // Set variable value; no type conversion is performed, false is returned on type mismatch error
 		bool set(bool value);
 		bool set(double value);
 		bool set(const char_t* value);
 		bool set(const xpath_node_set& value);
 	};
 
-	/**
-	 * A class that holds XPath variables
-	 */
+	// A set of XPath variables
 	class PUGIXML_CLASS xpath_variable_set
 	{
 	private:
+		xpath_variable* _data[64];
+
 		// Non-copyable semantics
 		xpath_variable_set(const xpath_variable_set&);
 		xpath_variable_set& operator=(const xpath_variable_set&);
 
-		xpath_variable* _data[64];
-
 		xpath_variable* find(const char_t* name) const;
 
 	public:
+        // Default constructor/destructor
 		xpath_variable_set();
 		~xpath_variable_set();
 
+        // Add a new variable or get the existing one, if the types match
 		xpath_variable* add(const char_t* name, xpath_value_type type);
 
+        // Set value of an existing variable; no type conversion is performed, false is returned if there is no such variable or if types mismatch
 		bool set(const char_t* name, bool value);
 		bool set(const char_t* name, double value);
 		bool set(const char_t* name, const char_t* value);
 		bool set(const char_t* name, const xpath_node_set& value);
 
+        // Get existing variable by name
 		xpath_variable* get(const char_t* name);
 		const xpath_variable* get(const char_t* name) const;
 	};
 
-	/**
-	 * A class that holds compiled XPath query and allows to evaluate query result
-	 */
+	// A compiled XPath query object
 	class PUGIXML_CLASS xpath_query
 	{
 	private:
-		// Non-copyable semantics
-		xpath_query(const xpath_query&);
-		xpath_query& operator=(const xpath_query&);
-
 		xpath_allocator* _alloc;
 		xpath_ast_node* _root;
 		xpath_parse_result _result;
 
-    	/// \internal Safe bool type
     	typedef xpath_ast_node* xpath_query::*unspecified_bool_type;
 
+		// Non-copyable semantics
+		xpath_query(const xpath_query&);
+		xpath_query& operator=(const xpath_query&);
+
 	public:
-		/**
-		 * Constructor from string with XPath expression.
-		 * Throws xpath_exception on compilation error, std::bad_alloc on out of memory error.
-		 *
-		 * \param query - string with XPath expression
-		 */
+        // Construct a compiled object from XPath expression.
+        // If PUGIXML_NO_EXCEPTIONS is not defined, throws xpath_exception on compilation errors.
 		explicit xpath_query(const char_t* query, xpath_variable_set* variables = 0);
 
-		/**
-		 * Destructor
-		 */
+		// Destructor
 		~xpath_query();
 
-		/**
-		 * Get query expression return type
-		 *
-		 * \return expression return type
-		 **/
+		// Get query expression return type
 		xpath_value_type return_type() const;
 		
-		/**
-		 * Evaluate expression as boolean value for the context node \a n.
-		 * If expression does not directly evaluate to boolean, the expression result is converted
-		 * as through boolean() XPath function call.
-		 * Throws std::bad_alloc on out of memory error.
-		 *
-		 * \param n - context node
-		 * \return evaluation result
-		 */
+		// Evaluate expression as boolean value in the specified context; performs type conversion if necessary.
+        // If PUGIXML_NO_EXCEPTIONS is not defined, throws std::bad_alloc on out of memory errors.
 		bool evaluate_boolean(const xpath_node& n) const;
 		
-		/**
-		 * Evaluate expression as double value for the context node \a n.
-		 * If expression does not directly evaluate to double, the expression result is converted
-		 * as through number() XPath function call.
-		 * Throws std::bad_alloc on out of memory error.
-		 *
-		 * \param n - context node
-		 * \return evaluation result
-		 */
+		// Evaluate expression as double value in the specified context; performs type conversion if necessary.
+        // If PUGIXML_NO_EXCEPTIONS is not defined, throws std::bad_alloc on out of memory errors.
 		double evaluate_number(const xpath_node& n) const;
 		
 	#ifndef PUGIXML_NO_STL
-		/**
-		 * Evaluate expression as string value for the context node \a n.
-		 * If expression does not directly evaluate to string, the expression result is converted
-		 * as through string() XPath function call.
-		 * Throws std::bad_alloc on out of memory error.
-		 *
-		 * \param n - context node
-		 * \return evaluation result
-		 */
+		// Evaluate expression as string value in the specified context; performs type conversion if necessary.
+        // If PUGIXML_NO_EXCEPTIONS is not defined, throws std::bad_alloc on out of memory errors.
 		string_t evaluate_string(const xpath_node& n) const;
 	#endif
 		
-		/**
-		 * Evaluate expression as string value for the context node \a n.
-		 * If expression does not directly evaluate to string, the expression result is converted
-		 * as through string() XPath function call.
-		 * Throws std::bad_alloc on out of memory error.
-		 *
-		 * \param n - context node
-		 * \return evaluation result
-		 */
+		// Evaluate expression as string value in the specified context; performs type conversion if necessary.
+        // At most capacity characters are written to the destination buffer, full result size is returned (includes terminating zero).
+        // If PUGIXML_NO_EXCEPTIONS is not defined, throws std::bad_alloc on out of memory errors.
+        // If PUGIXML_NO_EXCEPTIONS is defined, returns empty  set instead.
 		size_t evaluate_string(char_t* buffer, size_t capacity, const xpath_node& n) const;
 
-		/**
-		 * Evaluate expression as node set for the context node \a n.
-		 * If expression does not directly evaluate to node set, throws xpath_exception.
-		 * Throws std::bad_alloc on out of memory error.
-		 *
-		 * \param n - context node
-		 * \return evaluation result
-		 */
+		// Evaluate expression as node set in the specified context.
+        // If PUGIXML_NO_EXCEPTIONS is not defined, throws xpath_exception on type mismatch and std::bad_alloc on out of memory errors.
+        // If PUGIXML_NO_EXCEPTIONS is defined, returns empty node set instead.
 		xpath_node_set evaluate_node_set(const xpath_node& n) const;
 
-		// Get parsing result
+		// Get parsing result (used to get compilation errors in PUGIXML_NO_EXCEPTIONS mode)
 		const xpath_parse_result& result() const;
 
-		// Safe bool conversion
+		// Safe bool conversion operator
 		operator unspecified_bool_type() const;
 
     	// Borland C++ workaround
@@ -1977,112 +910,56 @@ namespace pugi
 	};
 	
 	#ifndef PUGIXML_NO_EXCEPTIONS
-	/**
-	 * XPath exception class.
-	 */
+	// XPath exception class
 	class PUGIXML_CLASS xpath_exception: public std::exception
 	{
 	private:
 		xpath_parse_result _result;
 
 	public:
-		/**
-		 * Construct exception from parse result
-		 *
-		 */
+		// Construct exception from parse result
 		explicit xpath_exception(const xpath_parse_result& result);
 
-		/**
-		 * Return error message
-		 *
-		 * \return error message
-		 */
+		// Get error message
 		virtual const char* what() const throw();
 
+        // Get parse result
 		const xpath_parse_result& result() const;
 	};
 	#endif
 	
-	/**
-	 * XPath node class.
-	 * 
-	 * XPath defines node to be either xml_node or xml_attribute in pugixml terminology, so xpath_node
-	 * is either xml_node or xml_attribute.
-	 */
+	// XPath node class (either xml_node or xml_attribute)
 	class PUGIXML_CLASS xpath_node
 	{
 	private:
 		xml_node _node;
 		xml_attribute _attribute;
 	
-    	/// \internal Safe bool type
     	typedef xml_node xpath_node::*unspecified_bool_type;
 
 	public:
-		/**
-		 * Construct empty XPath node
-		 */
+		// Default constructor; constructs empty XPath node
 		xpath_node();
 		
-		/**
-		 * Construct XPath node from XML node
-		 *
-		 * \param node - XML node
-		 */
+		// Construct XPath node from XML node/attribute
 		xpath_node(const xml_node& node);
-
-		/**
-		 * Construct XPath node from XML attribute
-		 *
-		 * \param attribute - XML attribute
-		 * \param parent - attribute's parent node
-		 */
 		xpath_node(const xml_attribute& attribute, const xml_node& parent);
 
-		/**
-		 * Get XML node, if any
-		 *
-		 * \return contained XML node, empty node otherwise
-		 */
+		// Get node/attribute, if any
 		xml_node node() const;
-		
-		/**
-		 * Get XML attribute, if any
-		 *
-		 * \return contained XML attribute, if any, empty attribute otherwise
-		 */
 		xml_attribute attribute() const;
 		
-		/**
-		 * Get parent of contained XML attribute, if any
-		 *
-		 * \return parent of contained XML attribute, if any, empty node otherwise
-		 */
+		// Get parent of contained node/attribute
 		xml_node parent() const;
 
-    	/**
-    	 * Safe bool conversion.
-    	 * Allows xpath_node to be used in a context where boolean variable is expected, such as 'if (node)'.
-    	 */
+    	// Safe bool conversion operator
 		operator unspecified_bool_type() const;
 		
     	// Borland C++ workaround
     	bool operator!() const;
 
-		/**
-		 * Compares two XPath nodes
-		 *
-		 * \param n - XPath node to compare to
-		 * \return comparison result
-		 */
+		// Comparison operators
 		bool operator==(const xpath_node& n) const;
-		
-		/**
-		 * Compares two XPath nodes
-		 *
-		 * \param n - XPath node to compare to
-		 * \return comparison result
-		 */
 		bool operator!=(const xpath_node& n) const;
 	};
 
@@ -2092,199 +969,87 @@ namespace pugi
 	bool PUGIXML_FUNCTION operator||(const xpath_node& lhs, bool rhs);
 #endif
 
-	/**
-	 * Not necessarily ordered constant collection of XPath nodes
-	 */
+	// A fixed-size collection of XPath nodes
 	class PUGIXML_CLASS xpath_node_set
 	{
 	public:
-		/// Collection type
+		// Collection type
 		enum type_t
 		{
-			type_unsorted,			///< Not ordered
-			type_sorted,			///< Sorted by document order (ascending)
-			type_sorted_reverse		///< Sorted by document order (descending)
+			type_unsorted,			// Not ordered
+			type_sorted,			// Sorted by document order (ascending)
+			type_sorted_reverse		// Sorted by document order (descending)
 		};
 		
-		/// Constant iterator type
+		// Constant iterator type
 		typedef const xpath_node* const_iterator;
 	
-	private:
-		type_t _type;
-		
-		xpath_node _storage;
-		
-		xpath_node* _begin;
-		xpath_node* _end;
-
-		void _assign(const_iterator begin, const_iterator end);
-		
-	public:
-		/**
-		 * Default constructor
-		 * Constructs empty set
-		 */
+		// Default constructor. Constructs empty set.
 		xpath_node_set();
 
-		/**
-		 * Constructor from contents
-		 */
+		// Constructs a set from iterator range; data is not checked for duplicates and is not sorted according to provided type, so be careful
 		xpath_node_set(const_iterator begin, const_iterator end, type_t type = type_unsorted);
 
-		/**
-         * Destructor
-         */
+		// Destructor
 		~xpath_node_set();
 		
-		/**
-		 * Copy constructor
-		 *
-		 * \param ns - set to copy
-		 */
+		// Copy constructor/assignment operator
 		xpath_node_set(const xpath_node_set& ns);
-
-		/**
-		 * Assignment operator
-		 *
-		 * \param ns - set to assign
-		 * \return self
-		 */
 		xpath_node_set& operator=(const xpath_node_set& ns);
 
-		/**
-		 * Get collection type
-		 *
-		 * \return collection type
-		 */
+		// Get collection type
 		type_t type() const;
 		
-		/**
-		 * Get collection size
-		 *
-		 * \return collection size
-		 */
+		// Get collection size
 		size_t size() const;
 
-		/**
-		 * Get element with the specified index
-		 *
-		 * \param index - requested index
-		 * \return element
-		 */
+        // Indexing operator
 		const xpath_node& operator[](size_t index) const;
 		
-		/**
-		 * Get begin constant iterator for collection
-		 *
-		 * \return begin constant iterator
-		 */
+		// Collection iterators
 		const_iterator begin() const;
-		
-		/**
-		 * Get end iterator for collection
-		 *
-		 * \return end iterator
-		 */
 		const_iterator end() const;
-		
-		/**
-		 * Sort the collection in ascending/descending order by document order
-		 *
-		 * \param reverse - whether to sort in ascending (false) or descending (true) order
-		 */
+
+		// Sort the collection in ascending/descending order by document order
 		void sort(bool reverse = false);
 		
-		/**
-		 * Get first node in the collection by document order
-		 *
-		 * \return first node by document order
-		 * \note set.first() is not equal to set[0], since operator[] does not take document order into account
-		 */
+		// Get first node in the collection by document order
 		xpath_node first() const;
 		
-		/**
-		 * Return true if collection is empty
-		 *
-		 * \return true if collection is empty, false otherwise
-		 */
+		// Check if collection is empty
 		bool empty() const;
+    
+	private:
+		type_t _type;
+		
+		xpath_node _storage;
+		
+		xpath_node* _begin;
+		xpath_node* _end;
+
+		void _assign(const_iterator begin, const_iterator end);
 	};
 #endif
 
 #ifndef PUGIXML_NO_STL
-	/**
-	 * Convert wide string to UTF8
-	 *
-	 * \param str - input wide string string
-	 * \return output UTF8 string
-	 */
+	// Convert wide string to UTF8
 	std::basic_string<char, std::char_traits<char>, std::allocator<char> > PUGIXML_FUNCTION as_utf8(const wchar_t* str);
 	
-	/**
-	 * Convert UTF8 to wide string
-	 *
-	 * \param str - input UTF8 string
-	 * \return output wide string string
-	 *
-	 * \deprecated This function is deprecated and will be removed in future versions; use as_wide instead
-	 */
-	PUGIXML_DEPRECATED std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > PUGIXML_FUNCTION as_utf16(const char* str);
-
-	/**
-	 * Convert UTF8 to wide string
-	 *
-	 * \param str - input UTF8 string
-	 * \return output wide string string
-	 */
+	// Convert UTF8 to wide string
 	std::basic_string<wchar_t, std::char_traits<wchar_t>, std::allocator<wchar_t> > PUGIXML_FUNCTION as_wide(const char* str);
 #endif
 
-	/**
-	 * Memory allocation function
-	 *
-	 * \param size - allocation size
-	 * \return pointer to allocated memory on success, NULL on failure
-	 */
+	// Memory allocation function interface; returns pointer to allocated memory or NULL on failure
 	typedef void* (*allocation_function)(size_t size);
 	
-	/**
-	 * Memory deallocation function
-	 *
-	 * \param ptr - pointer to memory previously allocated by allocation function
-	 */
+	// Memory deallocation function interface
     typedef void (*deallocation_function)(void* ptr);
 
-    /**
-     * Override default memory management functions
-     *
-     * All subsequent allocations/deallocations will be performed via supplied functions. Take care not to
-     * change memory management functions if any xml_document instances are still alive - this is considered
-     * undefined behaviour (expect crashes/memory damages/etc.).
-     *
-     * \param allocate - allocation function
-     * \param deallocate - deallocation function
-     * 
-     * \note XPath-related allocations, as well as allocations in functions that return std::string (xml_node::path, as_utf8, as_wide)
-     * are not performed via these functions.
-     * \note If you're using parse() with ownership transfer, you have to allocate the buffer you pass to parse() with allocation
-     * function you set via this function.
-     */
+    // Override default memory management functions. All subsequent allocations/deallocations will be performed via supplied functions.
     void PUGIXML_FUNCTION set_memory_management_functions(allocation_function allocate, deallocation_function deallocate);
     
-    /**
-     * Get current memory allocation function
-     *
-     * \return memory allocation function
-     * \see set_memory_management_functions
-     */
+    // Get current memory management functions
     allocation_function PUGIXML_FUNCTION get_memory_allocation_function();
-
-    /**
-     * Get current memory deallocation function
-     *
-     * \return memory deallocation function
-     * \see set_memory_management_functions
-     */
     deallocation_function PUGIXML_FUNCTION get_memory_deallocation_function();
 }