[libxml2] Documentation fixes

[Nick Wellnhofer <nwellnhof src gnome org>]

commit 5a0ae66d7202619d493985537818e052d9d1239f
Author: Nick Wellnhofer <wellnhofer aevum de>
Date:   Sat Jun 17 23:20:38 2017 +0200

    Documentation fixes
    
    Fixes bug 347465, bug 599433, bug 624550, bug 698253.

 tree.c      |    6 +++---
 xmlIO.c     |    2 +-
 xmlreader.c |    2 +-
 xmlstring.c |    7 ++++---
 4 files changed, 9 insertions(+), 8 deletions(-)
---
diff --git a/tree.c b/tree.c
index e154ec0..572185e 100644
--- a/tree.c
+++ b/tree.c
@@ -254,10 +254,10 @@ xmlBuildQName(const xmlChar *ncname, const xmlChar *prefix,
  *
  * [NS 7] LocalPart ::= NCName
  *
- * Returns NULL if not a QName, otherwise the local part, and prefix
- *   is updated to get the Prefix if any.
+ * Returns NULL if the name doesn't have a prefix. Otherwise, returns the
+ * local part, and prefix is updated to get the Prefix. Both the return value
+ * and the prefix must be freed by the caller.
  */
-
 xmlChar *
 xmlSplitQName2(const xmlChar *name, xmlChar **prefix) {
     int len = 0;
diff --git a/xmlIO.c b/xmlIO.c
index 14b3c15..c699d52 100644
--- a/xmlIO.c
+++ b/xmlIO.c
@@ -1286,7 +1286,7 @@ xmlGzfileOpenW (const char *filename, int compression) {
  *
  * Read @len bytes to @buffer from the compressed I/O channel.
  *
- * Returns the number of bytes written
+ * Returns the number of bytes read.
  */
 static int
 xmlGzfileRead (void * context, char * buffer, int len) {
diff --git a/xmlreader.c b/xmlreader.c
index f285790..34c4c6b 100644
--- a/xmlreader.c
+++ b/xmlreader.c
@@ -3982,7 +3982,7 @@ xmlTextReaderPreserve(xmlTextReaderPtr reader) {
  * pattern. The caller must also use xmlTextReaderCurrentDoc() to
  * keep an handle on the resulting document once parsing has finished
  *
- * Returns a positive number in case of success and -1 in case of error
+ * Returns a non-negative number in case of success and -1 in case of error
  */
 int
 xmlTextReaderPreservePattern(xmlTextReaderPtr reader, const xmlChar *pattern,
diff --git a/xmlstring.c b/xmlstring.c
index ed2baf0..8d2e06f 100644
--- a/xmlstring.c
+++ b/xmlstring.c
@@ -440,8 +440,8 @@ xmlStrlen(const xmlChar *str) {
  * first bytes of @add. Note that if @len < 0 then this is an API error
  * and NULL will be returned.
  *
- * Returns a new xmlChar *, the original @cur is reallocated if needed
- * and should not be freed
+ * Returns a new xmlChar *, the original @cur is reallocated and should
+ * not be freed.
  */
 
 xmlChar *
@@ -519,7 +519,8 @@ xmlStrncatNew(const xmlChar *str1, const xmlChar *str2, int len) {
  * encoded in UTF-8 or an encoding with 8bit based chars, we assume
  * a termination mark of '0'.
  *
- * Returns a new xmlChar * containing the concatenated string.
+ * Returns a new xmlChar * containing the concatenated string. The original
+ * @cur is reallocated and should not be freed.
  */
 xmlChar *
 xmlStrcat(xmlChar *cur, const xmlChar *add) {