doc: Make apibuild.py happy

HTMLparser.c

@@ -6721,7 +6721,7 @@ htmlReadIO(xmlInputReadCallback ioread, xmlInputCloseCallback ioclose,
 /**
  * htmlCtxtReadDoc:
  * @ctxt:  an HTML parser context
- * @cur:  a pointer to a zero terminated string
+ * @str:  a pointer to a zero terminated string
  * @URL:  the base URL to use for the document
  * @encoding:  the document encoding, or NULL
  * @options:  a combination of htmlParserOption(s)

encoding.c

@@ -1977,11 +1977,11 @@ xmlEncConvertError(int code) {
  * @in:  a pointer to an array of input bytes
  * @inlen:  the length of @in
  *
- * Returns an XML_ENC_ERR code.
- *
  * The value of @inlen after return is the number of octets consumed
  *     as the return value is 0, else unpredictable.
  * The value of @outlen after return is the number of octets produced.
+ *
+ * Returns an XML_ENC_ERR code.
  */
 int
 xmlEncInputChunk(xmlCharEncodingHandler *handler, unsigned char *out,
@@ -2070,6 +2070,8 @@ xmlEncOutputChunk(xmlCharEncodingHandler *handler, unsigned char *out,
  * @in:  an xmlBuffer for the input
  *
  * DEPERECATED: Don't use.
+ *
+ * Returns the number of bytes written or an XML_ENC_ERR code.
  */
 int
 xmlCharEncFirstLine(xmlCharEncodingHandler *handler, xmlBufferPtr out,

globals.c

@@ -622,7 +622,9 @@ xmlInitializeGlobalState(xmlGlobalStatePtr gs ATTRIBUTE_UNUSED)
 /**
  * xmlGetGlobalState:
  *
- * DEPRECATED: Always returns NULL.
+ * DEPRECATED
+ *
+ * Returns NULL.
  */
 xmlGlobalStatePtr
 xmlGetGlobalState(void)

include/libxml/HTMLparser.h

@@ -80,6 +80,7 @@ struct _htmlEntityDesc {
     const char *desc;   /* the description */
 };
 
+/** DOC_DISABLE */
 #ifdef LIBXML_SAX1_ENABLED
   #define XML_GLOBALS_HTML \
     XML_OP(htmlDefaultSAXHandler, xmlSAXHandlerV1, XML_DEPRECATED)
@@ -94,6 +95,7 @@ XML_GLOBALS_HTML
 #if defined(LIBXML_THREAD_ENABLED) && !defined(XML_GLOBALS_NO_REDEFINITION)
   #define htmlDefaultSAXHandler XML_GLOBAL_MACRO(htmlDefaultSAXHandler)
 #endif
+/** DOC_ENABLE */
 
 /*
  * There is only few public functions.
@@ -333,7 +335,9 @@ XMLPUBFUN htmlStatus htmlNodeStatus(const htmlNodePtr, int) ;
 
 #else /* LIBXML_HTML_ENABLED */
 
+/** DOC_DISABLE */
 #define XML_GLOBALS_HTML
+/** DOC_ENABLE */
 
 #endif /* LIBXML_HTML_ENABLED */
 #endif /* __HTML_PARSER_H__ */

include/libxml/c14n.h

@@ -20,7 +20,6 @@
 #include <libxml/xmlversion.h>
 
 #ifdef LIBXML_C14N_ENABLED
-#ifdef LIBXML_OUTPUT_ENABLED
 
 #include <libxml/tree.h>
 #include <libxml/xpath.h>
@@ -122,7 +121,6 @@ XMLPUBFUN int
 }
 #endif /* __cplusplus */
 
-#endif /* LIBXML_OUTPUT_ENABLED */
 #endif /* LIBXML_C14N_ENABLED */
 #endif /* __XML_C14N_H__ */
 

include/libxml/nanoftp.h

@@ -14,7 +14,7 @@
 
 #include <libxml/xmlversion.h>
 
-#if defined(LIBXML_FTP_ENABLED) || defined(LIBXML_LEGACY_ENABLED)
+#if defined(LIBXML_FTP_ENABLED)
 
 /* Needed for portability to Windows 64 bits */
 #if defined(_WIN32)

include/libxml/parser.h

@@ -821,6 +821,7 @@ XMLPUBVAR const char *const xmlParserVersion;
 XMLPUBFUN const char *const *__xmlParserVersion(void);
 #endif
 
+/** DOC_DISABLE */
 #define XML_GLOBALS_PARSER_CORE \
   XML_OP(oldXMLWDcompatibility, int, XML_DEPRECATED) \
   XML_OP(xmlDefaultSAXLocator, xmlSAXLocator, XML_DEPRECATED) \
@@ -866,6 +867,7 @@ XML_GLOBALS_PARSER
   #define xmlSubstituteEntitiesDefaultValue \
     XML_GLOBAL_MACRO(xmlSubstituteEntitiesDefaultValue)
 #endif
+/** DOC_ENABLE */
 
 /*
  * Init/Cleanup

include/libxml/tree.h

@@ -663,6 +663,7 @@ typedef void (*xmlDeregisterNodeFunc) (xmlNodePtr node);
  * Variables.
  */
 
+/** DOC_DISABLE */
 #define XML_GLOBALS_TREE \
   XML_OP(xmlBufferAllocScheme, xmlBufferAllocationScheme, XML_DEPRECATED) \
   XML_OP(xmlDefaultBufferSize, int, XML_DEPRECATED) \
@@ -682,6 +683,7 @@ XML_GLOBALS_TREE
   #define xmlDeregisterNodeDefaultValue \
     XML_GLOBAL_MACRO(xmlDeregisterNodeDefaultValue)
 #endif
+/** DOC_ENABLE */
 
 /*
  * Some helper functions

include/libxml/xmlIO.h

@@ -171,6 +171,7 @@ struct _xmlOutputBuffer {
 };
 #endif /* LIBXML_OUTPUT_ENABLED */
 
+/** DOC_DISABLE */
 #define XML_GLOBALS_IO \
   XML_OP(xmlParserInputBufferCreateFilenameValue, \
            xmlParserInputBufferCreateFilenameFunc, XML_DEPRECATED) \
@@ -187,6 +188,7 @@ XML_GLOBALS_IO
   #define xmlOutputBufferCreateFilenameValue \
     XML_GLOBAL_MACRO(xmlOutputBufferCreateFilenameValue)
 #endif
+/** DOC_ENABLE */
 
 /*
  * Interfaces for input
@@ -385,7 +387,7 @@ XMLPUBFUN int
 /**
  * Default 'ftp://' protocol callbacks
  */
-#if defined(LIBXML_FTP_ENABLED) || defined(LIBXML_LEGACY_ENABLED)
+#if defined(LIBXML_FTP_ENABLED)
 XMLPUBFUN int
 	xmlIOFTPMatch			(const char *filename);
 XMLPUBFUN void *
@@ -396,7 +398,7 @@ XMLPUBFUN int
 					 int len);
 XMLPUBFUN int
 	xmlIOFTPClose			(void * context);
-#endif /* defined(LIBXML_FTP_ENABLED) || defined(LIBXML_LEGACY_ENABLED) */
+#endif /* defined(LIBXML_FTP_ENABLED) */
 
 XMLPUBFUN xmlParserInputBufferCreateFilenameFunc
 	xmlParserInputBufferCreateFilenameDefault(

include/libxml/xmlerror.h

@@ -858,6 +858,7 @@ typedef void (*xmlGenericErrorFunc) (void *ctx,
  */
 typedef void (*xmlStructuredErrorFunc) (void *userData, xmlErrorPtr error);
 
+/** DOC_DISABLE */
 #define XML_GLOBALS_ERROR \
   XML_OP(xmlLastError, xmlError, XML_DEPRECATED) \
   XML_OP(xmlGenericError, xmlGenericErrorFunc, XML_EMPTY) \
@@ -876,6 +877,7 @@ XML_GLOBALS_ERROR
   #define xmlStructuredError XML_GLOBAL_MACRO(xmlStructuredError)
   #define xmlStructuredErrorContext XML_GLOBAL_MACRO(xmlStructuredErrorContext)
 #endif
+/** DOC_ENABLE */
 
 /*
  * Use the following function to reset the two global variables

include/libxml/xmlmemory.h

@@ -69,6 +69,7 @@ typedef char *(*xmlStrdupFunc)(const char *str);
  *    - xmlMemStrdup
  *    - xmlFree
  */
+/** DOC_DISABLE */
 #ifdef LIBXML_THREAD_ALLOC_ENABLED
   #define XML_GLOBALS_ALLOC \
     XML_OP(xmlMalloc, xmlMallocFunc, XML_EMPTY) \
@@ -88,6 +89,7 @@ typedef char *(*xmlStrdupFunc)(const char *str);
   #endif
 #else
   #define XML_GLOBALS_ALLOC
+/** DOC_ENABLE */
   XMLPUBVAR xmlMallocFunc xmlMalloc;
   XMLPUBVAR xmlMallocFunc xmlMallocAtomic;
   XMLPUBVAR xmlReallocFunc xmlRealloc;
@@ -171,6 +173,7 @@ XMLPUBFUN char *
 	xmlMemStrdupLoc	(const char *str, const char *file, int line);
 
 
+/** DOC_DISABLE */
 #ifdef DEBUG_MEMORY_LOCATION
 /**
  * xmlMalloc:
@@ -212,6 +215,7 @@ XMLPUBFUN char *
 #define xmlMemStrdup(str) xmlMemStrdupLoc((str), __FILE__, __LINE__)
 
 #endif /* DEBUG_MEMORY_LOCATION */
+/** DOC_ENABLE */
 
 #ifdef __cplusplus
 }

include/libxml/xmlsave.h

@@ -41,6 +41,7 @@ typedef enum {
 typedef struct _xmlSaveCtxt xmlSaveCtxt;
 typedef xmlSaveCtxt *xmlSaveCtxtPtr;
 
+/** DOC_DISABLE */
 #define XML_GLOBALS_SAVE \
   XML_OP(xmlIndentTreeOutput, int, XML_EMPTY) \
   XML_OP(xmlTreeIndentString, const char *, XML_EMPTY) \
@@ -55,6 +56,7 @@ XML_GLOBALS_SAVE
   #define xmlTreeIndentString XML_GLOBAL_MACRO(xmlTreeIndentString)
   #define xmlSaveNoEmptyTags XML_GLOBAL_MACRO(xmlSaveNoEmptyTags)
 #endif
+/** DOC_ENABLE */
 
 XMLPUBFUN xmlSaveCtxtPtr
 		xmlSaveToFd		(int fd,
@@ -108,7 +110,9 @@ XMLPUBFUN int
 
 #else /* LIBXML_OUTPUT_ENABLED */
 
+/** DOC_DISABLE */
 #define XML_GLOBALS_SAVE
+/** DOC_ENABLE */
 
 #endif /* LIBXML_OUTPUT_ENABLED */
 #endif /* __XML_XMLSAVE_H__ */

include/libxml/xmlversion.h.in

@@ -524,6 +524,7 @@ XMLPUBFUN void xmlCheckVersion(int version);
 #endif
 #endif /* __GNUC__ */
 
+/** DOC_DISABLE */
 #define XML_EMPTY
 
 #ifdef LIBXML_THREAD_ENABLED
@@ -534,6 +535,7 @@ XMLPUBFUN void xmlCheckVersion(int version);
   #define XML_DECLARE_GLOBAL(name, type, attrs) \
     attrs XMLPUBVAR type name;
 #endif
+/** DOC_ENABLE */
 
 #ifdef __cplusplus
 }

include/libxml/xpointer.h

@@ -28,7 +28,7 @@
 extern "C" {
 #endif
 
-#if defined(LIBXML_XPTR_LOCS_ENABLED) || defined(LIBXML_LEGACY_ENABLED)
+#if defined(LIBXML_XPTR_LOCS_ENABLED)
 /*
  * A Location Set
  */
@@ -105,7 +105,7 @@ XML_DEPRECATED
 XMLPUBFUN void
 		    xmlXPtrLocationSetRemove	(xmlLocationSetPtr cur,
 						 int val);
-#endif /* defined(LIBXML_XPTR_LOCS_ENABLED) || defined(LIBXML_LEGACY_ENABLED) */
+#endif /* defined(LIBXML_XPTR_LOCS_ENABLED) */
 
 /*
  * Functions.
@@ -118,7 +118,7 @@ XMLPUBFUN xmlXPathObjectPtr
 		    xmlXPtrEval			(const xmlChar *str,
 						 xmlXPathContextPtr ctx);
 
-#if defined(LIBXML_XPTR_LOCS_ENABLED) || defined(LIBXML_LEGACY_ENABLED)
+#if defined(LIBXML_XPTR_LOCS_ENABLED)
 XML_DEPRECATED
 XMLPUBFUN void
 		    xmlXPtrRangeToFunction	(xmlXPathParserContextPtr ctxt,
@@ -129,7 +129,7 @@ XMLPUBFUN xmlNodePtr
 XML_DEPRECATED
 XMLPUBFUN void
 		    xmlXPtrEvalRangePredicate	(xmlXPathParserContextPtr ctxt);
-#endif /* defined(LIBXML_XPTR_LOCS_ENABLED) || defined(LIBXML_LEGACY_ENABLED) */
+#endif /* defined(LIBXML_XPTR_LOCS_ENABLED) */
 #ifdef __cplusplus
 }
 #endif

legacy.c

@@ -1346,6 +1346,8 @@ cdataBlock(void *ctx, const xmlChar * value, int len)
 
 #include <libxml/nanoftp.h>
 
+/** DOC_DISABLE */
+
 void
 xmlNanoFTPInit(void) {
 }
@@ -1485,6 +1487,8 @@ xmlIOFTPClose(void *context ATTRIBUTE_UNUSED) {
     return(-1);
 }
 
+/** DOC_ENABLE */
+
 #endif /* #ifndef LIBXML_FTP_ENABLED */
 
 /*
@@ -1497,6 +1501,8 @@ xmlIOFTPClose(void *context ATTRIBUTE_UNUSED) {
 #include <libxml/xpathInternals.h>
 #include <libxml/xpointer.h>
 
+/** DOC_DISABLE */
+
 xmlXPathObjectPtr
 xmlXPtrNewRange(xmlNodePtr start ATTRIBUTE_UNUSED,
                 int startindex ATTRIBUTE_UNUSED,
@@ -1597,6 +1603,8 @@ xmlXPtrRangeToFunction(xmlXPathParserContextPtr ctxt,
     XP_ERROR(XPATH_EXPR_ERROR);
 }
 
+/** DOC_ENABLE */
+
 #endif /* #ifndef LIBXML_XPTR_LOCS_ENABLED */
 
 #endif /* LIBXML_LEGACY_ENABLED */

parser.c

@@ -13476,7 +13476,7 @@ int xmlSAXUserParseMemory(xmlSAXHandlerPtr sax, void *user_data,
 
 /**
  * xmlCreateDocParserCtxt:
- * @cur:  a pointer to an array of xmlChar
+ * @str:  a pointer to an array of xmlChar
  *
  * Creates a parser context for an XML in-memory document.
  *
@@ -14219,7 +14219,7 @@ xmlReadIO(xmlInputReadCallback ioread, xmlInputCloseCallback ioclose,
 /**
  * xmlCtxtReadDoc:
  * @ctxt:  an XML parser context
- * @cur:  a pointer to a zero terminated string
+ * @str:  a pointer to a zero terminated string
  * @URL:  the base URL to use for the document
  * @encoding:  the document encoding, or NULL
  * @options:  a combination of xmlParserOption

parserInternals.c

@@ -182,7 +182,7 @@ xmlErrInternal(xmlParserCtxtPtr ctxt, const char *msg, const xmlChar * str)
  * xmlFatalErr:
  * @ctxt:  an XML parser context
  * @error:  the error number
- * @extra:  extra information string
+ * @info:  extra information string
  *
  * Handle a fatal parser error, i.e. violating Well-Formedness constraints
  */
@@ -503,6 +503,10 @@ xmlParserInputRead(xmlParserInputPtr in ATTRIBUTE_UNUSED, int len ATTRIBUTE_UNUS
 /**
  * xmlParserGrow:
  * @ctxt:  an XML parser context
+ *
+ * Grow the input buffer.
+ *
+ * Returns the number of bytes read or -1 in case of error.
  */
 int
 xmlParserGrow(xmlParserCtxtPtr ctxt) {
@@ -590,6 +594,8 @@ xmlParserInputGrow(xmlParserInputPtr in, int len) {
 /**
  * xmlParserShrink:
  * @ctxt:  an XML parser context
+ *
+ * Shrink the input buffer.
  */
 void
 xmlParserShrink(xmlParserCtxtPtr ctxt) {

tree.c

@@ -7033,7 +7033,7 @@ xmlBufferDetach(xmlBufferPtr buf) {
  * @mem: the memory area
  * @size:  the size in byte
  *
- * Create an XML buffer initialized with bytes.
+ * Returns an XML buffer initialized with bytes.
  */
 xmlBufferPtr
 xmlBufferCreateStatic(void *mem, size_t size) {

valid.c

@@ -6264,7 +6264,7 @@ name_ok:
  * xmlValidateElement:
  * @ctxt:  the validation context
  * @doc:  a document instance
- * @elem:  an element instance
+ * @root:  an element instance
  *
  * Try to validate the subtree under an element
  *

xmlsave.c

@@ -1847,7 +1847,7 @@ xmlSaveDoc(xmlSaveCtxtPtr ctxt, xmlDocPtr doc)
 /**
  * xmlSaveTree:
  * @ctxt:  a document saving context
- * @node:  the top node of the subtree to save
+ * @cur:  the top node of the subtree to save
  *
  * Save a subtree starting at the node parameter to a saving context
  * TODO: The function is not fully implemented yet as it does not return the

xpath.c

@@ -183,6 +183,8 @@ xmlInitXPathInternal(void) {
  * xmlXPathIsNaN:
  * @val:  a double value
  *
+ * Checks whether a double is a NaN.
+ *
  * Returns 1 if the value is a NaN, 0 otherwise
  */
 int
@@ -198,6 +200,8 @@ xmlXPathIsNaN(double val) {
  * xmlXPathIsInf:
  * @val:  a double value
  *
+ * Checks whether a double is an infinity.
+ *
  * Returns 1 if the value is +Infinite, -1 if -Infinite, 0 otherwise
  */
 int