Heiko W. Rupp fixed a lot of comments to generate better API descriptions
* include/libxml/*.h: Heiko W. Rupp fixed a lot of comments
to generate better API descriptions etc...
Daniel
diff --git a/include/libxml/parser.h b/include/libxml/parser.h
index 341c559..cd48dc5 100644
--- a/include/libxml/parser.h
+++ b/include/libxml/parser.h
@@ -27,7 +27,7 @@
/**
* xmlParserInput:
*
- * an xmlParserInput is an input flow for the XML processor.
+ * An xmlParserInput is an input flow for the XML processor.
* Each entity parsed is associated an xmlParserInput (except the
* few predefined ones). This is the case both for internal entities
* - in which case the flow is already completely in memory - or
@@ -39,7 +39,7 @@
* xmlParserInputDeallocate:
* @str: the string to deallocate
*
- * Callback for freeing some parser input allocations
+ * Callback for freeing some parser input allocations.
*/
typedef void (* xmlParserInputDeallocate)(xmlChar *str);
@@ -65,7 +65,7 @@
/**
* xmlParserNodeInfo:
*
- * the parser can be asked to collect Node informations, i.e. at what
+ * The parser can be asked to collect Node informations, i.e. at what
* place in the file they were detected.
* NOTE: This is off by default and not very well tested.
*/
@@ -92,8 +92,8 @@
/**
* xmlParserInputState:
*
- * The parser is now working also as a state based parser
- * The recursive one use the state info for entities processing
+ * The parser is now working also as a state based parser.
+ * The recursive one use the state info for entities processing.
*/
typedef enum {
XML_PARSER_EOF = -1, /* nothing is to be parsed */
@@ -119,8 +119,8 @@
/**
* XML_DETECT_IDS:
*
- * Bit in the loadsubset context field to tell to do ID/REFs lookups
- * Use it to initialize xmlLoadExtDtdDefaultValue
+ * Bit in the loadsubset context field to tell to do ID/REFs lookups.
+ * Use it to initialize xmlLoadExtDtdDefaultValue.
*/
#define XML_DETECT_IDS 2
@@ -128,8 +128,8 @@
* XML_COMPLETE_ATTRS:
*
* Bit in the loadsubset context field to tell to do complete the
- * elements attributes lists with the ones defaulted from the DTDs
- * Use it to initialize xmlLoadExtDtdDefaultValue
+ * elements attributes lists with the ones defaulted from the DTDs.
+ * Use it to initialize xmlLoadExtDtdDefaultValue.
*/
#define XML_COMPLETE_ATTRS 4
@@ -137,7 +137,7 @@
* xmlParserCtxt:
*
* The parser context.
- * NOTE This doesn't completely defines the parser state, the (current ?)
+ * NOTE This doesn't completely define the parser state, the (current ?)
* design of the parser uses recursive function calls since this allow
* and easy mapping from the production rules of the specification
* to the actual code. The drawback is that the actual function call
@@ -224,7 +224,7 @@
/**
* xmlSAXLocator:
*
- * a SAX Locator.
+ * A SAX Locator.
*/
struct _xmlSAXLocator {
const xmlChar *(*getPublicId)(void *ctx);
@@ -236,7 +236,7 @@
/**
* xmlSAXHandler:
*
- * a SAX handler is bunch of callbacks called by the parser when processing
+ * A SAX handler is bunch of callbacks called by the parser when processing
* of the input generate data or structure informations.
*/
@@ -289,7 +289,7 @@
* @ctx: the user data (XML parser context)
* @name: The entity name
*
- * Get an entity by name
+ * Get an entity by name.
*
* Returns the xmlEntityPtr if found.
*/
@@ -300,7 +300,7 @@
* @ctx: the user data (XML parser context)
* @name: The entity name
*
- * Get a parameter entity by name
+ * Get a parameter entity by name.
*
* Returns the xmlEntityPtr if found.
*/
@@ -315,7 +315,7 @@
* @systemId: The system ID of the entity
* @content: the entity value (without processing).
*
- * An entity definition has been parsed
+ * An entity definition has been parsed.
*/
typedef void (*entityDeclSAXFunc) (void *ctx,
const xmlChar *name,
@@ -346,7 +346,7 @@
* @defaultValue: the attribute default value
* @tree: the tree of enumerated value set
*
- * An attribute definition has been parsed
+ * An attribute definition has been parsed.
*/
typedef void (*attributeDeclSAXFunc)(void *ctx,
const xmlChar *elem,
@@ -362,7 +362,7 @@
* @type: the element type
* @content: the element value tree
*
- * An element definition has been parsed
+ * An element definition has been parsed.
*/
typedef void (*elementDeclSAXFunc)(void *ctx,
const xmlChar *name,
@@ -376,7 +376,7 @@
* @systemId: The system ID of the entity
* @notationName: the name of the notation
*
- * What to do when an unparsed entity declaration is parsed
+ * What to do when an unparsed entity declaration is parsed.
*/
typedef void (*unparsedEntityDeclSAXFunc)(void *ctx,
const xmlChar *name,
@@ -388,7 +388,7 @@
* @ctx: the user data (XML parser context)
* @loc: A SAX Locator
*
- * Receive the document locator at startup, actually xmlDefaultSAXLocator
+ * 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,
@@ -397,14 +397,14 @@
* startDocumentSAXFunc:
* @ctx: the user data (XML parser context)
*
- * called when the document start being processed.
+ * 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.
+ * Called when the document end has been detected.
*/
typedef void (*endDocumentSAXFunc) (void *ctx);
/**
@@ -413,7 +413,7 @@
* @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.
+ * Called when an opening tag has been processed.
*/
typedef void (*startElementSAXFunc) (void *ctx,
const xmlChar *name,
@@ -423,7 +423,7 @@
* @ctx: the user data (XML parser context)
* @name: The element name
*
- * called when the end of an element has been detected.
+ * Called when the end of an element has been detected.
*/
typedef void (*endElementSAXFunc) (void *ctx,
const xmlChar *name);
@@ -446,7 +446,7 @@
* @ctx: the user data (XML parser context)
* @name: The entity name
*
- * called when an entity reference is detected.
+ * Called when an entity reference is detected.
*/
typedef void (*referenceSAXFunc) (void *ctx,
const xmlChar *name);
@@ -456,7 +456,7 @@
* @ch: a xmlChar string
* @len: the number of xmlChar
*
- * receiving some chars from the parser.
+ * Receiving some chars from the parser.
*/
typedef void (*charactersSAXFunc) (void *ctx,
const xmlChar *ch,
@@ -467,8 +467,8 @@
* @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
+ * Receiving some ignorable whitespaces from the parser.
+ * UNUSED: by default the DOM building will use characters.
*/
typedef void (*ignorableWhitespaceSAXFunc) (void *ctx,
const xmlChar *ch,
@@ -499,7 +499,7 @@
* @value: The pcdata content
* @len: the block length
*
- * called when a pcdata block has been parsed
+ * Called when a pcdata block has been parsed.
*/
typedef void (*cdataBlockSAXFunc) (
void *ctx,
@@ -511,7 +511,7 @@
* @msg: the message to display/transmit
* @...: extra parameters for the message display
*
- * Display and format a warning messages, callback
+ * Display and format a warning messages, callback.
*/
typedef void (*warningSAXFunc) (void *ctx,
const char *msg, ...);
@@ -521,7 +521,7 @@
* @msg: the message to display/transmit
* @...: extra parameters for the message display
*
- * Display and format an error messages, callback
+ * Display and format an error messages, callback.
*/
typedef void (*errorSAXFunc) (void *ctx,
const char *msg, ...);
@@ -531,7 +531,7 @@
* @msg: the message to display/transmit
* @...: extra parameters for the message display
*
- * Display and format fatal error messages, callback
+ * Display and format fatal error messages, callback.
*/
typedef void (*fatalErrorSAXFunc) (void *ctx,
const char *msg, ...);
@@ -539,7 +539,7 @@
* isStandaloneSAXFunc:
* @ctx: the user data (XML parser context)
*
- * Is this document tagged standalone ?
+ * Is this document tagged standalone?
*
* Returns 1 if true
*/
@@ -548,7 +548,7 @@
* hasInternalSubsetSAXFunc:
* @ctx: the user data (XML parser context)
*
- * Does this document has an internal subset
+ * Does this document has an internal subset.
*
* Returns 1 if true
*/
@@ -557,7 +557,7 @@
* hasExternalSubsetSAXFunc:
* @ctx: the user data (XML parser context)
*
- * Does this document has an external subset
+ * Does this document has an external subset?
*
* Returns 1 if true
*/
@@ -600,9 +600,9 @@
* @ID: The Public ID of the resource requested
* @context: the XML parser context
*
- * External entity loaders types
+ * External entity loaders types.
*
- * Returns the entity input parser
+ * Returns the entity input parser.
*/
typedef xmlParserInputPtr (*xmlExternalEntityLoader) (const char *URL,
const char *ID,
@@ -624,14 +624,14 @@
*/
/*
- * entity substitution default behavior.
+ * Entity substitution default behavior.
*/
#ifdef VMS
/**
* xmlSubstituteEntitiesDefaultValue:
*
- * global variable controlling the entity substitution default behavior
+ * Global variable controlling the entity substitution default behavior.
*/
LIBXML_DLL_IMPORT extern int xmlSubstituteEntitiesDefaultVal;
#define xmlSubstituteEntitiesDefaultValue xmlSubstituteEntitiesDefaultVal
@@ -804,7 +804,7 @@
void *value);
/*
- * Interfaces for the Push mode
+ * Interfaces for the Push mode.
*/
xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
void *user_data,
@@ -817,7 +817,7 @@
int terminate);
/*
- * Special I/O mode
+ * Special I/O mode.
*/
xmlParserCtxtPtr xmlCreateIOParserCtxt (xmlSAXHandlerPtr sax,
@@ -832,7 +832,7 @@
xmlCharEncoding enc);
/*
- * Node infos
+ * Node infos.
*/
const xmlParserNodeInfo*
xmlParserFindNodeInfo (const xmlParserCtxtPtr ctxt,
@@ -845,7 +845,7 @@
const xmlParserNodeInfoPtr info);
/*
- * External entities handling actually implemented in xmlIO
+ * External entities handling actually implemented in xmlIO.
*/
void xmlSetExternalEntityLoader(xmlExternalEntityLoader f);