doc: Convert documentation to Doxygen

Automated conversion based on a few regexes.

xmlstring.c

@@ -40,13 +40,12 @@
  ************************************************************************/
 
 /**
- * xmlStrndup:
- * @cur:  the input xmlChar *
- * @len:  the len of @cur
+ * @param cur  the input xmlChar *
+ * @param len  the len of `cur`
  *
  * a strndup for array of xmlChar's
  *
- * Returns a new xmlChar * or NULL
+ * @returns a new xmlChar * or NULL
  */
 xmlChar *
 xmlStrndup(const xmlChar *cur, int len) {
@@ -63,14 +62,13 @@ xmlStrndup(const xmlChar *cur, int len) {
 }
 
 /**
- * xmlStrdup:
- * @cur:  the input xmlChar *
+ * @param cur  the input xmlChar *
  *
  * a strdup for array of xmlChar's. Since they are supposed to be
  * encoded in UTF-8 or an encoding with 8bit based chars, we assume
  * a termination mark of '0'.
  *
- * Returns a new xmlChar * or NULL
+ * @returns a new xmlChar * or NULL
  */
 xmlChar *
 xmlStrdup(const xmlChar *cur) {
@@ -82,13 +80,12 @@ xmlStrdup(const xmlChar *cur) {
 }
 
 /**
- * xmlCharStrndup:
- * @cur:  the input char *
- * @len:  the len of @cur
+ * @param cur  the input char *
+ * @param len  the len of `cur`
  *
  * a strndup for char's to xmlChar's
  *
- * Returns a new xmlChar * or NULL
+ * @returns a new xmlChar * or NULL
  */
 
 xmlChar *
@@ -111,12 +108,11 @@ xmlCharStrndup(const char *cur, int len) {
 }
 
 /**
- * xmlCharStrdup:
- * @cur:  the input char *
+ * @param cur  the input char *
  *
  * a strdup for char's to xmlChar's
  *
- * Returns a new xmlChar * or NULL
+ * @returns a new xmlChar * or NULL
  */
 
 xmlChar *
@@ -129,13 +125,12 @@ xmlCharStrdup(const char *cur) {
 }
 
 /**
- * xmlStrcmp:
- * @str1:  the first xmlChar *
- * @str2:  the second xmlChar *
+ * @param str1  the first xmlChar *
+ * @param str2  the second xmlChar *
  *
  * a strcmp for xmlChar's
  *
- * Returns the integer result of the comparison
+ * @returns the integer result of the comparison
  */
 
 int
@@ -155,14 +150,13 @@ xmlStrcmp(const xmlChar *str1, const xmlChar *str2) {
 }
 
 /**
- * xmlStrEqual:
- * @str1:  the first xmlChar *
- * @str2:  the second xmlChar *
+ * @param str1  the first xmlChar *
+ * @param str2  the second xmlChar *
  *
  * Check if both strings are equal of have same content.
  * Should be a bit more readable and faster than xmlStrcmp()
  *
- * Returns 1 if they are equal, 0 if they are different
+ * @returns 1 if they are equal, 0 if they are different
  */
 
 int
@@ -181,14 +175,13 @@ xmlStrEqual(const xmlChar *str1, const xmlChar *str2) {
 }
 
 /**
- * xmlStrQEqual:
- * @pref:  the prefix of the QName
- * @name:  the localname of the QName
- * @str:  the second xmlChar *
+ * @param pref  the prefix of the QName
+ * @param name  the localname of the QName
+ * @param str  the second xmlChar *
  *
  * Check if a QName is Equal to a given string
  *
- * Returns 1 if they are equal, 0 if they are different
+ * @returns 1 if they are equal, 0 if they are different
  */
 
 int
@@ -208,14 +201,13 @@ xmlStrQEqual(const xmlChar *pref, const xmlChar *name, const xmlChar *str) {
 }
 
 /**
- * xmlStrncmp:
- * @str1:  the first xmlChar *
- * @str2:  the second xmlChar *
- * @len:  the max comparison length
+ * @param str1  the first xmlChar *
+ * @param str2  the second xmlChar *
+ * @param len  the max comparison length
  *
  * a strncmp for xmlChar's
  *
- * Returns the integer result of the comparison
+ * @returns the integer result of the comparison
  */
 
 int
@@ -271,13 +263,12 @@ static const xmlChar casemap[256] = {
 };
 
 /**
- * xmlStrcasecmp:
- * @str1:  the first xmlChar *
- * @str2:  the second xmlChar *
+ * @param str1  the first xmlChar *
+ * @param str2  the second xmlChar *
  *
  * a strcasecmp for xmlChar's
  *
- * Returns the integer result of the comparison
+ * @returns the integer result of the comparison
  */
 
 int
@@ -295,14 +286,13 @@ xmlStrcasecmp(const xmlChar *str1, const xmlChar *str2) {
 }
 
 /**
- * xmlStrncasecmp:
- * @str1:  the first xmlChar *
- * @str2:  the second xmlChar *
- * @len:  the max comparison length
+ * @param str1  the first xmlChar *
+ * @param str2  the second xmlChar *
+ * @param len  the max comparison length
  *
  * a strncasecmp for xmlChar's
  *
- * Returns the integer result of the comparison
+ * @returns the integer result of the comparison
  */
 
 int
@@ -321,13 +311,12 @@ xmlStrncasecmp(const xmlChar *str1, const xmlChar *str2, int len) {
 }
 
 /**
- * xmlStrchr:
- * @str:  the xmlChar * array
- * @val:  the xmlChar to search
+ * @param str  the xmlChar * array
+ * @param val  the xmlChar to search
  *
  * a strchr for xmlChar's
  *
- * Returns the xmlChar * for the first occurrence or NULL.
+ * @returns the xmlChar * for the first occurrence or NULL.
  */
 
 const xmlChar *
@@ -341,13 +330,12 @@ xmlStrchr(const xmlChar *str, xmlChar val) {
 }
 
 /**
- * xmlStrstr:
- * @str:  the xmlChar * array (haystack)
- * @val:  the xmlChar to search (needle)
+ * @param str  the xmlChar * array (haystack)
+ * @param val  the xmlChar to search (needle)
  *
  * a strstr for xmlChar's
  *
- * Returns the xmlChar * for the first occurrence or NULL.
+ * @returns the xmlChar * for the first occurrence or NULL.
  */
 
 const xmlChar *
@@ -369,13 +357,12 @@ xmlStrstr(const xmlChar *str, const xmlChar *val) {
 }
 
 /**
- * xmlStrcasestr:
- * @str:  the xmlChar * array (haystack)
- * @val:  the xmlChar to search (needle)
+ * @param str  the xmlChar * array (haystack)
+ * @param val  the xmlChar to search (needle)
  *
  * a case-ignoring strstr for xmlChar's
  *
- * Returns the xmlChar * for the first occurrence or NULL.
+ * @returns the xmlChar * for the first occurrence or NULL.
  */
 
 const xmlChar *
@@ -396,14 +383,13 @@ xmlStrcasestr(const xmlChar *str, const xmlChar *val) {
 }
 
 /**
- * xmlStrsub:
- * @str:  the xmlChar * array (haystack)
- * @start:  the index of the first char (zero based)
- * @len:  the length of the substring
+ * @param str  the xmlChar * array (haystack)
+ * @param start  the index of the first char (zero based)
+ * @param len  the length of the substring
  *
  * Extract a substring of a given string
  *
- * Returns the xmlChar * for the first occurrence or NULL.
+ * @returns the xmlChar * for the first occurrence or NULL.
  */
 
 xmlChar *
@@ -423,12 +409,11 @@ xmlStrsub(const xmlChar *str, int start, int len) {
 }
 
 /**
- * xmlStrlen:
- * @str:  the xmlChar * array
+ * @param str  the xmlChar * array
  *
  * length of a xmlChar's string
  *
- * Returns the number of xmlChar contained in the ARRAY.
+ * @returns the number of xmlChar contained in the ARRAY.
  */
 
 int
@@ -438,16 +423,15 @@ xmlStrlen(const xmlChar *str) {
 }
 
 /**
- * xmlStrncat:
- * @cur:  the original xmlChar * array
- * @add:  the xmlChar * array added
- * @len:  the length of @add
+ * @param cur  the original xmlChar * array
+ * @param add  the xmlChar * array added
+ * @param len  the length of `add`
  *
- * a strncat for array of xmlChar's, it will extend @cur with the len
- * first bytes of @add. Note that if @len < 0 then this is an API error
+ * a strncat for array of xmlChar's, it will extend `cur` with the len
+ * 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 and should
+ * @returns a new xmlChar *, the original `cur` is reallocated and should
  * not be freed.
  */
 
@@ -477,16 +461,15 @@ xmlStrncat(xmlChar *cur, const xmlChar *add, int len) {
 }
 
 /**
- * xmlStrncatNew:
- * @str1:  first xmlChar string
- * @str2:  second xmlChar string
- * @len:  the len of @str2 or < 0
+ * @param str1  first xmlChar string
+ * @param str2  second xmlChar string
+ * @param len  the len of `str2` or < 0
  *
  * same as xmlStrncat, but creates a new string.  The original
- * two strings are not freed. If @len is < 0 then the length
+ * two strings are not freed. If `len` is < 0 then the length
  * will be calculated automatically.
  *
- * Returns a new xmlChar * or NULL
+ * @returns a new xmlChar * or NULL
  */
 xmlChar *
 xmlStrncatNew(const xmlChar *str1, const xmlChar *str2, int len) {
@@ -516,16 +499,15 @@ xmlStrncatNew(const xmlChar *str1, const xmlChar *str2, int len) {
 }
 
 /**
- * xmlStrcat:
- * @cur:  the original xmlChar * array
- * @add:  the xmlChar * array added
+ * @param cur  the original xmlChar * array
+ * @param add  the xmlChar * array added
  *
  * a strcat for array of xmlChar's. Since they are supposed to be
  * 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. The original
- * @cur is reallocated and should not be freed.
+ * @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) {
@@ -540,15 +522,14 @@ xmlStrcat(xmlChar *cur, const xmlChar *add) {
 }
 
 /**
- * xmlStrPrintf:
- * @buf:   the result buffer.
- * @len:   the result buffer length.
- * @msg:   the message with printf formatting.
+ * @param buf  the result buffer.
+ * @param len  the result buffer length.
+ * @param msg  the message with printf formatting.
  * @...:   extra parameters for the message.
  *
- * Formats @msg and places result into @buf.
+ * Formats `msg` and places result into `buf`.
  *
- * Returns the number of characters written to @buf or -1 if an error occurs.
+ * @returns the number of characters written to `buf` or -1 if an error occurs.
  */
 int
 xmlStrPrintf(xmlChar *buf, int len, const char *msg, ...) {
@@ -568,15 +549,14 @@ xmlStrPrintf(xmlChar *buf, int len, const char *msg, ...) {
 }
 
 /**
- * xmlStrVPrintf:
- * @buf:   the result buffer.
- * @len:   the result buffer length.
- * @msg:   the message with printf formatting.
- * @ap:    extra parameters for the message.
+ * @param buf  the result buffer.
+ * @param len  the result buffer length.
+ * @param msg  the message with printf formatting.
+ * @param ap  extra parameters for the message.
  *
- * Formats @msg and places result into @buf.
+ * Formats `msg` and places result into `buf`.
  *
- * Returns the number of characters written to @buf or -1 if an error occurs.
+ * @returns the number of characters written to `buf` or -1 if an error occurs.
  */
 int
 xmlStrVPrintf(xmlChar *buf, int len, const char *msg, va_list ap) {
@@ -593,15 +573,14 @@ xmlStrVPrintf(xmlChar *buf, int len, const char *msg, va_list ap) {
 }
 
 /**
- * xmlStrVASPrintf:
- * @out:  pointer to the resulting string
- * @maxSize:  maximum size of the output buffer
- * @msg:  printf format string
- * @ap:  arguments for format string
+ * @param out  pointer to the resulting string
+ * @param maxSize  maximum size of the output buffer
+ * @param msg  printf format string
+ * @param ap  arguments for format string
  *
  * Creates a newly allocated string according to format.
  *
- * Returns 0 on success, 1 if the result was truncated or on other
+ * @returns 0 on success, 1 if the result was truncated or on other
  * errors, -1 if a memory allocation failed.
  */
 int
@@ -711,15 +690,14 @@ xmlStrVASPrintf(xmlChar **out, int maxSize, const char *msg, va_list ap) {
 }
 
 /**
- * xmlStrASPrintf:
- * @out:  pointer to the resulting string
- * @maxSize:  maximum size of the output buffer
- * @msg:  printf format string
+ * @param out  pointer to the resulting string
+ * @param maxSize  maximum size of the output buffer
+ * @param msg  printf format string
  * @...:  arguments for format string
  *
  * See xmlStrVASPrintf.
  *
- * Returns 0 on success, 1 if the result was truncated or on other
+ * @returns 0 on success, 1 if the result was truncated or on other
  * errors, -1 if a memory allocation failed.
  */
 int
@@ -751,12 +729,11 @@ xmlStrASPrintf(xmlChar **out, int maxSize, const char *msg, ...) {
 
 
 /**
- * xmlUTF8Size:
- * @utf: pointer to the UTF8 character
+ * @param utf  pointer to the UTF8 character
  *
  * calculates the internal size of a UTF8 character
  *
- * returns the numbers of bytes in the character, -1 on format error
+ * @returns the numbers of bytes in the character, -1 on format error
  */
 int
 xmlUTF8Size(const xmlChar *utf) {
@@ -781,13 +758,12 @@ xmlUTF8Size(const xmlChar *utf) {
 }
 
 /**
- * xmlUTF8Charcmp:
- * @utf1: pointer to first UTF8 char
- * @utf2: pointer to second UTF8 char
+ * @param utf1  pointer to first UTF8 char
+ * @param utf2  pointer to second UTF8 char
  *
  * compares the two UCS4 values
  *
- * returns result of the compare as with xmlStrncmp
+ * @returns result of the compare as with xmlStrncmp
  */
 int
 xmlUTF8Charcmp(const xmlChar *utf1, const xmlChar *utf2) {
@@ -801,13 +777,12 @@ xmlUTF8Charcmp(const xmlChar *utf1, const xmlChar *utf2) {
 }
 
 /**
- * xmlUTF8Strlen:
- * @utf:  a sequence of UTF-8 encoded bytes
+ * @param utf  a sequence of UTF-8 encoded bytes
  *
  * compute the length of an UTF8 string, it doesn't do a full UTF8
  * checking of the content of the string.
  *
- * Returns the number of characters in the string or -1 in case of error
+ * @returns the number of characters in the string or -1 in case of error
  */
 int
 xmlUTF8Strlen(const xmlChar *utf) {
@@ -842,15 +817,14 @@ xmlUTF8Strlen(const xmlChar *utf) {
 }
 
 /**
- * xmlGetUTF8Char:
- * @utf:  a sequence of UTF-8 encoded bytes
- * @len:  a pointer to the minimum number of bytes present in
+ * @param utf  a sequence of UTF-8 encoded bytes
+ * @param len  a pointer to the minimum number of bytes present in
  *        the sequence.  This is used to assure the next character
  *        is completely contained within the sequence.
  *
- * Read the first UTF8 character from @utf
+ * Read the first UTF8 character from `utf`
  *
- * Returns the char value or -1 in case of error, and sets *len to
+ * @returns the char value or -1 in case of error, and sets *len to
  *        the actual number of bytes consumed (0 in case of error)
  */
 int
@@ -912,17 +886,16 @@ error:
 }
 
 /**
- * xmlCheckUTF8:
- * @utf: Pointer to putative UTF-8 encoded string.
+ * @param utf  Pointer to putative UTF-8 encoded string.
  *
- * Checks @utf for being valid UTF-8. @utf is assumed to be
+ * Checks `utf` for being valid UTF-8. `utf` is assumed to be
  * null-terminated. This function is not super-strict, as it will
  * allow longer UTF-8 sequences than necessary. Note that Java is
  * capable of producing these sequences if provoked. Also note, this
  * routine checks for the 4-byte maximum size, but does not check for
  * 0x10ffff maximum value.
  *
- * Return value: true if @utf is valid.
+ * @returns value: true if `utf` is valid.
  **/
 int
 xmlCheckUTF8(const unsigned char *utf)
@@ -967,14 +940,13 @@ xmlCheckUTF8(const unsigned char *utf)
 }
 
 /**
- * xmlUTF8Strsize:
- * @utf:  a sequence of UTF-8 encoded bytes
- * @len:  the number of characters in the array
+ * @param utf  a sequence of UTF-8 encoded bytes
+ * @param len  the number of characters in the array
  *
  * storage size of an UTF8 string
  * the behaviour is not guaranteed if the input string is not UTF-8
  *
- * Returns the storage size of
+ * @returns the storage size of
  * the first 'len' characters of ARRAY
  */
 
@@ -1006,13 +978,12 @@ xmlUTF8Strsize(const xmlChar *utf, int len) {
 
 
 /**
- * xmlUTF8Strndup:
- * @utf:  the input UTF8 *
- * @len:  the len of @utf (in chars)
+ * @param utf  the input UTF8 *
+ * @param len  the len of `utf` (in chars)
  *
  * a strndup for array of UTF8's
  *
- * Returns a new UTF8 * or NULL
+ * @returns a new UTF8 * or NULL
  */
 xmlChar *
 xmlUTF8Strndup(const xmlChar *utf, int len) {
@@ -1031,14 +1002,13 @@ xmlUTF8Strndup(const xmlChar *utf, int len) {
 }
 
 /**
- * xmlUTF8Strpos:
- * @utf:  the input UTF8 *
- * @pos:  the position of the desired UTF8 char (in chars)
+ * @param utf  the input UTF8 *
+ * @param pos  the position of the desired UTF8 char (in chars)
  *
  * a function to provide the equivalent of fetching a
  * character from a string array
  *
- * Returns a pointer to the UTF8 character or NULL
+ * @returns a pointer to the UTF8 character or NULL
  */
 const xmlChar *
 xmlUTF8Strpos(const xmlChar *utf, int pos) {
@@ -1065,13 +1035,12 @@ xmlUTF8Strpos(const xmlChar *utf, int pos) {
 }
 
 /**
- * xmlUTF8Strloc:
- * @utf:  the input UTF8 *
- * @utfchar:  the UTF8 character to be found
+ * @param utf  the input UTF8 *
+ * @param utfchar  the UTF8 character to be found
  *
  * a function to provide the relative location of a UTF8 char
  *
- * Returns the relative character position of the desired char
+ * @returns the relative character position of the desired char
  * or -1 if not found
  */
 int
@@ -1100,15 +1069,14 @@ xmlUTF8Strloc(const xmlChar *utf, const xmlChar *utfchar) {
     return(-1);
 }
 /**
- * xmlUTF8Strsub:
- * @utf:  a sequence of UTF-8 encoded bytes
- * @start: relative pos of first char
- * @len:   total number to copy
+ * @param utf  a sequence of UTF-8 encoded bytes
+ * @param start  relative pos of first char
+ * @param len  total number to copy
  *
  * Create a substring from a given UTF-8 string
  * Note:  positions are given in units of UTF-8 chars
  *
- * Returns a pointer to a newly created string or NULL if the
+ * @returns a pointer to a newly created string or NULL if the
  * start index is out of bounds or a memory allocation failed.
  * If len is too large, the result is truncated.
  */
@@ -1144,13 +1112,12 @@ xmlUTF8Strsub(const xmlChar *utf, int start, int len) {
 }
 
 /**
- * xmlEscapeFormatString:
- * @msg:  a pointer to the string in which to escape '%' characters.
+ * @param msg  a pointer to the string in which to escape '%' characters.
  * Must be a heap-allocated buffer created by libxml2 that may be
  * returned, or that may be freed and replaced.
  *
  * Replaces the string pointed to by 'msg' with an escaped string.
- * Returns the same string with all '%' characters escaped.
+ * @returns the same string with all '%' characters escaped.
  */
 xmlChar *
 xmlEscapeFormatString(xmlChar **msg)