doc: Fix documentation

buf.c

@@ -622,6 +622,7 @@ xmlBufFromBuffer(xmlBufferPtr buffer) {
 /**
  * xmlBufBackToBuffer:
  * @buf: new buffer wrapping the old one
+ * @ret: old buffer
  *
  * Function to be called once internal processing had been done to
  * update back the buffer provided by the user. This can lead to
@@ -629,7 +630,7 @@ xmlBufFromBuffer(xmlBufferPtr buffer) {
  * than what an xmlBuffer can support on 64 bits (INT_MAX)
  * The xmlBufPtr @buf wrapper is deallocated by this call in any case.
  *
- * Returns the old xmlBufferPtr unless the call failed and NULL is returned
+ * Returns 0 on success, -1 on error.
  */
 int
 xmlBufBackToBuffer(xmlBufPtr buf, xmlBufferPtr ret) {

entities.c

@@ -517,6 +517,17 @@ xmlGetDocEntity(const xmlDoc *doc, const xmlChar *name) {
     return(xmlGetPredefinedEntity(name));
 }
 
+/*
+ * xmlSerializeHexCharRef:
+ * @buf:  a char buffer
+ * @val:  a codepoint
+ *
+ * Serializes a hex char ref like  
+ *
+ * Writes at most 9 bytes. Does not include a terminating zero byte.
+ *
+ * Returns the number of bytes written.
+ */
 int
 xmlSerializeHexCharRef(char *buf, int val) {
     char *out = buf;
@@ -554,6 +565,17 @@ xmlSerializeHexCharRef(char *buf, int val) {
     return(out - buf);
 }
 
+/*
+ * xmlSerializeDecCharRef:
+ * @buf:  a char buffer
+ * @val:  a codepoint
+ *
+ * Serializes a decimal char ref like &
+ *
+ * Writes at most 10 bytes. Does not include a terminating zero byte.
+ *
+ * Returns the number of bytes written.
+ */
 int
 xmlSerializeDecCharRef(char *buf, int val) {
     char *out = buf;
@@ -593,6 +615,21 @@ static const char xmlEscapeSafe[128] = {
     1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1
 };
 
+/*
+ * xmlEscapeText:
+ * @text:  input text
+ * @flags:  XML_ESCAPE flags
+ *
+ * Escapes certain characters with char refs.
+ *
+ * XML_ESCAPE_ATTR: for attribute content.
+ * XML_ESCAPE_NON_ASCII: escape non-ASCII chars.
+ * XML_ESCAPE_HTML: for HTML content.
+ * XML_ESCAPE_QUOT: escape double quotes.
+ * XML_ESCAPE_ALLOW_INVALID: allow invalid characters.
+ *
+ * Returns an escaped string or NULL if a memory allocation failed.
+ */
 xmlChar *
 xmlEscapeText(const xmlChar *text, int flags) {
     const xmlChar *cur;
@@ -751,7 +788,7 @@ xmlEscapeText(const xmlChar *text, int flags) {
  * xmlEncodeEntitiesInternal:
  * @doc:  the document containing the string
  * @input:  A string to convert to XML.
- * @attr: are we handling an attribute value
+ * @flags:  XML_ESCAPE flags
  *
  * Do a global encoding of a string, replacing the predefined entities
  * and non ASCII values with their entities and CharRef counterparts.

error.c

@@ -20,6 +20,13 @@
 #include "private/globals.h"
 #include "private/string.h"
 
+/**
+ * xmlIsCatastrophicError:
+ * @level:  error level
+ * @code:  error code
+ *
+ * Returns true if an error is catastrophic.
+ */
 int
 xmlIsCatastrophicError(int level, int code) {
     int fatal = 0;
@@ -774,7 +781,7 @@ xmlVRaiseError(xmlStructuredErrorFunc schannel,
  * @channel: the old callback channel
  * @data: the callback data
  * @ctx: the parser context or NULL
- * @nod: the node or NULL
+ * @node: the node or NULL
  * @domain: the domain for the error
  * @code: the code for the error
  * @level: the xmlErrorLevel for the error
@@ -1353,11 +1360,25 @@ xmlErrString(xmlParserErrors code) {
     return(errmsg);
 }
 
+/**
+ * xmlVPrintErrorMessage:
+ * @fmt:  printf format string
+ * @ap:  arguments
+ *
+ * Prints to stderr.
+ */
 void
 xmlVPrintErrorMessage(const char *fmt, va_list ap) {
     vfprintf(stderr, fmt, ap);
 }
 
+/**
+ * xmlPrintErrorMessage:
+ * @fmt:  printf format string
+ * @...:  arguments
+ *
+ * Prints to stderr.
+ */
 void
 xmlPrintErrorMessage(const char *fmt, ...) {
     va_list ap;
@@ -1367,6 +1388,13 @@ xmlPrintErrorMessage(const char *fmt, ...) {
     va_end(ap);
 }
 
+/**
+ * xmlAbort:
+ * @fmt:  printf format string
+ * @...:  arguments
+ *
+ * Print message to stderr and abort.
+ */
 void
 xmlAbort(const char *fmt, ...) {
     va_list ap;

globals.c

@@ -981,6 +981,11 @@ xmlCheckThreadLocalStorage(void) {
     return(0);
 }
 
+/**
+ * xmlGetLastErrorInternal:
+ *
+ * Returns a pointer to the global error struct.
+ */
 xmlError *
 xmlGetLastErrorInternal(void) {
 #ifdef LIBXML_THREAD_ENABLED

parser.c

@@ -10656,7 +10656,7 @@ xmlParseXMLDecl(xmlParserCtxtPtr ctxt) {
 
 /**
  * xmlCtxtGetVersion:
- * ctxt:  parser context
+ * @ctxt:  parser context
  *
  * Available since 2.14.0.
  *
@@ -10672,7 +10672,7 @@ xmlCtxtGetVersion(xmlParserCtxtPtr ctxt) {
 
 /**
  * xmlCtxtGetStandalone:
- * ctxt:  parser context
+ * @ctxt:  parser context
  *
  * Available since 2.14.0.
  *

parserInternals.c

@@ -257,6 +257,12 @@ xmlCtxtErrIO(xmlParserCtxtPtr ctxt, int code, const char *uri)
                msg, str1, str2);
 }
 
+/**
+ * xmlCtxtIsCatastrophicError:
+ * @ctxt:  parser context
+ *
+ * Returns true if the last error is catastrophic.
+ */
 int
 xmlCtxtIsCatastrophicError(xmlParserCtxtPtr ctxt) {
     if (ctxt == NULL)
@@ -1612,7 +1618,7 @@ xmlSetDeclaredEncoding(xmlParserCtxtPtr ctxt, xmlChar *encoding) {
 
 /**
  * xmlCtxtGetDeclaredEncoding:
- * ctxt:  parser context
+ * @ctxt:  parser context
  *
  * Available since 2.14.0.
  *
@@ -3012,7 +3018,7 @@ xmlNewSAXParserCtxt(const xmlSAXHandler *sax, void *userData)
 
 /**
  * xmlCtxtGetPrivate:
- * ctxt:  parser context
+ * @ctxt:  parser context
  *
  * Available since 2.14.0.
  *
@@ -3028,8 +3034,8 @@ xmlCtxtGetPrivate(xmlParserCtxtPtr ctxt) {
 
 /**
  * xmlCtxtSetPrivate:
- * ctxt:  parser context
- * priv:  private application data
+ * @ctxt:  parser context
+ * @priv:  private application data
  *
  * Available since 2.14.0.
  *
@@ -3045,7 +3051,7 @@ xmlCtxtSetPrivate(xmlParserCtxtPtr ctxt, void *priv) {
 
 /**
  * xmlCtxtGetCatalogs:
- * ctxt:  parser context
+ * @ctxt:  parser context
  *
  * Available since 2.14.0.
  *
@@ -3061,8 +3067,8 @@ xmlCtxtGetCatalogs(xmlParserCtxtPtr ctxt) {
 
 /**
  * xmlCtxtSetCatalogs:
- * ctxt:  parser context
- * catalogs:  catalogs pointer
+ * @ctxt:  parser context
+ * @catalogs:  catalogs pointer
  *
  * Available since 2.14.0.
  *
@@ -3078,7 +3084,7 @@ xmlCtxtSetCatalogs(xmlParserCtxtPtr ctxt, void *catalogs) {
 
 /**
  * xmlCtxtGetDict:
- * ctxt:  parser context
+ * @ctxt:  parser context
  *
  * Available since 2.14.0.
  *
@@ -3094,8 +3100,8 @@ xmlCtxtGetDict(xmlParserCtxtPtr ctxt) {
 
 /**
  * xmlCtxtSetDict:
- * ctxt:  parser context
- * dict:  dictionary
+ * @ctxt:  parser context
+ * @dict:  dictionary
  *
  * Available since 2.14.0.
  *

shell.c

@@ -1096,7 +1096,6 @@ xmllintShellReadline(char *prompt) {
  * xmllintShell:
  * @doc:  the initial document
  * @filename:  the output buffer
- * @input:  the line reading function
  * @output:  the output FILE*, defaults to stdout if NULL
  *
  * Implements the XML shell

threads.c

@@ -159,6 +159,12 @@ xmlMutexUnlock(xmlMutexPtr tok)
 #endif
 }
 
+/**
+ * xmlInitRMutex:
+ * @tok:  mutex
+ *
+ * Initialize the mutex.
+ */
 void
 xmlInitRMutex(xmlRMutexPtr tok) {
     (void) tok;
@@ -195,6 +201,12 @@ xmlNewRMutex(void)
     return (tok);
 }
 
+/**
+ * xmlCleanupRMutex:
+ * @tok:  mutex
+ *
+ * Cleanup the mutex.
+ */
 void
 xmlCleanupRMutex(xmlRMutexPtr tok) {
     (void) tok;

valid.c

@@ -6790,7 +6790,7 @@ xmlValidateDocumentInternal(xmlParserCtxtPtr ctxt, xmlValidCtxtPtr vctxt,
 
 /**
  * xmlValidateDocument:
- * @ctxt:  the validation context
+ * @vctxt:  the validation context
  * @doc:  a document instance
  *
  * DEPRECATED: This function can't report malloc or other failures.