[libxml2] Improve documentation of tree manipulation API

[Nick Wellnhofer <nwellnhof src gnome org>]

commit 39745c927af8904468a2fff55dcb414e5942ba78
Author: Nick Wellnhofer <wellnhofer aevum de>
Date:   Tue Jul 19 21:23:44 2022 +0200

    Improve documentation of tree manipulation API
    
    - Discourage use of node constructors without document.
    - Mention that xmlReconciliateNs is crucial when moving nodes from one
      document to another.

 tree.c | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)
---
diff --git a/tree.c b/tree.c
index da34685b..b53fa37e 100644
--- a/tree.c
+++ b/tree.c
@@ -2221,7 +2221,8 @@ xmlNewDocPI(xmlDocPtr doc, const xmlChar *name, const xmlChar *content) {
  * @content:  the PI content
  *
  * Creation of a processing instruction element.
- * Use xmlDocNewPI preferably to get string interning
+ *
+ * Use of this function is DISCOURAGED in favor of xmlNewDocPI.
  *
  * Returns a pointer to the new node object.
  */
@@ -2237,6 +2238,8 @@ xmlNewPI(const xmlChar *name, const xmlChar *content) {
  *
  * Creation of a new node element. @ns is optional (NULL).
  *
+ * Use of this function is DISCOURAGED in favor of xmlNewDocNode.
+ *
  * Returns a pointer to the new node object. Uses xmlStrdup() to make
  * copy of @name.
  */
@@ -2278,6 +2281,8 @@ xmlNewNode(xmlNsPtr ns, const xmlChar *name) {
  *
  * Creation of a new node element. @ns is optional (NULL).
  *
+ * Use of this function is DISCOURAGED in favor of xmlNewDocNodeEatName.
+ *
  * Returns a pointer to the new node object, with pointer @name as
  * new node's name. Use xmlNewNode() if a copy of @name string is
  * is needed as new node's name.
@@ -2452,6 +2457,9 @@ xmlNewDocFragment(xmlDocPtr doc) {
  * @content:  the text content
  *
  * Creation of a new text node.
+ *
+ * Use of this function is DISCOURAGED in favor of xmlNewDocText.
+ *
  * Returns a pointer to the new node object.
  */
 xmlNodePtr
@@ -2682,6 +2690,8 @@ xmlNewDocText(const xmlDoc *doc, const xmlChar *content) {
  * @content:  the text content
  * @len:  the text len.
  *
+ * Use of this function is DISCOURAGED in favor of xmlNewDocTextLen.
+ *
  * Creation of a new text node with an extra parameter for the content's length
  * Returns a pointer to the new node object.
  */
@@ -2733,6 +2743,8 @@ xmlNewDocTextLen(xmlDocPtr doc, const xmlChar *content, int len) {
  * xmlNewComment:
  * @content:  the comment content
  *
+ * Use of this function is DISCOURAGED in favor of xmlNewDocComment.
+ *
  * Creation of a new node containing a comment.
  * Returns a pointer to the new node object.
  */
@@ -3003,6 +3015,8 @@ xmlNewChild(xmlNodePtr parent, xmlNsPtr ns,
  * When inserting after @cur, @prev is passed as @cur.
  * If an existing attribute is found it is destroyed prior to adding @prop.
  *
+ * See the note regarding namespaces in xmlAddChild.
+ *
  * Returns the attribute being inserted or NULL in case of error.
  */
 static xmlNodePtr
@@ -3055,6 +3069,8 @@ xmlAddPropSibling(xmlNodePtr prev, xmlNodePtr cur, xmlNodePtr prop) {
  * If the new node is ATTRIBUTE, it is added into properties instead of children.
  * If there is an attribute with equal name, it is first destroyed.
  *
+ * See the note regarding namespaces in xmlAddChild.
+ *
  * Returns the new node or NULL in case of error.
  */
 xmlNodePtr
@@ -3133,6 +3149,8 @@ xmlAddNextSibling(xmlNodePtr cur, xmlNodePtr elem) {
  * If the new node is ATTRIBUTE, it is added into properties instead of children.
  * If there is an attribute with equal name, it is first destroyed.
  *
+ * See the note regarding namespaces in xmlAddChild.
+ *
  * Returns the new node or NULL in case of error.
  */
 xmlNodePtr
@@ -3209,6 +3227,8 @@ xmlAddPrevSibling(xmlNodePtr cur, xmlNodePtr elem) {
  * If the new element was already inserted in a document it is
  * first unlinked from its existing context.
  *
+ * See the note regarding namespaces in xmlAddChild.
+ *
  * Returns the new element or NULL in case of error.
  */
 xmlNodePtr
@@ -3285,6 +3305,8 @@ xmlAddSibling(xmlNodePtr cur, xmlNodePtr elem) {
  * Add a list of node at the end of the child list of the parent
  * merging adjacent TEXT nodes (@cur may be freed)
  *
+ * See the note regarding namespaces in xmlAddChild.
+ *
  * Returns the last child or NULL in case of error.
  */
 xmlNodePtr
@@ -3371,6 +3393,12 @@ xmlAddChildList(xmlNodePtr parent, xmlNodePtr cur) {
  * If the new node is ATTRIBUTE, it is added into properties instead of children.
  * If there is an attribute with equal name, it is first destroyed.
  *
+ * All tree manipulation functions can safely move nodes within a document.
+ * But when moving nodes from one document to another, references to
+ * namespaces in element or attribute nodes are NOT fixed. In this case,
+ * you MUST call xmlReconciliateNs after the move operation to avoid
+ * memory errors.
+ *
  * Returns the child or NULL in case of error.
  */
 xmlNodePtr
@@ -3939,6 +3967,8 @@ xmlUnlinkNode(xmlNodePtr cur) {
  * at the same place. If @cur was already inserted in a document it is
  * first unlinked from its existing context.
  *
+ * See the note regarding namespaces in xmlAddChild.
+ *
  * Returns the @old node
  */
 xmlNodePtr