[libxml++] Node: Replace remove_child() by remove_node()

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 6ea9dbc728a07444db28f62e059599927b114eac
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Tue Sep 29 15:57:47 2015 +0200

    Node: Replace remove_child() by remove_node()
    
    * libxml++/nodes/node.[h|cc]: Replace remove_child() by the static
    remove_node(). Improve the documentation of remove_node() and the destructor.
    Bug #754673

 libxml++/nodes/node.cc |    8 +++++---
 libxml++/nodes/node.h  |   23 +++++++++++++++++++----
 2 files changed, 24 insertions(+), 7 deletions(-)
---
diff --git a/libxml++/nodes/node.cc b/libxml++/nodes/node.cc
index d8f54e6..16cb55f 100644
--- a/libxml++/nodes/node.cc
+++ b/libxml++/nodes/node.cc
@@ -303,14 +303,16 @@ Node::const_NodeList Node::get_children(const Glib::ustring& name) const
   return get_children_common<const_NodeList>(name, impl_->children);
 }
 
-void Node::remove_child(Node* node)
+//static
+void Node::remove_node(Node* node)
 {
-  //TODO: Allow a node to be removed without deleting it, to allow it to be moved?
+  //TODO: Allow a node to be disconnected from its parent without deleting it,
+  // to allow it to be moved?
   //This would require a more complex memory management API.
   if (!node)
     return;
   auto cnode = node->cobj();
-  Node::free_wrappers(cnode); //This delete the C++ node (not this) itself.
+  Node::free_wrappers(cnode); // This deletes the C++ node.
   xmlUnlinkNode(cnode);
   xmlFreeNode(cnode);
 }
diff --git a/libxml++/nodes/node.h b/libxml++/nodes/node.h
index 02084eb..8966b8d 100644
--- a/libxml++/nodes/node.h
+++ b/libxml++/nodes/node.h
@@ -43,7 +43,10 @@ enum XPathResultType
 };
 
 /** Represents XML Nodes.
- * You should never new or delete Nodes. The Parser will create and manage them for you.
+ *
+ * You should never new and delete Nodes. The Parser will create and
+ * manage them for you. Furthermore, Document and Element have methods for
+ * adding Nodes to a Document.
  */
 class Node : public NonCopyable
 {
@@ -57,6 +60,11 @@ public:
   /** @throws xmlpp::internal_error If @a node is <tt>0</tt>.
    */
   explicit Node(_xmlNode* node);
+
+  /** Destructor.
+   * Does not destroy the underlying xmlNode. The xmlNode is owned by a xmlDoc
+   * document. If you want to also destroy the xmlNode, use remove_node().
+   */
   ~Node() override;
 
   /** Get the name of this node.
@@ -151,10 +159,17 @@ public:
    */
   const_NodeList get_children(const Glib::ustring& name = Glib::ustring()) const;
 
-  /** Remove the child node.
-   * @param node The child node to remove. This Node will be deleted and therefore unusable after calling 
this method.
+  /** Remove a node and its children.
+   *
+   * The node is disconnected from its parent. The underlying libxml xmlNode
+   * instances are also removed.
+   *
+   * @newin{3,0} Replaces remove_child()
+   *
+   * @param node The node to remove. This Node and all its descendants will be
+   *             deleted and therefore unusable after calling this method.
    */
-  void remove_child(Node* node);
+  static void remove_node(Node* node);
 
   /** Import node(s) from another document under this node, without affecting the source node.
    *