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

include/libxml/parser.h

@@ -27,7 +27,7 @@ extern "C" {
 /**
  * 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 @@ extern "C" {
  * 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 @@ struct _xmlParserInput {
 /**
  * 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 @@ struct _xmlParserNodeInfoSeq {
 /**
  * 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 @@ typedef enum {
 /**
  * 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 @@ typedef enum {
  * 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 @@ typedef enum {
  * 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 @@ struct _xmlParserCtxt {
 /**
  * xmlSAXLocator:
  *
- * a SAX Locator.
+ * A SAX Locator.
  */
 struct _xmlSAXLocator {
     const xmlChar *(*getPublicId)(void *ctx);
@@ -236,7 +236,7 @@ struct _xmlSAXLocator {
 /**
  * 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 @@ typedef void (*externalSubsetSAXFunc) (void *ctx,
  * @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 @@ typedef xmlEntityPtr (*getEntitySAXFunc) (void *ctx,
  * @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 @@ typedef xmlEntityPtr (*getParameterEntitySAXFunc) (void *ctx,
  * @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 @@ typedef void (*notationDeclSAXFunc)(void *ctx,
  * @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 @@ typedef void (*attributeDeclSAXFunc)(void *ctx,
  * @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 @@ typedef void (*elementDeclSAXFunc)(void *ctx,
  * @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 @@ typedef void (*unparsedEntityDeclSAXFunc)(void *ctx,
  * @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 @@ typedef void (*setDocumentLocatorSAXFunc) (void *ctx,
  * 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 @@ typedef void (*endDocumentSAXFunc) (void *ctx);
  * @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 @@ typedef void (*startElementSAXFunc) (void *ctx,
  * @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 @@ typedef void (*attributeSAXFunc) (void *ctx,
  * @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 @@ typedef void (*referenceSAXFunc) (void *ctx,
  * @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 @@ typedef void (*charactersSAXFunc) (void *ctx,
  * @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 @@ typedef void (*commentSAXFunc) (void *ctx,
  * @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 @@ typedef void (*cdataBlockSAXFunc) (
  * @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 @@ typedef void (*warningSAXFunc) (void *ctx,
  * @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 @@ typedef void (*errorSAXFunc) (void *ctx,
  * @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 @@ typedef void (*fatalErrorSAXFunc) (void *ctx,
  * 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 @@ typedef int (*isStandaloneSAXFunc) (void *ctx);
  * 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 @@ typedef int (*hasInternalSubsetSAXFunc) (void *ctx);
  * 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 @@ struct _xmlSAXHandler {
  * @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 @@ LIBXML_DLL_IMPORT extern xmlSAXHandler docbDefaultSAXHandler;
  */
 
 /*
- * 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 @@ int		xmlSetFeature		(xmlParserCtxtPtr ctxt,
 					 void *value);
 
 /*
- * Interfaces for the Push mode
+ * Interfaces for the Push mode.
  */
 xmlParserCtxtPtr xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax,
 					 void *user_data,
@@ -817,7 +817,7 @@ int		 xmlParseChunk		(xmlParserCtxtPtr ctxt,
 					 int terminate);
 
 /*
- * Special I/O mode
+ * Special I/O mode.
  */
 
 xmlParserCtxtPtr xmlCreateIOParserCtxt	(xmlSAXHandlerPtr sax,
@@ -832,7 +832,7 @@ xmlParserInputPtr xmlNewIOInputStream	(xmlParserCtxtPtr ctxt,
 					 xmlCharEncoding enc);
 
 /*
- * Node infos
+ * Node infos.
  */
 const xmlParserNodeInfo*
 		xmlParserFindNodeInfo	(const xmlParserCtxtPtr ctxt,
@@ -845,7 +845,7 @@ void		xmlParserAddNodeInfo	(xmlParserCtxtPtr ctxt,
 					 const xmlParserNodeInfoPtr info);
 
 /*
- * External entities handling actually implemented in xmlIO
+ * External entities handling actually implemented in xmlIO.
  */
 
 void		xmlSetExternalEntityLoader(xmlExternalEntityLoader f);