doc: Misc improvements

HTMLparser.c

@@ -5623,7 +5623,7 @@ htmlCtxtSetOptionsInternal(xmlParserCtxtPtr ctxt, int options, int keepMask)
  *         in case of error.
  */
 int
-htmlCtxtSetOptions(xmlParserCtxtPtr ctxt, int options)
+htmlCtxtSetOptions(htmlParserCtxtPtr ctxt, int options)
 {
     return(htmlCtxtSetOptionsInternal(ctxt, options, 0));
 }
@@ -5906,7 +5906,7 @@ htmlReadIO(xmlInputReadCallback ioread, xmlInputCloseCallback ioclose,
  * @returns the resulting document tree
  */
 htmlDocPtr
-htmlCtxtReadDoc(htmlParserCtxtPtr ctxt, const xmlChar *str,
+htmlCtxtReadDoc(xmlParserCtxtPtr ctxt, const xmlChar *str,
                 const char *URL, const char *encoding, int options)
 {
     xmlParserInputPtr input;
@@ -5938,7 +5938,7 @@ htmlCtxtReadDoc(htmlParserCtxtPtr ctxt, const xmlChar *str,
  * @returns the resulting document tree
  */
 htmlDocPtr
-htmlCtxtReadFile(htmlParserCtxtPtr ctxt, const char *filename,
+htmlCtxtReadFile(xmlParserCtxtPtr ctxt, const char *filename,
                 const char *encoding, int options)
 {
     xmlParserInputPtr input;
@@ -5971,7 +5971,7 @@ htmlCtxtReadFile(htmlParserCtxtPtr ctxt, const char *filename,
  * @returns the resulting document tree
  */
 htmlDocPtr
-htmlCtxtReadMemory(htmlParserCtxtPtr ctxt, const char *buffer, int size,
+htmlCtxtReadMemory(xmlParserCtxtPtr ctxt, const char *buffer, int size,
                   const char *URL, const char *encoding, int options)
 {
     xmlParserInputPtr input;
@@ -6006,7 +6006,7 @@ htmlCtxtReadMemory(htmlParserCtxtPtr ctxt, const char *buffer, int size,
  * @returns the resulting document tree
  */
 htmlDocPtr
-htmlCtxtReadFd(htmlParserCtxtPtr ctxt, int fd,
+htmlCtxtReadFd(xmlParserCtxtPtr ctxt, int fd,
               const char *URL, const char *encoding, int options)
 {
     xmlParserInputPtr input;
@@ -6039,7 +6039,7 @@ htmlCtxtReadFd(htmlParserCtxtPtr ctxt, int fd,
  * @returns the resulting document tree
  */
 htmlDocPtr
-htmlCtxtReadIO(htmlParserCtxtPtr ctxt, xmlInputReadCallback ioread,
+htmlCtxtReadIO(xmlParserCtxtPtr ctxt, xmlInputReadCallback ioread,
               xmlInputCloseCallback ioclose, void *ioctx,
 	      const char *URL,
               const char *encoding, int options)

doc/Doxyfile

@@ -6,7 +6,6 @@ JAVADOC_AUTOBRIEF      = YES
 OPTIMIZE_OUTPUT_FOR_C  = YES
 EXTRACT_LOCAL_CLASSES  = NO
 HIDE_UNDOC_MEMBERS     = YES
-HIDE_UNDOC_CLASSES     = YES
 CASE_SENSE_NAMES       = YES
 HIDE_SCOPE_NAMES       = YES
 SHOW_INCLUDE_FILES     = NO

encoding.c

@@ -983,7 +983,7 @@ xmlFindExtraHandler(const char *norig, const char *name, xmlCharEncFlags flags,
  */
 xmlParserErrors
 xmlLookupCharEncodingHandler(xmlCharEncoding enc,
-                             xmlCharEncodingHandler **out) {
+                             xmlCharEncodingHandlerPtr *out) {
     const xmlCharEncodingHandler *handler;
 
     if (out == NULL)
@@ -1063,7 +1063,7 @@ xmlGetCharEncodingHandler(xmlCharEncoding enc) {
 xmlParserErrors
 xmlCreateCharEncodingHandler(const char *name, xmlCharEncFlags flags,
                              xmlCharEncConvImpl impl, void *implCtxt,
-                             xmlCharEncodingHandler **out) {
+                             xmlCharEncodingHandlerPtr *out) {
     const xmlCharEncodingHandler *handler;
     const char *norig, *nalias;
     xmlCharEncoding enc;
@@ -1166,7 +1166,7 @@ xmlCreateCharEncodingHandler(const char *name, xmlCharEncFlags flags,
  */
 xmlParserErrors
 xmlOpenCharEncodingHandler(const char *name, int output,
-                           xmlCharEncodingHandler **out) {
+                           xmlCharEncodingHandlerPtr *out) {
     xmlCharEncFlags flags = output ? XML_ENC_OUTPUT : XML_ENC_INPUT;
 
     return(xmlCreateCharEncodingHandler(name, flags, NULL, NULL, out));
@@ -1773,8 +1773,8 @@ xmlEncOutputChunk(xmlCharEncodingHandler *handler, unsigned char *out,
  * @returns the number of bytes written or an xmlCharEncError code.
  */
 int
-xmlCharEncFirstLine(xmlCharEncodingHandler *handler, xmlBufferPtr out,
+xmlCharEncFirstLine(xmlCharEncodingHandler *handler, struct _xmlBuffer *out,
-                    xmlBufferPtr in) {
+                    struct _xmlBuffer *in) {
     return(xmlCharEncInFunc(handler, out, in));
 }
 
@@ -1889,8 +1889,8 @@ xmlCharEncInput(xmlParserInputBufferPtr input, size_t *sizeOut, int flush)
  * @returns the number of bytes written or an xmlCharEncError code.
  */
 int
-xmlCharEncInFunc(xmlCharEncodingHandler * handler, xmlBufferPtr out,
+xmlCharEncInFunc(xmlCharEncodingHandler * handler, struct _xmlBuffer *out,
-                 xmlBufferPtr in)
+                 struct _xmlBuffer *in)
 {
     int ret;
     int written;
@@ -2096,8 +2096,8 @@ error:
  * @returns the number of bytes written or an xmlCharEncError code.
  */
 int
-xmlCharEncOutFunc(xmlCharEncodingHandler *handler, xmlBufferPtr out,
+xmlCharEncOutFunc(xmlCharEncodingHandler *handler, struct _xmlBuffer *out,
-                  xmlBufferPtr in) {
+                  struct _xmlBuffer *in) {
     int ret;
     int written;
     int writtentot = 0;

error.c

@@ -325,7 +325,7 @@ xmlSetStructuredErrorFunc(void *ctx, xmlStructuredErrorFunc handler) {
  */
 
 void
-xmlParserPrintFileInfo(xmlParserInputPtr input) {
+xmlParserPrintFileInfo(struct _xmlParserInput *input) {
     if (input != NULL) {
 	if (input->filename)
 	    xmlGenericError(xmlGenericErrorContext,
@@ -419,7 +419,7 @@ xmlParserPrintFileContextInternal(xmlParserInputPtr input ,
  * @param input  an xmlParserInputPtr input
  */
 void
-xmlParserPrintFileContext(xmlParserInputPtr input) {
+xmlParserPrintFileContext(struct _xmlParserInput *input) {
    xmlParserPrintFileContextInternal(input, xmlGenericError,
                                      xmlGenericErrorContext);
 }

globals.c

@@ -185,40 +185,6 @@ static xmlGlobalState globalState;
  *									*
  ************************************************************************/
 
-/*
- * Memory allocation routines
- */
-
-/**
- * The variable holding the libxml free() implementation
- *
- * @param mem  an already allocated block of memory
- */
-xmlFreeFunc xmlFree = free;
-/**
- * The variable holding the libxml malloc() implementation
- *
- * @param size  the size requested in bytes
- * @returns a pointer to the newly allocated block or NULL in case of error
- */
-xmlMallocFunc xmlMalloc = malloc;
-/**
- * The variable holding the libxml malloc() implementation for atomic
- * data (i.e. blocks not containing pointers), useful when using a
- * garbage collecting allocator.
- *
- * @param size  the size requested in bytes
- * @returns a pointer to the newly allocated block or NULL in case of error
- */
-xmlMallocFunc xmlMallocAtomic = malloc;
-/**
- * The variable holding the libxml realloc() implementation
- *
- * @param mem  an already allocated block of memory
- * @param size  the new size requested in bytes
- * @returns a pointer to the newly reallocated block or NULL in case of error
- */
-xmlReallocFunc xmlRealloc = realloc;
 /**
  * a strdup implementation with a type signature matching POSIX
  *
@@ -229,12 +195,15 @@ static char *
 xmlPosixStrdup(const char *cur) {
     return((char*) xmlCharStrdup(cur));
 }
-/**
+
- * The variable holding the libxml strdup() implementation
+/*
- *
+ * Memory allocation routines
- * @param str  a zero terminated string
- * @returns the copy of the string or NULL in case of error
  */
+
+xmlFreeFunc xmlFree = free;
+xmlMallocFunc xmlMalloc = malloc;
+xmlMallocFunc xmlMallocAtomic = malloc;
+xmlReallocFunc xmlRealloc = realloc;
 xmlStrdupFunc xmlMemStrdup = xmlPosixStrdup;
 
 /*

hash.c

@@ -1095,7 +1095,7 @@ xmlHashScanFull3(xmlHashTablePtr hash, const xmlChar *key,
     }
 }
 
-/*
+/**
  * @param hash  hash table
  * @param copyFunc  copier function for items in the hash
  * @param deallocFunc  deallocation function in case of errors
@@ -1147,7 +1147,7 @@ error:
     return(NULL);
 }
 
-/*
+/**
  * @param hash  hash table
  * @param copy  copier function for items in the hash
  *

include/libxml/HTMLparser.h

@@ -27,6 +27,8 @@
 extern "C" {
 #endif
 
+/** @cond ignore */
+
 /*
  * Backward compatibility
  */
@@ -93,6 +95,8 @@ XMLPUBVAR const xmlSAXHandlerV1 htmlDefaultSAXHandler;
 
 #endif /* LIBXML_SAX1_ENABLED */
 
+/** @endcond */
+
 /*
  * There is only few public functions.
  */
@@ -358,7 +362,8 @@ XMLPUBFUN htmlDocPtr
 					 const char *encoding,
 					 int options);
 
-/* deprecated content model
+/**
+ * deprecated content model
  */
 typedef enum {
   HTML_NA = 0 ,		/* something we don't check at all */

include/libxml/HTMLtree.h

@@ -26,11 +26,13 @@ extern "C" {
 #endif
 
 /* Deprecated */
+/** @cond ignore */
 #define HTML_TEXT_NODE		XML_TEXT_NODE
 #define HTML_ENTITY_REF_NODE	XML_ENTITY_REF_NODE
 #define HTML_COMMENT_NODE	XML_COMMENT_NODE
 #define HTML_PRESERVE_NODE	XML_CDATA_SECTION_NODE
 #define HTML_PI_NODE		XML_PI_NODE
+/** @endcond */
 
 XMLPUBFUN htmlDocPtr
 		htmlNewDoc		(const xmlChar *URI,

include/libxml/catalog.h

@@ -43,6 +43,8 @@ extern "C" {
 #define XML_CATALOG_PI						\
     (const xmlChar *) "oasis-xml-catalog"
 
+/** @cond ignore */
+
 /*
  * The API is voluntarily limited to general cataloging.
  */
@@ -59,6 +61,8 @@ typedef enum {
     XML_CATA_ALLOW_ALL = 3
 } xmlCatalogAllow;
 
+/** @endcond */
+
 typedef struct _xmlCatalog xmlCatalog;
 typedef xmlCatalog *xmlCatalogPtr;
 

include/libxml/chvalid.h

@@ -23,6 +23,8 @@
 extern "C" {
 #endif
 
+/** @cond ignore */
+
 /*
  * Define our typedefs and structures
  *
@@ -50,6 +52,14 @@ struct _xmlChRangeGroup {
     const xmlChLRange	*longRange;
 };
 
+XMLPUBVAR const xmlChRangeGroup xmlIsBaseCharGroup;
+XMLPUBVAR const xmlChRangeGroup xmlIsCharGroup;
+XMLPUBVAR const xmlChRangeGroup xmlIsCombiningGroup;
+XMLPUBVAR const xmlChRangeGroup xmlIsDigitGroup;
+XMLPUBVAR const xmlChRangeGroup xmlIsExtenderGroup;
+XMLPUBVAR const xmlChRangeGroup xmlIsIdeographicGroup;
+XMLPUBVAR const unsigned char xmlIsPubidChar_tab[256];
+
 /**
  * Range checking routine
  */
@@ -57,6 +67,8 @@ XMLPUBFUN int
 		xmlCharInRange(unsigned int val, const xmlChRangeGroup *group);
 
 
+/** @endcond */
+
 /**
  * Automatically generated by genChRanges.py
  *
@@ -77,8 +89,6 @@ XMLPUBFUN int
 				 xmlIsBaseChar_ch((c)) : \
 				 xmlCharInRange((c), &xmlIsBaseCharGroup))
 
-XMLPUBVAR const xmlChRangeGroup xmlIsBaseCharGroup;
-
 /**
  * Automatically generated by genChRanges.py
  *
@@ -117,8 +127,6 @@ XMLPUBVAR const xmlChRangeGroup xmlIsBaseCharGroup;
 				 ((0xe000 <= (c)) && ((c) <= 0xfffd)) || \
 				 ((0x10000 <= (c)) && ((c) <= 0x10ffff))))
 
-XMLPUBVAR const xmlChRangeGroup xmlIsCharGroup;
-
 /**
  * Automatically generated by genChRanges.py
  *
@@ -128,8 +136,6 @@ XMLPUBVAR const xmlChRangeGroup xmlIsCharGroup;
 				 0 : \
 				 xmlCharInRange((c), &xmlIsCombiningGroup))
 
-XMLPUBVAR const xmlChRangeGroup xmlIsCombiningGroup;
-
 /**
  * Automatically generated by genChRanges.py
  *
@@ -146,8 +152,6 @@ XMLPUBVAR const xmlChRangeGroup xmlIsCombiningGroup;
 				 xmlIsDigit_ch((c)) : \
 				 xmlCharInRange((c), &xmlIsDigitGroup))
 
-XMLPUBVAR const xmlChRangeGroup xmlIsDigitGroup;
-
 /**
  * Automatically generated by genChRanges.py
  *
@@ -164,8 +168,6 @@ XMLPUBVAR const xmlChRangeGroup xmlIsDigitGroup;
 				 xmlIsExtender_ch((c)) : \
 				 xmlCharInRange((c), &xmlIsExtenderGroup))
 
-XMLPUBVAR const xmlChRangeGroup xmlIsExtenderGroup;
-
 /**
  * Automatically generated by genChRanges.py
  *
@@ -177,9 +179,6 @@ XMLPUBVAR const xmlChRangeGroup xmlIsExtenderGroup;
 				 ((c) == 0x3007) || \
 				 ((0x3021 <= (c)) && ((c) <= 0x3029))))
 
-XMLPUBVAR const xmlChRangeGroup xmlIsIdeographicGroup;
-XMLPUBVAR const unsigned char xmlIsPubidChar_tab[256];
-
 /**
  * Automatically generated by genChRanges.py
  *

include/libxml/encoding.h

@@ -21,8 +21,10 @@ extern "C" {
 /*
  * Backward compatibility
  */
+/** @cond ignore */
 #define UTF8Toisolat1 xmlUTF8ToIsolat1
 #define isolat1ToUTF8 xmlIsolat1ToUTF8
+/** @endcond */
 
 /**
  * Encoding conversion errors
@@ -186,13 +188,13 @@ typedef xmlCharEncError
 typedef void
 (*xmlCharEncConvCtxtDtor)(void *vctxt);
 
-/*
+typedef struct _xmlCharEncodingHandler xmlCharEncodingHandler;
- * Block defining the handlers for non UTF-8 encodings.
+typedef xmlCharEncodingHandler *xmlCharEncodingHandlerPtr;
+/**
+ * A character encoding conversion handler for non UTF-8 encodings.
  *
  * This structure will be made private.
  */
-typedef struct _xmlCharEncodingHandler xmlCharEncodingHandler;
-typedef xmlCharEncodingHandler *xmlCharEncodingHandlerPtr;
 struct _xmlCharEncodingHandler {
     char *name XML_DEPRECATED_MEMBER;
     union {

include/libxml/parser.h

@@ -14,7 +14,9 @@
 #define __XML_PARSER_H__
 
 #include <libxml/xmlversion.h>
+/** @cond ignore */
 #define XML_TREE_INTERNALS
+/** @endcond */
 #include <libxml/tree.h>
 #undef XML_TREE_INTERNALS
 #include <libxml/dict.h>
@@ -131,6 +133,8 @@ struct _xmlParserInput {
     xmlEntityPtr entity XML_DEPRECATED_MEMBER;
 };
 
+/** @cond ignore */
+
 /*
  * The parser can be asked to collect Node information, i.e. at what
  * place in the file they were detected.
@@ -205,6 +209,8 @@ typedef struct _xmlStartTag xmlStartTag;
 typedef struct _xmlParserNsData xmlParserNsData;
 typedef struct _xmlAttrHashBucket xmlAttrHashBucket;
 
+/** @endcond */
+
 /**
  * Callback for custom resource loaders.
  *
@@ -230,32 +236,66 @@ typedef xmlParserErrors
  * Parser context
  */
 struct _xmlParserCtxt {
-    /* The SAX handler */
+    /**
+     * @deprecated Use xmlCtxtGetSaxHandler() and
+     * xmlCtxtSetSaxHandler().
+     *
+     * the SAX handler
+     */
     struct _xmlSAXHandler *sax;
-    /* For SAX interface only, used by DOM build */
+    /**
+     * user data for SAX interface, defaults to the context itself
+     */
     void *userData;
-    /* the document being built */
+    /**
+     * @deprecated Use xmlCtxtGetDocument()
+     *
+     * the document being built
+     */
     xmlDocPtr myDoc;
-    /* is the document well formed */
+    /**
+     * @deprecated Use xmlCtxtGetStatus()
+     *
+     * is the document well formed?
+     */
     int wellFormed;
-    /* shall we replace entities ? */
+    /**
+     * @deprecated Use xmlParserOption XML_PARSE_NOENT
+     *
+     * shall we replace entities?
+     */
     int replaceEntities XML_DEPRECATED_MEMBER;
-    /* the XML version string */
+    /**
+     * @deprecated Use xmlCtxtGetVersion()
+     *
+     * the XML version string
+     */
     const xmlChar *version;
-    /* the declared encoding, if any */
+    /**
+     * @deprecated Use xmlCtxtGetDeclaredEncoding()
+     *
+     * the declared encoding, if any
+     */
     const xmlChar *encoding;
-    /* standalone document */
+    /**
+     * @deprecated Use xmlCtxtGetStandalone()
+     *
+     * standalone document
+     */
     int standalone;
 
-    /* an HTML(1) document
+    /**
-     * 3 is HTML after <head>
+     * @deprecated Use xmlCtxtIsHtml()
-     * 10 is HTML after <body>
+     *
+     * non-zero for HTML documents, actually an htmlInsertMode
      */
     int html;
 
     /* Input stream stack */
 
-    /* Current input stream */
+    /**
+     * Current input stream
+     */
     xmlParserInputPtr input;
     /* Number of current input streams */
     int inputNr;
@@ -280,7 +320,11 @@ struct _xmlParserCtxt {
     /* info about each node parsed */
     xmlParserNodeInfoSeq node_seq XML_DEPRECATED_MEMBER;
 
-    /* error code */
+    /**
+     * @deprecated Use xmlCtxtGetLastError()
+     *
+     * error code
+     */
     int errNo;
 
     /* reference and external subset */
@@ -290,11 +334,23 @@ struct _xmlParserCtxt {
     /* unused */
     int external XML_DEPRECATED_MEMBER;
 
-    /* is the document valid */
+    /**
+     * @deprecated Use xmlCtxtGetStatus()
+     *
+     * is the document valid
+     */
     int valid;
-    /* shall we try to validate ? */
+    /**
+     * @deprecated Use xmlParserOption XML_PARSE_DTDVALID
+     *
+     * shall we try to validate?
+     */
     int validate XML_DEPRECATED_MEMBER;
-    /* The validity context */
+    /**
+     * @deprecated Use xmlCtxtGetValidCtxt()
+     *
+     * The validity context
+     */
     xmlValidCtxt vctxt;
 
     /* push parser state */
@@ -320,9 +376,17 @@ struct _xmlParserCtxt {
     long nbChars XML_DEPRECATED_MEMBER;
     /* used by progressive parsing lookup */
     long checkIndex XML_DEPRECATED_MEMBER;
-    /* ugly but ... */
+    /**
+     * @deprecated Use inverted xmlParserOption XML_PARSE_NOBLANKS
+     *
+     * ugly but ...
+     */
     int keepBlanks XML_DEPRECATED_MEMBER;
-    /* SAX callbacks are disabled */
+    /**
+     * @deprecated Use xmlCtxtIsStopped()
+     *
+     * SAX callbacks are disabled
+     */
     int disableSAX XML_DEPRECATED_MEMBER;
     /* Parsing is in int 1/ext 2 subset */
     int inSubset;
@@ -350,26 +414,48 @@ struct _xmlParserCtxt {
     xmlParserInputPtr entity XML_DEPRECATED_MEMBER;
     /* unused */
     int charset XML_DEPRECATED_MEMBER;
-    /* Those two fields are there to */
+    /* Those two fields are there to speed up large node parsing */
     int nodelen XML_DEPRECATED_MEMBER;
-    /* Speed up large node parsing */
     int nodemem XML_DEPRECATED_MEMBER;
-    /* signal pedantic warnings */
+    /**
+     * @deprecated Use xmlParserOption XML_PARSE_PEDANTIC
+     *
+     * signal pedantic warnings
+     */
     int pedantic XML_DEPRECATED_MEMBER;
-    /* For user data, libxml won't touch it */
+    /**
+     * @deprecated Use xmlCtxtGetPrivate() and xmlCtxtSetPrivate()
+     *
+     * For user data, libxml won't touch it
+     */
     void *_private;
-
+    /**
-    /* should the external subset be loaded */
+     * @deprecated Use xmlParserOption XML_PARSE_DTDLOAD or
+     * XML_PARSE_DTD_ATTR
+     *
+     * should the external subset be loaded
+     */
     int loadsubset;
     /* set line number in element content */
     int linenumbers XML_DEPRECATED_MEMBER;
-    /* document's own catalog */
+    /**
+     * @deprecated Use xmlCtxtGetCatalogs() and xmlCtxtSetCatalogs()
+     *
+     * document's own catalog
+     */
     void *catalogs XML_DEPRECATED_MEMBER;
-    /* run in recovery mode */
+    /**
+     * @deprecated Use xmlParserOption XML_PARSE_RECOVER
+     * run in recovery mode
+     */
     int recovery XML_DEPRECATED_MEMBER;
     /* unused */
     int progressive XML_DEPRECATED_MEMBER;
-    /* dictionary for the parser */
+    /**
+     * @deprecated Use xmlCtxtGetDict() and xmlCtxtSetDict()
+     *
+     * dictionary for the parser
+     */
     xmlDictPtr dict;
     /* array for the attributes callbacks */
     const xmlChar **atts XML_DEPRECATED_MEMBER;
@@ -405,16 +491,29 @@ struct _xmlParserCtxt {
     xmlHashTablePtr attsDefault XML_DEPRECATED_MEMBER;
     /* non-CDATA attributes if any */
     xmlHashTablePtr attsSpecial XML_DEPRECATED_MEMBER;
-    /* is the document XML Namespace okay */
+
+    /**
+     * @deprecated Use xmlCtxtGetStatus()
+     *
+     * is the document XML Namespace okay
+     */
     int nsWellFormed;
-    /* Extra options */
+    /**
+     * @deprecated Use xmlCtxtGetOptions()
+     *
+     * Extra options
+     */
     int options;
 
     /*
      * Those fields are needed only for streaming parsing so far
      */
 
-    /* Use dictionary names for the tree */
+    /**
+     * @deprecated Use inverted xmlParserOption XML_PARSE_NODICT
+     *
+     * Use dictionary names for the tree
+     */
     int dictNames XML_DEPRECATED_MEMBER;
     /* number of freed element nodes */
     int freeElemsNr XML_DEPRECATED_MEMBER;
@@ -425,7 +524,9 @@ struct _xmlParserCtxt {
     /* List of freed attributes nodes */
     xmlAttrPtr freeAttrs XML_DEPRECATED_MEMBER;
 
-    /*
+    /**
+     * @deprecated Use xmlCtxtGetLastError()
+     *
      * the complete error information for the last error.
      */
     xmlError lastError XML_DEPRECATED_MEMBER;
@@ -477,7 +578,7 @@ struct _xmlParserCtxt {
     void *convCtxt XML_DEPRECATED_MEMBER;
 };
 
-/*
+/**
  * A SAX Locator.
  */
 struct _xmlSAXLocator {
@@ -941,11 +1042,11 @@ struct _xmlSAXHandler {
     xmlStructuredErrorFunc serror;
 };
 
-/*
- * SAX Version 1
- */
 typedef struct _xmlSAXHandlerV1 xmlSAXHandlerV1;
 typedef xmlSAXHandlerV1 *xmlSAXHandlerV1Ptr;
+/**
+ * SAX Version 1
+ */
 struct _xmlSAXHandlerV1 {
     internalSubsetSAXFunc internalSubset;
     isStandaloneSAXFunc isStandalone;
@@ -994,8 +1095,13 @@ typedef xmlParserInputPtr (*xmlExternalEntityLoader) (const char *URL,
  * Variables
  */
 
+/**
+ * Run-time version string.
+ */
 XMLPUBVAR const char *const xmlParserVersion;
 
+/** @cond ignore */
+
 XML_DEPRECATED
 XMLPUBVAR const xmlSAXLocator xmlDefaultSAXLocator;
 #ifdef LIBXML_SAX1_ENABLED
@@ -1027,6 +1133,8 @@ XML_DEPRECATED
 XMLPUBFUN int *__xmlSaveNoEmptyTags(void);
 #endif
 
+/** @endcond */
+
 #ifndef XML_GLOBALS_NO_REDEFINITION
   /**
    * Thread-local setting to enable validation. Defaults to 0.
@@ -1148,14 +1256,8 @@ XMLPUBFUN xmlDocPtr
 XML_DEPRECATED
 XMLPUBFUN int
 		xmlSubstituteEntitiesDefault(int val);
-XML_DEPRECATED
-XMLPUBFUN int
-                xmlThrDefSubstituteEntitiesDefaultValue(int v);
 XMLPUBFUN int
 		xmlKeepBlanksDefault	(int val);
-XML_DEPRECATED
-XMLPUBFUN int
-		xmlThrDefKeepBlanksDefaultValue(int v);
 XMLPUBFUN void
 		xmlStopParser		(xmlParserCtxtPtr ctxt);
 XML_DEPRECATED
@@ -1163,10 +1265,17 @@ XMLPUBFUN int
 		xmlPedanticParserDefault(int val);
 XML_DEPRECATED
 XMLPUBFUN int
-                xmlThrDefPedanticParserDefaultValue(int v);
+		xmlLineNumbersDefault	(int val);
+
 XML_DEPRECATED
 XMLPUBFUN int
-		xmlLineNumbersDefault	(int val);
+                xmlThrDefSubstituteEntitiesDefaultValue(int v);
+XML_DEPRECATED
+XMLPUBFUN int
+		xmlThrDefKeepBlanksDefaultValue(int v);
+XML_DEPRECATED
+XMLPUBFUN int
+                xmlThrDefPedanticParserDefaultValue(int v);
 XML_DEPRECATED
 XMLPUBFUN int
                 xmlThrDefLineNumbersDefaultValue(int v);

include/libxml/parserInternals.h

@@ -24,11 +24,21 @@
 extern "C" {
 #endif
 
-/*
+/**
- * Backward compatibility
+ * Push an input on the stack.
+ *
+ * @deprecated Use xmlCtxtPushInput()
  */
 #define inputPush xmlCtxtPushInput
+/**
+ * Pop an input from the stack.
+ *
+ * @deprecated Use xmlCtxtPushInput()
+ */
 #define inputPop xmlCtxtPopInput
+/**
+ * Maximum element nesting depth (without XML_PARSE_HUGE).
+ */
 #define xmlParserMaxDepth 256
 
 /**
@@ -238,10 +248,12 @@ extern "C" {
 /*
  * Global variables used for predefined strings.
  */
+/** @cond ignore */
 XMLPUBVAR const xmlChar xmlStringText[];
 XMLPUBVAR const xmlChar xmlStringTextNoenc[];
 XML_DEPRECATED
 XMLPUBVAR const xmlChar xmlStringComment[];
+/** @endcond */
 
 XML_DEPRECATED
 XMLPUBFUN int                   xmlIsLetter     (int c);
@@ -470,10 +482,12 @@ XMLPUBFUN void
 						 const xmlChar *ExternalID,
 						 const xmlChar *SystemID);
 
+/** @cond ignore */
 #define XML_SUBSTITUTE_NONE	0
 #define XML_SUBSTITUTE_REF	1
 #define XML_SUBSTITUTE_PEREF	2
 #define XML_SUBSTITUTE_BOTH	3
+/** @endcond */
 XML_DEPRECATED
 XMLPUBFUN xmlChar *
 		xmlStringDecodeEntities		(xmlParserCtxtPtr ctxt,

include/libxml/pattern.h

@@ -30,7 +30,7 @@ extern "C" {
 typedef struct _xmlPattern xmlPattern;
 typedef xmlPattern *xmlPatternPtr;
 
-/*
+/**
  * Internal type. This is the set of options affecting the behaviour
  * of pattern matching with this module.
  */

include/libxml/relaxng.h

@@ -60,7 +60,7 @@ typedef xmlRelaxNGParserCtxt *xmlRelaxNGParserCtxtPtr;
 typedef struct _xmlRelaxNGValidCtxt xmlRelaxNGValidCtxt;
 typedef xmlRelaxNGValidCtxt *xmlRelaxNGValidCtxtPtr;
 
-/*
+/**
  * List of possible Relax NG validation errors
  */
 typedef enum {
@@ -106,7 +106,7 @@ typedef enum {
     XML_RELAXNG_ERR_TEXTWRONG
 } xmlRelaxNGValidErr;
 
-/*
+/**
  * List of possible Relax NG Parser flags
  */
 typedef enum {

include/libxml/schemasInternals.h

@@ -30,6 +30,9 @@
 extern "C" {
 #endif
 
+/**
+ * Schema value type
+ */
 typedef enum {
     XML_SCHEMAS_UNKNOWN = 0,
     XML_SCHEMAS_STRING = 1,
@@ -80,7 +83,7 @@ typedef enum {
     XML_SCHEMAS_ANYSIMPLETYPE = 46
 } xmlSchemaValType;
 
-/*
+/**
  * XML Schemas defines multiple type of types.
  */
 typedef enum {
@@ -126,6 +129,9 @@ typedef enum {
     XML_SCHEMA_EXTRA_ATTR_USE_PROHIB
 } xmlSchemaTypeType;
 
+/**
+ * Schema content type
+ */
 typedef enum {
     XML_SCHEMA_CONTENT_UNKNOWN = 0,
     XML_SCHEMA_CONTENT_EMPTY = 1,
@@ -146,11 +152,11 @@ typedef xmlSchemaType *xmlSchemaTypePtr;
 typedef struct _xmlSchemaFacet xmlSchemaFacet;
 typedef xmlSchemaFacet *xmlSchemaFacetPtr;
 
-/*
- * Annotation
- */
 typedef struct _xmlSchemaAnnot xmlSchemaAnnot;
 typedef xmlSchemaAnnot *xmlSchemaAnnotPtr;
+/**
+ * Annotation
+ */
 struct _xmlSchemaAnnot {
     struct _xmlSchemaAnnot *next;
     xmlNodePtr content;         /* the annotation */
@@ -216,12 +222,11 @@ struct _xmlSchemaAnnot {
  */
 #define XML_SCHEMAS_ATTR_FIXED        1 << 9
 
-/*
- * An attribute definition.
- */
-
 typedef struct _xmlSchemaAttribute xmlSchemaAttribute;
 typedef xmlSchemaAttribute *xmlSchemaAttributePtr;
+/**
+ * An attribute definition.
+ */
 struct _xmlSchemaAttribute {
     xmlSchemaTypeType type;
     struct _xmlSchemaAttribute *next; /* the next attribute (not used?) */
@@ -245,12 +250,12 @@ struct _xmlSchemaAttribute {
     xmlSchemaAttributePtr refDecl; /* Deprecated; not used */
 };
 
-/*
+typedef struct _xmlSchemaAttributeLink xmlSchemaAttributeLink;
+typedef xmlSchemaAttributeLink *xmlSchemaAttributeLinkPtr;
+/**
  * Used to build a list of attribute uses on complexType definitions.
  * WARNING: Deprecated; not used.
  */
-typedef struct _xmlSchemaAttributeLink xmlSchemaAttributeLink;
-typedef xmlSchemaAttributeLink *xmlSchemaAttributeLinkPtr;
 struct _xmlSchemaAttributeLink {
     struct _xmlSchemaAttributeLink *next;/* the next attribute link ... */
     struct _xmlSchemaAttribute *attr;/* the linked attribute */
@@ -261,21 +266,21 @@ struct _xmlSchemaAttributeLink {
  */
 #define XML_SCHEMAS_WILDCARD_COMPLETE 1 << 0
 
-/*
- * Used to build a list of namespaces on wildcards.
- */
 typedef struct _xmlSchemaWildcardNs xmlSchemaWildcardNs;
 typedef xmlSchemaWildcardNs *xmlSchemaWildcardNsPtr;
+/**
+ * Used to build a list of namespaces on wildcards.
+ */
 struct _xmlSchemaWildcardNs {
     struct _xmlSchemaWildcardNs *next;/* the next constraint link ... */
     const xmlChar *value;/* the value */
 };
 
-/*
- * A wildcard.
- */
 typedef struct _xmlSchemaWildcard xmlSchemaWildcard;
 typedef xmlSchemaWildcard *xmlSchemaWildcardPtr;
+/**
+ * A wildcard.
+ */
 struct _xmlSchemaWildcard {
     xmlSchemaTypeType type;        /* The kind of type */
     const xmlChar *id; /* Deprecated; not used */
@@ -312,14 +317,14 @@ struct _xmlSchemaWildcard {
  */
 #define XML_SCHEMAS_ATTRGROUP_HAS_REFS 1 << 4
 
-/*
+typedef struct _xmlSchemaAttributeGroup xmlSchemaAttributeGroup;
+typedef xmlSchemaAttributeGroup *xmlSchemaAttributeGroupPtr;
+/**
  * An attribute group definition.
  *
  * xmlSchemaAttribute and xmlSchemaAttributeGroup start of structures
  * must be kept similar
  */
-typedef struct _xmlSchemaAttributeGroup xmlSchemaAttributeGroup;
-typedef xmlSchemaAttributeGroup *xmlSchemaAttributeGroupPtr;
 struct _xmlSchemaAttributeGroup {
     xmlSchemaTypeType type;        /* The kind of type */
     struct _xmlSchemaAttribute *next;/* the next attribute if in a group ... */
@@ -339,22 +344,22 @@ struct _xmlSchemaAttributeGroup {
     void *attrUses;
 };
 
-/*
+typedef struct _xmlSchemaTypeLink xmlSchemaTypeLink;
+typedef xmlSchemaTypeLink *xmlSchemaTypeLinkPtr;
+/**
  * Used to build a list of types (e.g. member types of
  * simpleType with variety "union").
  */
-typedef struct _xmlSchemaTypeLink xmlSchemaTypeLink;
-typedef xmlSchemaTypeLink *xmlSchemaTypeLinkPtr;
 struct _xmlSchemaTypeLink {
     struct _xmlSchemaTypeLink *next;/* the next type link ... */
     xmlSchemaTypePtr type;/* the linked type */
 };
 
-/*
- * Used to build a list of facets.
- */
 typedef struct _xmlSchemaFacetLink xmlSchemaFacetLink;
 typedef xmlSchemaFacetLink *xmlSchemaFacetLinkPtr;
+/**
+ * Used to build a list of facets.
+ */
 struct _xmlSchemaFacetLink {
     struct _xmlSchemaFacetLink *next;/* the next facet link ... */
     xmlSchemaFacetPtr facet;/* the linked facet */
@@ -494,7 +499,7 @@ struct _xmlSchemaFacetLink {
 #define XML_SCHEMAS_TYPE_REDEFINING    1 << 31
 #endif
 
-/*
+/**
  * Schemas type definition.
  */
 struct _xmlSchemaType {
@@ -532,12 +537,6 @@ struct _xmlSchemaType {
     void *attrUses;
 };
 
-/*
- * An element definition.
- *
- * xmlSchemaType, xmlSchemaFacet and xmlSchemaElement start of
- * structures must be kept similar
- */
 /**
  * the element is nillable
  */
@@ -621,6 +620,12 @@ struct _xmlSchemaType {
 
 typedef struct _xmlSchemaElement xmlSchemaElement;
 typedef xmlSchemaElement *xmlSchemaElementPtr;
+/**
+ * An element definition.
+ *
+ * xmlSchemaType, xmlSchemaFacet and xmlSchemaElement start of
+ * structures must be kept similar
+ */
 struct _xmlSchemaElement {
     xmlSchemaTypeType type; /* The kind of type */
     struct _xmlSchemaType *next; /* Not used? */
@@ -652,23 +657,23 @@ struct _xmlSchemaElement {
     void *idcs; /* The identity-constraint defs */
 };
 
-/*
+/**
  * unknown facet handling
  */
 #define XML_SCHEMAS_FACET_UNKNOWN        0
-/*
+/**
  * preserve the type of the facet
  */
 #define XML_SCHEMAS_FACET_PRESERVE        1
-/*
+/**
  * replace the type of the facet
  */
 #define XML_SCHEMAS_FACET_REPLACE        2
-/*
+/**
  * collapse the types of the facet
  */
 #define XML_SCHEMAS_FACET_COLLAPSE        3
-/*
+/**
  * A facet definition.
  */
 struct _xmlSchemaFacet {
@@ -684,11 +689,11 @@ struct _xmlSchemaFacet {
     xmlRegexpPtr    regexp; /* The regex for patterns */
 };
 
-/*
- * A notation definition.
- */
 typedef struct _xmlSchemaNotation xmlSchemaNotation;
 typedef xmlSchemaNotation *xmlSchemaNotationPtr;
+/**
+ * A notation definition.
+ */
 struct _xmlSchemaNotation {
     xmlSchemaTypeType type; /* The kind of type */
     const xmlChar *name;
@@ -746,7 +751,7 @@ struct _xmlSchemaNotation {
  * no target namespace.
  */
 #define XML_SCHEMAS_INCLUDING_CONVERT_NS            1 << 9
-/*
+/**
  * A Schemas definition
  */
 struct _xmlSchema {

include/libxml/schematron.h

@@ -25,14 +25,24 @@
 extern "C" {
 #endif
 
+/**
+ * Schematron validation options
+ */
 typedef enum {
-    XML_SCHEMATRON_OUT_QUIET = 1 << 0,	/* quiet no report */
+    /** quiet no report */
-    XML_SCHEMATRON_OUT_TEXT = 1 << 1,	/* build a textual report */
+    XML_SCHEMATRON_OUT_QUIET = 1 << 0,
-    XML_SCHEMATRON_OUT_XML = 1 << 2,	/* output SVRL */
+    /** build a textual report */
-    XML_SCHEMATRON_OUT_ERROR = 1 << 3,  /* output via xmlStructuredErrorFunc */
+    XML_SCHEMATRON_OUT_TEXT = 1 << 1,
-    XML_SCHEMATRON_OUT_FILE = 1 << 8,	/* output to a file descriptor */
+    /** output SVRL */
-    XML_SCHEMATRON_OUT_BUFFER = 1 << 9,	/* output to a buffer */
+    XML_SCHEMATRON_OUT_XML = 1 << 2,
-    XML_SCHEMATRON_OUT_IO = 1 << 10	/* output to I/O mechanism */
+    /** output via xmlStructuredErrorFunc */
+    XML_SCHEMATRON_OUT_ERROR = 1 << 3,
+    /** output to a file descriptor */
+    XML_SCHEMATRON_OUT_FILE = 1 << 8,
+    /** output to a buffer */
+    XML_SCHEMATRON_OUT_BUFFER = 1 << 9,
+    /** output to I/O mechanism */
+    XML_SCHEMATRON_OUT_IO = 1 << 10
 } xmlSchematronValidOptions;
 
 /**

include/libxml/tree.h

@@ -22,7 +22,9 @@
 #else /* XML_TREE_INTERNALS */
 
 #ifndef __XML_TREE_H__
+/** @cond ignore */
 #define __XML_TREE_H__
+/** @endcond */
 
 #include <stdio.h>
 #include <limits.h>
@@ -38,11 +40,13 @@ extern "C" {
 /*
  * Backward compatibility
  */
+/** @cond ignore */
 #define xmlBufferAllocScheme XML_BUFFER_ALLOC_EXACT
 #define xmlDefaultBufferSize 4096
 #define XML_GET_CONTENT(n) \
     ((n)->type == XML_ELEMENT_NODE ? NULL : (n)->content)
 #define XML_GET_LINE(n)	xmlGetLineNo(n)
+/** @endcond */
 
 /*
  * Some of the basic types pointer to structures:
@@ -71,7 +75,7 @@ typedef xmlSAXHandler *xmlSAXHandlerPtr;
 typedef struct _xmlEntity xmlEntity;
 typedef xmlEntity *xmlEntityPtr;
 
-/*
+/**
  * Removed, buffers always use XML_BUFFER_ALLOC_IO now.
  */
 typedef enum {
@@ -108,7 +112,7 @@ struct _xmlBuffer {
 typedef struct _xmlBuf xmlBuf;
 typedef xmlBuf *xmlBufPtr;
 
-/*
+/**
  * Macro used to express that the API use the new buffers for
  * xmlParserInputBuffer and xmlOutputBuffer. The change was
  * introduced in 2.9.0.
@@ -199,7 +203,7 @@ struct _xmlNotation {
     const xmlChar               *SystemID;
 };
 
-/*
+/**
  * A DTD Attribute type definition.
  */
 typedef enum {
@@ -215,7 +219,7 @@ typedef enum {
     XML_ATTRIBUTE_NOTATION
 } xmlAttributeType;
 
-/*
+/**
  * A DTD Attribute default definition.
  */
 typedef enum {
@@ -276,7 +280,7 @@ struct _xmlAttribute {
     const xmlChar          *elem;
 };
 
-/*
+/**
  * Possible definitions of element content types.
  */
 typedef enum {
@@ -286,7 +290,7 @@ typedef enum {
     XML_ELEMENT_CONTENT_OR
 } xmlElementContentType;
 
-/*
+/**
  * Possible definitions of element content occurrences.
  */
 typedef enum {
@@ -319,7 +323,7 @@ struct _xmlElementContent {
     const xmlChar             *prefix;
 };
 
-/*
+/**
  * The different possibilities for an element content type.
  */
 typedef enum {
@@ -486,7 +490,7 @@ struct _xmlAttr {
 
 typedef struct _xmlID xmlID;
 typedef xmlID *xmlIDPtr;
-/*
+/**
  * An XML ID instance.
  */
 struct _xmlID {
@@ -504,6 +508,7 @@ struct _xmlID {
     struct _xmlDoc   *doc;
 };
 
+/** @cond ignore */
 typedef struct _xmlRef xmlRef;
 typedef xmlRef *xmlRefPtr;
 /*
@@ -516,6 +521,7 @@ struct _xmlRef {
     const xmlChar    *name;	/* The attribute if attr is not available */
     int               lineno;	/* The line number if attr is not available */
 };
+/** @endcond */
 
 typedef struct _xmlNode xmlNode;
 typedef xmlNode *xmlNodePtr;
@@ -679,7 +685,7 @@ typedef xmlNsPtr (*xmlDOMWrapAcquireNsFunction) (xmlDOMWrapCtxtPtr ctxt,
 						 const xmlChar *nsName,
 						 const xmlChar *nsPrefix);
 
-/*
+/**
  * Context for DOM wrapper-operations.
  */
 struct _xmlDOMWrapCtxt {
@@ -734,6 +740,8 @@ typedef void (*xmlDeregisterNodeFunc) (xmlNodePtr node);
  * Variables.
  */
 
+/** @cond ignore */
+
 XML_DEPRECATED
 XMLPUBFUN xmlRegisterNodeFunc *__xmlRegisterNodeDefaultValue(void);
 XML_DEPRECATED
@@ -746,6 +754,8 @@ XMLPUBFUN xmlDeregisterNodeFunc *__xmlDeregisterNodeDefaultValue(void);
     (*__xmlDeregisterNodeDefaultValue())
 #endif
 
+/** @endcond */
+
 /*
  * Some helper functions
  */

include/libxml/uri.h

@@ -22,16 +22,18 @@
 extern "C" {
 #endif
 
+typedef struct _xmlURI xmlURI;
+typedef xmlURI *xmlURIPtr;
 /**
- * A parsed URI reference. This is a struct containing the various fields
+ * A parsed URI reference.
+ *
+ * This is a struct containing the various fields
  * as described in RFC 2396 but separated for further processing.
  *
  * Note: query is a deprecated field which is incorrectly unescaped.
  * query_raw takes precedence over query if the former is set.
  * See: http://mail.gnome.org/archives/xml/2007-April/thread.html\#00127
  */
-typedef struct _xmlURI xmlURI;
-typedef xmlURI *xmlURIPtr;
 struct _xmlURI {
     char *scheme;	/* the URI scheme */
     char *opaque;	/* opaque part */

include/libxml/valid.h

@@ -56,11 +56,11 @@ typedef void (*xmlValidityWarningFunc) (void *ctx,
 			       const char *msg,
 			       ...) LIBXML_ATTR_FORMAT(2,3);
 
-/*
- * An xmlValidCtxt is used for error reporting when validating.
- */
 typedef struct _xmlValidCtxt xmlValidCtxt;
 typedef xmlValidCtxt *xmlValidCtxtPtr;
+/**
+ * An xmlValidCtxt is used for error reporting when validating.
+ */
 struct _xmlValidCtxt {
     void *userData;			/* user specific data block */
     xmlValidityErrorFunc error;		/* the callback in case of errors */

include/libxml/xlink.h

@@ -22,6 +22,8 @@
 extern "C" {
 #endif
 
+/** @cond ignore */
+
 /**
  * Various defines for the various Link properties.
  *
@@ -56,6 +58,8 @@ typedef enum {
     XLINK_ACTUATE_ONREQUEST
 } xlinkActuate;
 
+/** @endcond */
+
 /**
  * This is the prototype for the link detection routine.
  * It calls the default link detection callbacks upon link detection.
@@ -140,14 +144,14 @@ typedef void
 				 const xlinkTitle *titles,
 				 const xmlChar **langs);
 
+typedef struct _xlinkHandler xlinkHandler;
+typedef xlinkHandler *xlinkHandlerPtr;
 /**
  * This is the structure containing a set of Links detection callbacks.
  *
  * There is no default xlink callbacks, if one want to get link
  * recognition activated, those call backs must be provided before parsing.
  */
-typedef struct _xlinkHandler xlinkHandler;
-typedef xlinkHandler *xlinkHandlerPtr;
 struct _xlinkHandler {
     xlinkSimpleLinkFunk simple;
     xlinkExtendedLinkFunk extended;

include/libxml/xmlIO.h

@@ -117,8 +117,10 @@ typedef xmlOutputBufferPtr
 (*xmlOutputBufferCreateFilenameFunc)(const char *URI,
         xmlCharEncodingHandlerPtr encoder, int compression);
 
-/*
+/**
- * This struct and all related functions should be ultimately
+ * Parser input buffer
+ *
+ * This struct and all related functions should ultimately
  * be removed from the public interface.
  */
 struct _xmlParserInputBuffer {
@@ -154,6 +156,8 @@ struct _xmlOutputBuffer {
 };
 #endif /* LIBXML_OUTPUT_ENABLED */
 
+/** @cond ignore */
+
 XML_DEPRECATED
 XMLPUBFUN xmlParserInputBufferCreateFilenameFunc *
 __xmlParserInputBufferCreateFilenameValue(void);
@@ -168,6 +172,8 @@ __xmlOutputBufferCreateFilenameValue(void);
     (*__xmlOutputBufferCreateFilenameValue())
 #endif
 
+/** @endcond */
+
 /*
  * Interfaces for input
  */

include/libxml/xmlerror.h

@@ -19,8 +19,10 @@
 extern "C" {
 #endif
 
-/*
+/**
- * Backward compatibility
+ * Set generic error callback.
+ *
+ * @deprecated Use xmlSetGenericErrorFunc()
  */
 #define initGenericErrorDefaultFunc(h) xmlSetGenericErrorFunc(NULL, *(h))
 
@@ -920,13 +922,14 @@ typedef void (*xmlGenericErrorFunc) (void *ctx,
  */
 typedef void (*xmlStructuredErrorFunc) (void *userData, const xmlError *error);
 
+/** @cond ignore */
 XML_DEPRECATED
 XMLPUBFUN const xmlError *__xmlLastError(void);
-
 XMLPUBFUN xmlGenericErrorFunc *__xmlGenericError(void);
 XMLPUBFUN void **__xmlGenericErrorContext(void);
 XMLPUBFUN xmlStructuredErrorFunc *__xmlStructuredError(void);
 XMLPUBFUN void **__xmlStructuredErrorContext(void);
+/** @endcond */
 
 #ifndef XML_GLOBALS_NO_REDEFINITION
   /**
@@ -967,18 +970,19 @@ XMLPUBFUN void **__xmlStructuredErrorContext(void);
 XMLPUBFUN void
     xmlSetGenericErrorFunc	(void *ctx,
 				 xmlGenericErrorFunc handler);
+XMLPUBFUN void
+    xmlSetStructuredErrorFunc	(void *ctx,
+				 xmlStructuredErrorFunc handler);
+
 XML_DEPRECATED
 XMLPUBFUN void
     xmlThrDefSetGenericErrorFunc(void *ctx,
                                  xmlGenericErrorFunc handler);
-
-XMLPUBFUN void
-    xmlSetStructuredErrorFunc	(void *ctx,
-				 xmlStructuredErrorFunc handler);
 XML_DEPRECATED
 XMLPUBFUN void
     xmlThrDefSetStructuredErrorFunc(void *ctx,
                                  xmlStructuredErrorFunc handler);
+
 /*
  * Legacy error handlers.
  */

include/libxml/xmlmemory.h

@@ -67,7 +67,6 @@ typedef char *(*xmlStrdupFunc)(const char *str);
  */
 #ifdef LIBXML_THREAD_ALLOC_ENABLED
 
-/** @cond IGNORE */
 XMLPUBFUN xmlMallocFunc *__xmlMalloc(void);
 XMLPUBFUN xmlMallocFunc *__xmlMallocAtomic(void);
 XMLPUBFUN xmlReallocFunc *__xmlRealloc(void);
@@ -81,14 +80,34 @@ XMLPUBFUN xmlStrdupFunc *__xmlMemStrdup(void);
   #define xmlFree (*__xmlFree())
   #define xmlMemStrdup (*__xmlMemStrdup())
 #endif
-/** @endcond */
 
 #else
+
+/**
+ * The variable holding the libxml malloc() implementation
+ */
 XMLPUBVAR xmlMallocFunc xmlMalloc;
+/**
+ * The variable holding the libxml malloc() implementation for atomic
+ * data (i.e. blocks not containing pointers), useful when using a
+ * garbage collecting allocator.
+ *
+ * @deprecated Use xmlMalloc()
+ */
 XMLPUBVAR xmlMallocFunc xmlMallocAtomic;
+/**
+ * The variable holding the libxml realloc() implementation
+ */
 XMLPUBVAR xmlReallocFunc xmlRealloc;
+/**
+ * The variable holding the libxml free() implementation
+ */
 XMLPUBVAR xmlFreeFunc xmlFree;
+/**
+ * The variable holding the libxml strdup() implementation
+ */
 XMLPUBVAR xmlStrdupFunc xmlMemStrdup;
+
 #endif
 
 /*

include/libxml/xmlmodule.h

@@ -28,7 +28,7 @@ extern "C" {
 typedef struct _xmlModule xmlModule;
 typedef xmlModule *xmlModulePtr;
 
-/*
+/**
  * enumeration of options that can be passed down to xmlModuleOpen()
  */
 typedef enum {

include/libxml/xmlreader.h

@@ -42,7 +42,7 @@ typedef enum {
 
 #ifdef LIBXML_READER_ENABLED
 
-/*
+/**
  * Internal state values for the reader.
  */
 typedef enum {

include/libxml/xmlschemastypes.h

@@ -26,6 +26,9 @@
 extern "C" {
 #endif
 
+/**
+ * Schema whitespace value type
+ */
 typedef enum {
     XML_SCHEMA_WHITESPACE_UNKNOWN = 0,
     XML_SCHEMA_WHITESPACE_PRESERVE = 1,

include/libxml/xpath.h

@@ -87,17 +87,15 @@ struct _xmlNodeSet {
     xmlNodePtr *nodeTab;
 };
 
-/*
+/**
  * An expression is evaluated to yield an object, which
  * has one of the following four basic types:
+ *
  *   - node-set
  *   - boolean
  *   - number
  *   - string
- *
- * @@ XPointer will add more types !
  */
-
 typedef enum {
     XPATH_UNDEFINED = 0,
     XPATH_NODESET = 1,
@@ -136,6 +134,7 @@ struct _xmlXPathObject {
     int index2;
 };
 
+/** @cond ignore */
 
 /*
  * unused
@@ -182,6 +181,8 @@ struct _xmlXPathAxis {
     xmlXPathAxisFunc func;		/* the search function */
 };
 
+/** @endcond */
+
 /**
  * An XPath function.
  * The arguments (if any) are popped out from the context stack
@@ -403,6 +404,8 @@ struct _xmlXPathParserContext {
  * Objects and Nodesets handling
  */
 
+/** @cond ignore */
+
 XML_DEPRECATED
 XMLPUBVAR double xmlXPathNAN;
 XML_DEPRECATED
@@ -440,6 +443,7 @@ XMLPUBVAR double xmlXPathNINF;
 #define xmlXPathNodeSetIsEmpty(ns)                                      \
     (((ns) == NULL) || ((ns)->nodeNr == 0) || ((ns)->nodeTab == NULL))
 
+/** @endcond */
 
 XMLPUBFUN void
 		    xmlXPathFreeObject		(xmlXPathObjectPtr obj);

include/libxml/xpathInternals.h

@@ -25,10 +25,17 @@
 extern "C" {
 #endif
 
-/*
+/**
- * Backward compatibility
+ * Push a value on the stack
+ *
+ * @deprecated Use xmlXPathValuePush()
  */
 #define valuePush xmlXPathValuePush
+/**
+ * Pop a value from the stack
+ *
+ * @deprecated Use xmlXPathValuePop()
+ */
 #define valuePop xmlXPathValuePop
 
 /************************************************************************

parserInternals.c

@@ -433,7 +433,7 @@ xmlCtxtErr(xmlParserCtxtPtr ctxt, xmlNodePtr node, xmlErrorDomain domain,
  * @returns a bitmask of XML_STATUS_* flags ORed together.
  */
 xmlParserStatus
-xmlCtxtGetStatus(xmlParserCtxt *ctxt) {
+xmlCtxtGetStatus(xmlParserCtxtPtr ctxt) {
     xmlParserStatus bits = 0;
 
     if (xmlCtxtIsCatastrophicError(ctxt)) {
@@ -3372,11 +3372,6 @@ xmlLineNumbersDefault(int val) {
 
 /**
  * Set and return the previous value for default entity support.
- * Initially the parser always keep entity references instead of substituting
- * entity values in the output. This function has to be used to change the
- * default parser behavior
- * SAX::substituteEntities() has to be used for changing that on a file by
- * file basis.
  *
  * @deprecated Use the modern options API with XML_PARSE_NOENT.
  *
@@ -3394,21 +3389,6 @@ xmlSubstituteEntitiesDefault(int val) {
 
 /**
  * Set and return the previous value for default blanks text nodes support.
- * The 1.x version of the parser used an heuristic to try to detect
- * ignorable white spaces. As a result the SAX callback was generating
- * xmlSAX2IgnorableWhitespace() callbacks instead of characters() one, and when
- * using the DOM output text nodes containing those blanks were not generated.
- * The 2.x and later version will switch to the XML standard way and
- * ignorableWhitespace() are only generated when running the parser in
- * validating mode and when the current element doesn't allow CDATA or
- * mixed content.
- * This function is provided as a way to force the standard behavior
- * on 1.X libs and to switch back to the old mode for compatibility when
- * running 1.X client code on 2.X . Upgrade of 1.X code should be done
- * by using xmlIsBlankNode() commodity function to detect the "empty"
- * nodes generated.
- * This value also affect autogeneration of indentation when saving code
- * if blanks sections are kept, indentation is not generated.
  *
  * @deprecated Use the modern options API with XML_PARSE_NOBLANKS.
  *

pattern.c

@@ -1988,21 +1988,21 @@ xmlStreamPushNode(xmlStreamCtxtPtr stream,
 }
 
 /**
-* xmlStreamPushAttr:
+ * Push new attribute data onto the stream.
  *
-* @stream: the stream context
+ * NOTE: If the call to xmlPatterncompile() indicated a dictionary,
-* @name: the current name
+ * then strings for `name` and `ns` will be expected to come from
-* @ns: the namespace name
+ * the dictionary.
  *
-* Push new attribute data onto the stream. NOTE: if the call xmlPatterncompile()
+ * Both `name` and `ns` being NULL means the root of the document.
-* indicated a dictionary, then strings for name and ns will be expected
+ * This can also act as a reset. Otherwise the function will act as
-* to come from the dictionary.
+ * if it has been given an attribute-node.
-* Both @name and @ns being NULL means the / i.e. the root of the document.
-* This can also act as a reset.
-* Otherwise the function will act as if it has been given an attribute-node.
  *
-* Returns: -1 in case of error, 1 if the current state in the stream is a
+ * @param stream  the stream context
-*    match and 0 otherwise.
+ * @param name  the current name
+ * @param ns  the namespace name
+ * @returns -1 in case of error, 1 if the current state in the stream
+ * is a match and 0 otherwise.
  */
 int
 xmlStreamPushAttr(xmlStreamCtxtPtr stream,

uri.c

@@ -2702,12 +2702,11 @@ done:
     return(ret);
 }
 
-/*
+/**
- * @param URI  the URI reference under consideration
- * @param base  the base value
- *
  * See xmlBuildRelativeURISafe().
  *
+ * @param URI  the URI reference under consideration
+ * @param base  the base value
  * @returns a new URI string (to be freed by the caller) or NULL in case
  * error.
  */

xmlIO.c

@@ -1697,6 +1697,21 @@ xmlParserInputBufferCreateUrl(const char *URI, xmlCharEncoding enc,
     return(ret);
 }
 
+/**
+ * Create a buffered parser input for the progressive parsing of a file
+ * Automatic support for ZLIB/Compress compressed document is provided
+ * by default if found at compile-time.
+ * Do an encoding check if enc == XML_CHAR_ENCODING_NONE
+ *
+ * Internal implementation, never uses the callback installed with
+ * xmlParserInputBufferCreateFilenameDefault().
+ *
+ * @deprecated Use xmlNewInputFromUrl().
+ *
+ * @param URI  a C string containing the URI or filename
+ * @param enc  the charset encoding if known
+ * @returns the new parser input or NULL
+ */
 xmlParserInputBufferPtr
 __xmlParserInputBufferCreateFilename(const char *URI, xmlCharEncoding enc) {
     xmlParserInputBufferPtr ret;
@@ -1711,6 +1726,9 @@ __xmlParserInputBufferCreateFilename(const char *URI, xmlCharEncoding enc) {
  * by default if found at compile-time.
  * Do an encoding check if enc == XML_CHAR_ENCODING_NONE
  *
+ * Allows the actual function to be overridden with
+ * xmlParserInputBufferCreateFilenameDefault().
+ *
  * @deprecated Use xmlNewInputFromUrl().
  *
  * @param URI  a C string containing the URI or filename
@@ -1743,6 +1761,22 @@ xmlParserInputBufferCreateFilename(const char *URI, xmlCharEncoding enc) {
 }
 
 #ifdef LIBXML_OUTPUT_ENABLED
+/**
+ * Create a buffered  output for the progressive saving of a file
+ * If filename is `"-"` then we use stdout as the output.
+ * Automatic support for ZLIB/Compress compressed document is provided
+ * by default if found at compile-time.
+ *
+ * Consumes `encoder` but not in error case.
+ *
+ * Internal implementation, never uses the callback installed with
+ * xmlOutputBufferCreateFilenameDefault().
+ *
+ * @param URI  a C string containing the URI or filename
+ * @param encoder  the encoding converter or NULL
+ * @param compression  the compression ration (0 none, 9 max).
+ * @returns the new output or NULL
+ */
 xmlOutputBufferPtr
 __xmlOutputBufferCreateFilename(const char *URI,
                               xmlCharEncodingHandlerPtr encoder,
@@ -1824,6 +1858,9 @@ error:
  *
  * Consumes `encoder` but not in error case.
  *
+ * Allows the actual function to be overridden with
+ * xmlOutputBufferCreateFilenameDefault().
+ *
  * @param URI  a C string containing the URI or filename
  * @param encoder  the encoding converter or NULL
  * @param compression  the compression ration (0 none, 9 max).

xmlschemastypes.c

@@ -514,8 +514,7 @@ xmlSchemaCleanupTypesInternal(void) {
     /* Note that the xmlSchemaType*Def pointers aren't set to NULL. */
 }
 
-/*
+/**
- *
  * Initialize the default XML Schemas type library
  *
  * @returns 0 on success, -1 on error.