diff --git a/interface/wx/xml/xml.h b/interface/wx/xml/xml.h
index 114711e518..93ed2943fd 100644
--- a/interface/wx/xml/xml.h
+++ b/interface/wx/xml/xml.h
@@ -30,26 +30,41 @@ enum wxXmlNodeType
 
     Represents a node in an XML document. See wxXmlDocument.
 
-    Node has a name and may have content and attributes.
+    Each node is named and depending on the node type it may also hold content
+    or be given attributes.
 
-    Most common node types are @c wxXML_TEXT_NODE (name and attributes are irrelevant)
-    and @c wxXML_ELEMENT_NODE.
+    The two most common node types are @c wxXML_ELEMENT_NODE and
+    @c wxXML_TEXT_NODE. @c wxXML_ELEMENT_NODE represents a pair of XML element
+    tags, whilst @c wxXML_TEXT_NODE represents the text value that can belong
+    to the element.
 
-    Example: in <tt>\<title\>hi\</title\></tt> there is an element with the name
-    @c title and irrelevant content and one child of type @c wxXML_TEXT_NODE
-    with @c hi as content.
+    A @c wxXML_ELEMENT_NODE has a title, and optionally attributes, but does not
+    have any content. A @c wxXML_TEXT_NODE does not have a title or attributes
+    but should normally have content.
 
-    The @c wxXML_PI_NODE type sets the name to the PI target and the contents to
+    For example: in the XML fragment <tt>\<title\>hi\</title\></tt> there is an
+    element node with the name @c title and a single text node child with the
+    text @c hi as content.
+
+    A @c wxXML_PI_NODE represents a Processing Instruction (PI) node with
+    the name parameter set as the target and the contents parameter set as
     the instructions. Note that whilst the PI instructions are often in the form
-    of pseudo-attributes these do not use the nodes attribute system. It is the users
-    responsibility to code and decode the instruction text.
+    of pseudo-attributes, these do not use the node's attribute member. It is
+    the user's responsibility to code and decode the PI instruction text.
 
     The @c wxXML_DOCUMENT_TYPE_NODE is not implemented at this time. Instead,
-    get and set the DOCTYPE values using the wxXmlDocument class.
+    you should get and set the DOCTYPE values using the wxXmlDocument class.
 
     If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
     wxXmlDocument::Load (default is UTF-8).
 
+    @Note
+    Once a wxXmlNode has been added to a wxXmlDocument it becomes owned by the
+    document and this has two implications. Firstly, the wxXmlDocument takes
+    responsibility for deleting the node so the user should not @c delete it;
+    and secondly, a wxXmlNode must always be created on the heap and never on
+    the stack.
+
     @library{wxxml}
     @category{xml}
 
@@ -59,14 +74,16 @@ class wxXmlNode
 {
 public:
     /**
-        Creates this XML node and eventually insert it into an existing XML tree.
+        Creates this XML node and inserts it into the XML tree as a child of
+        the specified parent. Once added, the XML tree takes ownership of this
+        object and there is no need to delete it.
 
         @param parent
             The parent node to which append this node instance.
             If this argument is @NULL this new node will be floating and it can
             be appended later to another one using the AddChild() or InsertChild()
-            functions. Otherwise the child is already added to the XML tree by
-            this constructor and it shouldn't be done again.
+            functions. Otherwise the child is added to the XML tree by this
+            constructor and it shouldn't be done again.
         @param type
             One of the ::wxXmlNodeType enumeration value.
         @param name
@@ -130,7 +147,8 @@ public:
     virtual void AddAttribute(wxXmlAttribute* attr);
 
     /**
-        Adds node @a child as the last child of this node.
+        Adds node @a child as the last child of this node. Once added, the XML
+        tree takes ownership of this object and there is no need to delete it.
 
         @note
         Note that this function works in O(n) time where @e n is the number
@@ -257,7 +275,8 @@ public:
 
     /**
         Inserts the @a child node immediately before @a followingNode in the
-        children list.
+        children list. Once inserted, the XML tree takes ownership of the new
+        child and there is no need to delete it.
 
         @return @true if @a followingNode has been found and the @a child
                 node has been inserted.
@@ -274,7 +293,8 @@ public:
 
     /**
         Inserts the @a child node immediately after @a precedingNode in the
-        children list.
+        children list. Once inserted, the XML tree takes ownership of the new
+        child and there is no need to delete it.
 
         @return @true if @a precedingNode has been found and the @a child
                 node has been inserted.
@@ -529,10 +549,10 @@ public:
 
 
 
-//* special indentation value for wxXmlDocument::Save
+//* Special indentation value for wxXmlDocument::Save.
 #define wxXML_NO_INDENTATION           (-1)
 
-//* flags for wxXmlDocument::Load
+//* Flags for wxXmlDocument::Load.
 enum wxXmlDocumentLoadFlag
 {
     wxXMLDOC_NONE,
@@ -549,6 +569,16 @@ enum wxXmlDocumentLoadFlag
     wxXmlDocument internally uses the expat library which comes with wxWidgets to
     parse the given stream.
 
+    A wxXmlDocument is in fact a list of wxXmlNode organised into a structure
+    that reflects the XML tree being represented by the document.
+
+    @note
+    Ownership is passed to the XML tree as each wxXmlNode is added to it,
+    and this has two implications. Firstly, the wxXmlDocument takes
+    responsibility for deleting the node so the user should not @c delete it;
+    and secondly, a wxXmlNode must always be created on the heap and never
+    on the stack.
+
     A simple example of using XML classes is:
 
     @code
@@ -556,17 +586,19 @@ enum wxXmlDocumentLoadFlag
     if (!doc.Load("myfile.xml"))
         return false;
 
-    // start processing the XML file
+    // Start processing the XML file.
     if (doc.GetRoot()->GetName() != "myroot-node")
         return false;
 
-    // examine prologue
+    // Examine prologue.
     wxXmlNode *prolog = doc.GetDocumentNode()->GetChildren();
-    while (prolog) {
+    while (prolog)
+    {
 
-        if (prolog->GetType() == wxXML_PI_NODE && prolog->GetName() == "target") {
+        if (prolog->GetType() == wxXML_PI_NODE && prolog->GetName() == "target")
+        {
 
-            // process Process Instruction contents
+            // Process Process Instruction (PI) contents.
             wxString pi = prolog->GetContent();
 
             ...
@@ -575,26 +607,27 @@ enum wxXmlDocumentLoadFlag
     }
 
     wxXmlNode *child = doc.GetRoot()->GetChildren();
-    while (child) {
-
-        if (child->GetName() == "tag1") {
-
-            // process text enclosed by tag1/tag1
+    while (child)
+    {
+        if (child->GetName() == "tag1")
+        {
+            // Process text enclosed by tag1/tag1.
             wxString content = child->GetNodeContent();
 
             ...
 
-            // process attributes of tag1
+            // Process attributes of tag1.
             wxString attrvalue1 =
                 child->GetAttribute("attr1", "default-value");
             wxString attrvalue2 =
                 child->GetAttribute("attr2", "default-value");
 
             ...
+        }
+        else if (child->GetName() == "tag2")
+        {
 
-        } else if (child->GetName() == "tag2") {
-
-            // process tag2 ...
+            // Process tag2 ...
         }
 
         child = child->GetNext();
@@ -603,7 +636,7 @@ enum wxXmlDocumentLoadFlag
 
     Note that if you want to preserve the original formatting of the loaded file
     including whitespaces and indentation, you need to turn off whitespace-only
-    textnode removal and automatic indentation:
+    textnode removal and automatic indentation. For example:
 
     @code
     wxXmlDocument doc;
@@ -622,6 +655,40 @@ enum wxXmlDocumentLoadFlag
     doc.Save("myfile2.xml");  // myfile2.xml != myfile.xml
     @endcode
 
+    wxXmlDocument can also be used to create documents. The following code gives
+    an example of creating a simple document with two nested element nodes, the
+    second of which has an attribute, and a text node. It also demonstrates
+    how to write the resulting output to a wxString:
+
+    @code
+    // Create a document and add the root node.
+    wxXmlDocument xmlDoc;
+
+    wxXmlNode* root = new wxXmlNode(NULL, wxXML_ELEMENT_NODE, "Root");
+    xmlDoc.SetRoot(root);
+
+    // Add some XML.
+    wxXmlNode* library = new wxXmlNode (root, wxXML_ELEMENT_NODE, "Library");
+    library->AddAttribute("type", "CrossPlatformList");
+    wxXmlNode* name = new wxXmlNode(library, wxXML_ELEMENT_NODE, "Name");
+    name->AddChild(new wxXmlNode(wxXML_TEXT_NODE, "", "wxWidgets"));
+
+    // Write the output to a wxString.
+    wxStringOutputStream stream;
+    xmlDoc.Save(stream);
+    @endcode
+
+    This will produce a document that looks something like the following:
+
+    @code
+    <?xml version="1.0" encoding="UTF-8"?>
+    <Root>
+      <Library type="CrossPlatformList">
+        <Name>wxWidgets</Name>
+      </Library>
+    </Root>
+    @endcode
+
     If the root name value of the DOCTYPE is set, either by loading a file with a
     DOCTYPE declaration or by setting it directly with the SetDoctype member,
     then a DOCTYPE declaration will be added immediately after the XML declaration.