Build a new version hopefully near complete and fully documented of the
* doc/libxml2-api.xml doc/parsedecl.py: Build a new version
hopefully near complete and fully documented of the API in XML
* HTMLtree.c SAX.c debugXML.c error.c globals.c parser.c tree.c
xmlIO.c xmlmemory.c include/libxml/catalog.h include/libxml/hash.h
include/libxml/list.h include/libxml/parser.h include/libxml/tree.h
include/libxml/parserInternals.h include/libxml/valid.hi
include/libxml/xmlIO.h include/libxml/xmlerror.hi
include/libxml/xmlmemory.h include/libxml/xmlversion.h.ini
include/libxml/xpath.h include/libxml/xpathInternals.h:
Cleaned up the doc comments a lot in the process, the interface
coverage is now 100%
Daniel
diff --git a/include/libxml/parser.h b/include/libxml/parser.h
index 8800fe9..8271bb9 100644
--- a/include/libxml/parser.h
+++ b/include/libxml/parser.h
@@ -37,7 +37,13 @@
* progressive reading and I18N conversions to the internal UTF-8 format.
*/
-typedef void (* xmlParserInputDeallocate)(xmlChar *);
+/**
+ * xmlParserInputDeallocate:
+ * @str: the string to deallocate
+ *
+ * Callback for freeing some parser input allocations
+ */
+typedef void (* xmlParserInputDeallocate)(xmlChar *str);
struct _xmlParserInput {
/* Input buffer */
@@ -237,52 +243,327 @@
* of the input generate data or structure informations.
*/
+/**
+ * resolveEntitySAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @publicId: The public ID of the entity
+ * @systemId: The system ID of the entity
+ *
+ * Callback:
+ * The entity loader, to control the loading of external entities,
+ * the application can either:
+ * - override this resolveEntity() callback in the SAX block
+ * - or better use the xmlSetExternalEntityLoader() function to
+ * set up it's own entity resolution routine
+ *
+ * Returns the xmlParserInputPtr if inlined or NULL for DOM behaviour.
+ */
typedef xmlParserInputPtr (*resolveEntitySAXFunc) (void *ctx,
- const xmlChar *publicId, const xmlChar *systemId);
-typedef void (*internalSubsetSAXFunc) (void *ctx, const xmlChar *name,
- const xmlChar *ExternalID, const xmlChar *SystemID);
-typedef void (*externalSubsetSAXFunc) (void *ctx, const xmlChar *name,
- const xmlChar *ExternalID, const xmlChar *SystemID);
+ const xmlChar *publicId,
+ const xmlChar *systemId);
+/**
+ * internalSubsetSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: the root element name
+ * @ExternalID: the external ID
+ * @SystemID: the SYSTEM ID (e.g. filename or URL)
+ *
+ * Callback on internal subset declaration.
+ */
+typedef void (*internalSubsetSAXFunc) (void *ctx,
+ const xmlChar *name,
+ const xmlChar *ExternalID,
+ const xmlChar *SystemID);
+/**
+ * externalSubsetSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: the root element name
+ * @ExternalID: the external ID
+ * @SystemID: the SYSTEM ID (e.g. filename or URL)
+ *
+ * Callback on external subset declaration.
+ */
+typedef void (*externalSubsetSAXFunc) (void *ctx,
+ const xmlChar *name,
+ const xmlChar *ExternalID,
+ const xmlChar *SystemID);
+/**
+ * getEntitySAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: The entity name
+ *
+ * Get an entity by name
+ *
+ * Returns the xmlEntityPtr if found.
+ */
typedef xmlEntityPtr (*getEntitySAXFunc) (void *ctx,
- const xmlChar *name);
+ const xmlChar *name);
+/**
+ * getParameterEntitySAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: The entity name
+ *
+ * Get a parameter entity by name
+ *
+ * Returns the xmlEntityPtr if found.
+ */
typedef xmlEntityPtr (*getParameterEntitySAXFunc) (void *ctx,
- const xmlChar *name);
+ const xmlChar *name);
+/**
+ * entityDeclSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: the entity name
+ * @type: the entity type
+ * @publicId: The public ID of the entity
+ * @systemId: The system ID of the entity
+ * @content: the entity value (without processing).
+ *
+ * An entity definition has been parsed
+ */
typedef void (*entityDeclSAXFunc) (void *ctx,
- const xmlChar *name, int type, const xmlChar *publicId,
- const xmlChar *systemId, xmlChar *content);
-typedef void (*notationDeclSAXFunc)(void *ctx, const xmlChar *name,
- const xmlChar *publicId, const xmlChar *systemId);
-typedef void (*attributeDeclSAXFunc)(void *ctx, const xmlChar *elem,
- const xmlChar *name, int type, int def,
- const xmlChar *defaultValue, xmlEnumerationPtr tree);
-typedef void (*elementDeclSAXFunc)(void *ctx, const xmlChar *name,
- int type, xmlElementContentPtr content);
+ const xmlChar *name,
+ int type,
+ const xmlChar *publicId,
+ const xmlChar *systemId,
+ xmlChar *content);
+/**
+ * notationDeclSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: The name of the notation
+ * @publicId: The public ID of the entity
+ * @systemId: The system ID of the entity
+ *
+ * What to do when a notation declaration has been parsed.
+ */
+typedef void (*notationDeclSAXFunc)(void *ctx,
+ const xmlChar *name,
+ const xmlChar *publicId,
+ const xmlChar *systemId);
+/**
+ * attributeDeclSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @elem: the name of the element
+ * @fullname: the attribute name
+ * @type: the attribute type
+ * @def: the type of default value
+ * @defaultValue: the attribute default value
+ * @tree: the tree of enumerated value set
+ *
+ * An attribute definition has been parsed
+ */
+typedef void (*attributeDeclSAXFunc)(void *ctx,
+ const xmlChar *elem,
+ const xmlChar *fullname,
+ int type,
+ int def,
+ const xmlChar *defaultValue,
+ xmlEnumerationPtr tree);
+/**
+ * elementDeclSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: the element name
+ * @type: the element type
+ * @content: the element value tree
+ *
+ * An element definition has been parsed
+ */
+typedef void (*elementDeclSAXFunc)(void *ctx,
+ const xmlChar *name,
+ int type,
+ xmlElementContentPtr content);
+/**
+ * unparsedEntityDeclSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: The name of the entity
+ * @publicId: The public ID of the entity
+ * @systemId: The system ID of the entity
+ * @notationName: the name of the notation
+ *
+ * What to do when an unparsed entity declaration is parsed
+ */
typedef void (*unparsedEntityDeclSAXFunc)(void *ctx,
- const xmlChar *name, const xmlChar *publicId,
- const xmlChar *systemId, const xmlChar *notationName);
+ const xmlChar *name,
+ const xmlChar *publicId,
+ const xmlChar *systemId,
+ const xmlChar *notationName);
+/**
+ * setDocumentLocatorSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @loc: A SAX Locator
+ *
+ * Receive the document locator at startup, actually xmlDefaultSAXLocator
+ * Everything is available on the context, so this is useless in our case.
+ */
typedef void (*setDocumentLocatorSAXFunc) (void *ctx,
- xmlSAXLocatorPtr loc);
+ xmlSAXLocatorPtr loc);
+/**
+ * startDocumentSAXFunc:
+ * @ctx: the user data (XML parser context)
+ *
+ * called when the document start being processed.
+ */
typedef void (*startDocumentSAXFunc) (void *ctx);
+/**
+ * endDocumentSAXFunc:
+ * @ctx: the user data (XML parser context)
+ *
+ * called when the document end has been detected.
+ */
typedef void (*endDocumentSAXFunc) (void *ctx);
-typedef void (*startElementSAXFunc) (void *ctx, const xmlChar *name,
- const xmlChar **atts);
-typedef void (*endElementSAXFunc) (void *ctx, const xmlChar *name);
-typedef void (*attributeSAXFunc) (void *ctx, const xmlChar *name,
- const xmlChar *value);
-typedef void (*referenceSAXFunc) (void *ctx, const xmlChar *name);
-typedef void (*charactersSAXFunc) (void *ctx, const xmlChar *ch,
- int len);
+/**
+ * startElementSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: The element name, including namespace prefix
+ * @atts: An array of name/value attributes pairs, NULL terminated
+ *
+ * called when an opening tag has been processed.
+ */
+typedef void (*startElementSAXFunc) (void *ctx,
+ const xmlChar *name,
+ const xmlChar **atts);
+/**
+ * endElementSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: The element name
+ *
+ * called when the end of an element has been detected.
+ */
+typedef void (*endElementSAXFunc) (void *ctx,
+ const xmlChar *name);
+/**
+ * attributeSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: The attribute name, including namespace prefix
+ * @value: The attribute value
+ *
+ * Handle an attribute that has been read by the parser.
+ * The default handling is to convert the attribute into an
+ * DOM subtree and past it in a new xmlAttr element added to
+ * the element.
+ */
+typedef void (*attributeSAXFunc) (void *ctx,
+ const xmlChar *name,
+ const xmlChar *value);
+/**
+ * referenceSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @name: The entity name
+ *
+ * called when an entity reference is detected.
+ */
+typedef void (*referenceSAXFunc) (void *ctx,
+ const xmlChar *name);
+/**
+ * charactersSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @ch: a xmlChar string
+ * @len: the number of xmlChar
+ *
+ * receiving some chars from the parser.
+ */
+typedef void (*charactersSAXFunc) (void *ctx,
+ const xmlChar *ch,
+ int len);
+/**
+ * ignorableWhitespaceSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @ch: a xmlChar string
+ * @len: the number of xmlChar
+ *
+ * receiving some ignorable whitespaces from the parser.
+ * UNUSED: by default the DOM building will use characters
+ */
typedef void (*ignorableWhitespaceSAXFunc) (void *ctx,
- const xmlChar *ch, int len);
+ const xmlChar *ch,
+ int len);
+/**
+ * processingInstructionSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @target: the target name
+ * @data: the PI data's
+ *
+ * A processing instruction has been parsed.
+ */
typedef void (*processingInstructionSAXFunc) (void *ctx,
- const xmlChar *target, const xmlChar *data);
-typedef void (*commentSAXFunc) (void *ctx, const xmlChar *value);
-typedef void (*cdataBlockSAXFunc) (void *ctx, const xmlChar *value, int len);
-typedef void (*warningSAXFunc) (void *ctx, const char *msg, ...);
-typedef void (*errorSAXFunc) (void *ctx, const char *msg, ...);
-typedef void (*fatalErrorSAXFunc) (void *ctx, const char *msg, ...);
+ const xmlChar *target,
+ const xmlChar *data);
+/**
+ * commentSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @value: the comment content
+ *
+ * A comment has been parsed.
+ */
+typedef void (*commentSAXFunc) (void *ctx,
+ const xmlChar *value);
+/**
+ * cdataBlockSAXFunc:
+ * @ctx: the user data (XML parser context)
+ * @value: The pcdata content
+ * @len: the block length
+ *
+ * called when a pcdata block has been parsed
+ */
+typedef void (*cdataBlockSAXFunc) (
+ void *ctx,
+ const xmlChar *value,
+ int len);
+/**
+ * warningSAXFunc:
+ * @ctx: an XML parser context
+ * @msg: the message to display/transmit
+ * @...: extra parameters for the message display
+ *
+ * Display and format a warning messages, callback
+ */
+typedef void (*warningSAXFunc) (void *ctx,
+ const char *msg, ...);
+/**
+ * errorSAXFunc:
+ * @ctx: an XML parser context
+ * @msg: the message to display/transmit
+ * @...: extra parameters for the message display
+ *
+ * Display and format an error messages, callback
+ */
+typedef void (*errorSAXFunc) (void *ctx,
+ const char *msg, ...);
+/**
+ * fatalErrorSAXFunc:
+ * @ctx: an XML parser context
+ * @msg: the message to display/transmit
+ * @...: extra parameters for the message display
+ *
+ * Display and format fatal error messages, callback
+ */
+typedef void (*fatalErrorSAXFunc) (void *ctx,
+ const char *msg, ...);
+/**
+ * isStandaloneSAXFunc:
+ * @ctx: the user data (XML parser context)
+ *
+ * Is this document tagged standalone ?
+ *
+ * Returns 1 if true
+ */
typedef int (*isStandaloneSAXFunc) (void *ctx);
+/**
+ * hasInternalSubsetSAXFunc:
+ * @ctx: the user data (XML parser context)
+ *
+ * Does this document has an internal subset
+ *
+ * Returns 1 if true
+ */
typedef int (*hasInternalSubsetSAXFunc) (void *ctx);
+/**
+ * hasExternalSubsetSAXFunc:
+ * @ctx: the user data (XML parser context)
+ *
+ * Does this document has an external subset
+ *
+ * Returns 1 if true
+ */
typedef int (*hasExternalSubsetSAXFunc) (void *ctx);
typedef struct _xmlSAXHandler xmlSAXHandler;
@@ -328,9 +609,9 @@
*
* Returns the entity input parser
*/
-typedef xmlParserInputPtr (*xmlExternalEntityLoader)(const char *URL,
- const char *ID,
- xmlParserCtxtPtr context);
+typedef xmlParserInputPtr (*xmlExternalEntityLoader) (const char *URL,
+ const char *ID,
+ xmlParserCtxtPtr context);
/*
* Global variables: just the default SAX interface tables and XML
@@ -569,7 +850,7 @@
xmlParserInputPtr
xmlLoadExternalEntity (const char *URL,
const char *ID,
- xmlParserCtxtPtr context);
+ xmlParserCtxtPtr ctxt);
#ifdef __cplusplus
}