Commit 61f26174 authored by Daniel Veillard's avatar Daniel Veillard

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
parent 9ff8817e
Tue Mar 12 19:45:24 CET 2002 Daniel Veillard <daniel@veillard.com>
* include/libxml/*.h: Heiko W. Rupp fixed a lot of comments
to generate better API descriptions etc...
Mon Mar 11 10:10:30 CET 2002 Daniel Veillard <daniel@veillard.com>
* c14n.c: Fixing #74186, made sure all boolean expressions
......
......@@ -15,7 +15,7 @@ extern "C" {
#endif
/*
* Most of the back-end structures from XML and SGML are shared
* Most of the back-end structures from XML and SGML are shared.
*/
typedef xmlParserCtxt docbParserCtxt;
typedef xmlParserCtxtPtr docbParserCtxtPtr;
......@@ -49,7 +49,7 @@ docbDocPtr docbParseFile (const char *filename,
const char *encoding);
/**
* Interfaces for the Push mode
* Interfaces for the Push mode.
*/
void docbFreeParserCtxt (docbParserCtxtPtr ctxt);
docbParserCtxtPtr docbCreatePushParserCtxt(docbSAXHandlerPtr sax,
......
......@@ -15,7 +15,7 @@ extern "C" {
#endif
/*
* Most of the back-end structures from XML and HTML are shared
* Most of the back-end structures from XML and HTML are shared.
*/
typedef xmlParserCtxt htmlParserCtxt;
typedef xmlParserCtxtPtr htmlParserCtxtPtr;
......@@ -28,7 +28,7 @@ typedef xmlDocPtr htmlDocPtr;
typedef xmlNodePtr htmlNodePtr;
/*
* Internal description of an HTML element
* Internal description of an HTML element.
*/
typedef struct _htmlElemDesc htmlElemDesc;
typedef htmlElemDesc *htmlElemDescPtr;
......@@ -45,7 +45,7 @@ struct _htmlElemDesc {
};
/*
* Internal description of an HTML entity
* Internal description of an HTML entity.
*/
typedef struct _htmlEntityDesc htmlEntityDesc;
typedef htmlEntityDesc *htmlEntityDescPtr;
......@@ -96,7 +96,7 @@ int htmlIsScriptAttribute(const xmlChar *name);
int htmlHandleOmittedElem(int val);
/**
* Interfaces for the Push mode
* Interfaces for the Push mode.
*/
void htmlFreeParserCtxt (htmlParserCtxtPtr ctxt);
htmlParserCtxtPtr htmlCreatePushParserCtxt(htmlSAXHandlerPtr sax,
......
......@@ -22,35 +22,35 @@ extern "C" {
/**
* HTML_TEXT_NODE:
*
* Macro, a text node in a HTML document is really implemented
* Macro. A text node in a HTML document is really implemented
* the same way as a text node in an XML document.
*/
#define HTML_TEXT_NODE XML_TEXT_NODE
/**
* HTML_ENTITY_REF_NODE:
*
* Macro, an entity reference in a HTML document is really implemented
* Macro. An entity reference in a HTML document is really implemented
* the same way as an entity reference in an XML document.
*/
#define HTML_ENTITY_REF_NODE XML_ENTITY_REF_NODE
/**
* HTML_COMMENT_NODE:
*
* Macro, a comment in a HTML document is really implemented
* Macro. A comment in a HTML document is really implemented
* the same way as a comment in an XML document.
*/
#define HTML_COMMENT_NODE XML_COMMENT_NODE
/**
* HTML_PRESERVE_NODE:
*
* Macro, a preserved node in a HTML document is really implemented
* Macro. A preserved node in a HTML document is really implemented
* the same way as a CDATA section in an XML document.
*/
#define HTML_PRESERVE_NODE XML_CDATA_SECTION_NODE
/**
* HTML_PI_NODE:
*
* Macro, a processing instruction in a HTML document is really implemented
* Macro. A processing instruction in a HTML document is really implemented
* the same way as a processing instruction in an XML document.
*/
#define HTML_PI_NODE XML_PI_NODE
......
......@@ -31,20 +31,20 @@ extern "C" {
/**
* XML_CATALOGS_NAMESPACE:
*
* The namespace for the XML Catalogs elements
* The namespace for the XML Catalogs elements.
*/
#define XML_CATALOGS_NAMESPACE \
(const xmlChar *) "urn:oasis:names:tc:entity:xmlns:xml:catalog"
/**
* XML_CATALOG_PI:
*
* the specific XML Catalog Processing Instuction name
* The specific XML Catalog Processing Instuction name.
*/
#define XML_CATALOG_PI \
(const xmlChar *) "oasis-xml-catalog"
/*
* The API is voluntarily limited to general cataloging
* The API is voluntarily limited to general cataloging.
*/
typedef enum {
XML_CATA_PREFER_NONE = 0,
......@@ -63,7 +63,7 @@ typedef struct _xmlCatalog xmlCatalog;
typedef xmlCatalog *xmlCatalogPtr;
/*
* Operations on a given catalog
* Operations on a given catalog.
*/
xmlCatalogPtr xmlNewCatalog (int sgml);
xmlCatalogPtr xmlLoadACatalog (const char *filename);
......@@ -90,7 +90,7 @@ void xmlFreeCatalog (xmlCatalogPtr catal);
int xmlCatalogIsEmpty (xmlCatalogPtr catal);
/*
* Global operations
* Global operations.
*/
void xmlInitializeCatalog (void);
int xmlLoadCatalog (const char *filename);
......@@ -122,7 +122,7 @@ xmlChar * xmlCatalogLocalResolve (void *catalogs,
xmlChar * xmlCatalogLocalResolveURI(void *catalogs,
const xmlChar *URI);
/*
* Preference settings
* Preference settings.
*/
int xmlCatalogSetDebug (int level);
xmlCatalogPrefer xmlCatalogSetDefaultPrefer(xmlCatalogPrefer prefer);
......
......@@ -19,7 +19,7 @@ extern "C" {
#endif
/*
* The standard Dump routines
* The standard Dump routines.
*/
void xmlDebugDumpString (FILE *output,
const xmlChar *str);
......@@ -62,16 +62,16 @@ LIBXML_DLL_IMPORT const char *xmlBoolToText (int boolval);
* xmlShellReadlineFunc:
* @prompt: a string prompt
*
* This is a generic signature for the XML shell input function
* This is a generic signature for the XML shell input function.
*
* Returns a string which will be freed by the Shell
* Returns a string which will be freed by the Shell.
*/
typedef char * (* xmlShellReadlineFunc)(char *prompt);
/**
* xmlShellCtxt:
*
* A debugging shell context
* A debugging shell context.
* TODO: add the defined function tables.
*/
typedef struct _xmlShellCtxt xmlShellCtxt;
......@@ -93,9 +93,9 @@ struct _xmlShellCtxt {
* @node: a first node
* @node2: a second node
*
* This is a generic signature for the XML shell functions
* This is a generic signature for the XML shell functions.
*
* Returns an int, negative returns indicating errors
* Returns an int, negative returns indicating errors.
*/
typedef int (* xmlShellCmd) (xmlShellCtxtPtr ctxt,
char *arg,
......
......@@ -36,8 +36,8 @@ extern "C" {
/**
* xmlCharEncoding:
*
* Predefined values for some standard encodings
* Libxml don't do beforehand translation on UTF8, ISOLatinX
* Predefined values for some standard encodings.
* Libxml don't do beforehand translation on UTF8, ISOLatinX.
* It also support UTF16 (LE and BE) by default.
*
* Anything else would have to be translated to UTF8 before being
......@@ -108,7 +108,7 @@ typedef int (* xmlCharEncodingInputFunc)(unsigned char *out, int *outlen,
* Take a block of UTF-8 chars in and try to convert it to an other
* encoding.
* Note: a first call designed to produce heading info is called with
* in = NULL. If stateful this should also initialize the encoder state
* in = NULL. If stateful this should also initialize the encoder state.
*
* Returns the number of byte written, or -1 by lack of space, or -2
* if the transcoding failed.
......@@ -122,7 +122,7 @@ typedef int (* xmlCharEncodingOutputFunc)(unsigned char *out, int *outlen,
/*
* Block defining the handlers for non UTF-8 encodings.
* If iconv is supported, there is two extra fields
* If iconv is supported, there is two extra fields.
*/
typedef struct _xmlCharEncodingHandler xmlCharEncodingHandler;
......@@ -146,7 +146,7 @@ extern "C" {
#endif
/*
* Interfaces for encoding handlers
* Interfaces for encoding handlers.
*/
void xmlInitCharEncodingHandlers (void);
void xmlCleanupCharEncodingHandlers (void);
......@@ -158,7 +158,7 @@ xmlCharEncodingHandlerPtr
/*
* Interfaces for encoding names and aliases
* Interfaces for encoding names and aliases.
*/
int xmlAddEncodingAlias (const char *name,
const char *alias);
......@@ -202,7 +202,7 @@ int isolat1ToUTF8 (unsigned char *out,
const unsigned char *in,
int *inlen);
/*
* exports additional "UTF-8 aware" string routines which are
* exports additional "UTF-8 aware" string routines which are.
*/
int xmlCheckUTF8 (const unsigned char *utf);
......
......@@ -16,7 +16,7 @@ extern "C" {
#endif
/*
* The different valid entity types
* The different valid entity types.
*/
typedef enum {
XML_INTERNAL_GENERAL_ENTITY = 1,
......@@ -55,15 +55,15 @@ struct _xmlEntity {
};
/*
* All entities are stored in an hash table
* there is 2 separate hash tables for global and parameter entities
* All entities are stored in an hash table.
* There is 2 separate hash tables for global and parameter entities.
*/
typedef struct _xmlHashTable xmlEntitiesTable;
typedef xmlEntitiesTable *xmlEntitiesTablePtr;
/*
* External functions :
* External functions:
*/
void xmlInitializePredefinedEntities (void);
......
......@@ -25,7 +25,7 @@ extern "C" {
#endif
/*
* The hash table
* The hash table.
*/
typedef struct _xmlHashTable xmlHashTable;
typedef xmlHashTable *xmlHashTablePtr;
......@@ -38,7 +38,7 @@ typedef xmlHashTable *xmlHashTablePtr;
* @payload: the data in the hash
* @name: the name associated
*
* Callback to free data from a hash
* Callback to free data from a hash.
*/
typedef void (*xmlHashDeallocator)(void *payload, xmlChar *name);
/**
......@@ -46,9 +46,9 @@ typedef void (*xmlHashDeallocator)(void *payload, xmlChar *name);
* @payload: the data in the hash
* @name: the name associated
*
* Callback to copy data from a hash
* Callback to copy data from a hash.
*
* Returns a copy of the data or NULL in case of error
* Returns a copy of the data or NULL in case of error.
*/
typedef void *(*xmlHashCopier)(void *payload, xmlChar *name);
/**
......@@ -57,7 +57,7 @@ typedef void *(*xmlHashCopier)(void *payload, xmlChar *name);
* @data: extra scannner data
* @name: the name associated
*
* Callback when scanning data in a hash with the simple scanner
* Callback when scanning data in a hash with the simple scanner.
*/
typedef void (*xmlHashScanner)(void *payload, void *data, xmlChar *name);
/**
......@@ -68,21 +68,21 @@ typedef void (*xmlHashScanner)(void *payload, void *data, xmlChar *name);
* @name2: the second name associated
* @name3: the third name associated
*
* Callback when scanning data in a hash with the full scanner
* Callback when scanning data in a hash with the full scanner.
*/
typedef void (*xmlHashScannerFull)(void *payload, void *data,
const xmlChar *name, const xmlChar *name2,
const xmlChar *name3);
/*
* Constructor and destructor
* Constructor and destructor.
*/
xmlHashTablePtr xmlHashCreate (int size);
void xmlHashFree (xmlHashTablePtr table,
xmlHashDeallocator f);
/*
* Add a new entry to the hash table
* Add a new entry to the hash table.
*/
int xmlHashAddEntry (xmlHashTablePtr table,
const xmlChar *name,
......@@ -113,7 +113,7 @@ int xmlHashUpdateEntry3(xmlHashTablePtr table,
xmlHashDeallocator f);
/*
* Remove an entry from the hash table
* Remove an entry from the hash table.
*/
int xmlHashRemoveEntry(xmlHashTablePtr table, const xmlChar *name,
xmlHashDeallocator f);
......@@ -124,7 +124,7 @@ int xmlHashRemoveEntry3(xmlHashTablePtr table, const xmlChar *name,
xmlHashDeallocator f);
/*
* Retrieve the userdata
* Retrieve the userdata.
*/
void * xmlHashLookup (xmlHashTablePtr table,
const xmlChar *name);
......@@ -137,7 +137,7 @@ void * xmlHashLookup3 (xmlHashTablePtr table,
const xmlChar *name3);
/*
* Helpers
* Helpers.
*/
xmlHashTablePtr xmlHashCopy (xmlHashTablePtr table,
xmlHashCopier f);
......
......@@ -32,7 +32,7 @@ typedef xmlList *xmlListPtr;
* xmlListDeallocator:
* @lk: the data to deallocate
*
* Callback function used to free data from a list
* Callback function used to free data from a list.
*/
typedef void (*xmlListDeallocator) (xmlLinkPtr lk);
/**
......@@ -40,9 +40,9 @@ typedef void (*xmlListDeallocator) (xmlLinkPtr lk);
* @data0: the first data
* @data1: the second data
*
* Callback function used to compare 2 data
* Callback function used to compare 2 data.
*
* Returns 0 is equality, -1 or 1 otherwise depending on the ordering
* Returns 0 is equality, -1 or 1 otherwise depending on the ordering.
*/
typedef int (*xmlListDataCompare) (const void *data0, const void *data1);
/**
......@@ -50,9 +50,9 @@ typedef int (*xmlListDataCompare) (const void *data0, const void *data1);
* @data: the data found in the list
* @user: extra user provided data to the walker
*
* Callback function used when walking a list with xmlListWalk()
* Callback function used when walking a list with xmlListWalk().
*
* Returns 0 to stop walking the list, 1 otherwise
* Returns 0 to stop walking the list, 1 otherwise.
*/
typedef int (*xmlListWalker) (const void *data, const void *user);
......
......@@ -35,8 +35,8 @@ extern "C" {
* @hour: the hour
* @minute: the minute
*
* A callback for the xmlNanoFTPList command
* Note that only one of year and day:minute are specified
* A callback for the xmlNanoFTPList command.
* Note that only one of year and day:minute are specified.
*/
typedef void (*ftpListCallback) (void *userData,
const char *filename, const char *attrib,
......@@ -50,7 +50,7 @@ typedef void (*ftpListCallback) (void *userData,
* @data: the data received
* @len: its size in bytes
*
* A callback for the xmlNanoFTPGet command
* A callback for the xmlNanoFTPGet command.
*/
typedef void (*ftpDataCallback) (void *userData,
const char *data,
......@@ -63,14 +63,14 @@ void xmlNanoFTPInit (void);
void xmlNanoFTPCleanup (void);
/*
* Creating/freeing contexts
* Creating/freeing contexts.
*/
void * xmlNanoFTPNewCtxt (const char *URL);
void xmlNanoFTPFreeCtxt (void * ctx);
void * xmlNanoFTPConnectTo (const char *server,
int port);
/*
* Opening/closing session connections
* Opening/closing session connections.
*/
void * xmlNanoFTPOpen (const char *URL);
int xmlNanoFTPConnect (void *ctx);
......@@ -86,13 +86,13 @@ int xmlNanoFTPUpdateURL (void *ctx,
const char *URL);
/*
* Rathern internal commands
* Rather internal commands.
*/
int xmlNanoFTPGetResponse (void *ctx);
int xmlNanoFTPCheckResponse (void *ctx);
/*
* CD/DIR/GET handlers
* CD/DIR/GET handlers.
*/
int xmlNanoFTPCwd (void *ctx,
char *directory);
......
......@@ -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.