From 9bbffec568d3e3543d425cc2cda291b141f5e5ea Mon Sep 17 00:00:00 2001 From: Nick Wellnhofer Date: Tue, 6 May 2025 17:42:46 +0200 Subject: [PATCH] doc: Move brief to top, params to bottom of doc comments --- HTMLparser.c | 464 +++++------- HTMLtree.c | 128 ++-- SAX2.c | 210 +++--- buf.c | 205 +++-- c14n.c | 148 ++-- catalog.c | 312 ++++---- chvalid.c | 29 +- debugXML.c | 104 ++- dict.c | 77 +- encoding.c | 185 ++--- entities.c | 116 ++- error.c | 145 ++-- globals.c | 42 +- hash.c | 198 +++-- include/libxml/c14n.h | 5 +- include/libxml/chvalid.h | 56 +- include/libxml/encoding.h | 44 +- include/libxml/hash.h | 20 +- include/libxml/list.h | 14 +- include/libxml/parser.h | 165 ++-- include/libxml/parserInternals.h | 63 +- include/libxml/relaxng.h | 14 +- include/libxml/schematron.h | 14 +- include/libxml/tree.h | 13 +- include/libxml/valid.h | 8 +- include/libxml/xlink.h | 18 +- include/libxml/xmlIO.h | 40 +- include/libxml/xmlerror.h | 11 +- include/libxml/xmlmemory.h | 15 +- include/libxml/xmlreader.h | 4 +- include/libxml/xmlregexp.h | 4 +- include/libxml/xmlschemas.h | 21 +- include/libxml/xpath.h | 31 +- include/libxml/xpathInternals.h | 90 ++- list.c | 144 ++-- nanohttp.c | 78 +- parser.c | 1139 ++++++++++++---------------- parserInternals.c | 458 +++++------- pattern.c | 143 ++-- relaxng.c | 711 ++++++++---------- runtest.c | 316 ++++---- schematron.c | 152 ++-- shell.c | 140 ++-- testlimits.c | 175 ++--- testrecurse.c | 41 +- threads.c | 40 +- tree.c | 836 +++++++++------------ uri.c | 176 ++--- valid.c | 712 ++++++++---------- xinclude.c | 162 ++-- xlink.c | 25 +- xmlIO.c | 301 ++++---- xmlcatalog.c | 3 +- xmlmemory.c | 87 +-- xmlmodule.c | 19 +- xmlreader.c | 510 ++++++------- xmlregexp.c | 495 ++++++------ xmlsave.c | 326 ++++---- xmlschemas.c | 1202 +++++++++++++----------------- xmlschemastypes.c | 343 ++++----- xmlstring.c | 164 ++-- xmlunicode.c | 507 +++++-------- xmlwriter.c | 482 +++++------- xpath.c | 1106 ++++++++++++--------------- xpointer.c | 33 +- 65 files changed, 6004 insertions(+), 8035 deletions(-) diff --git a/HTMLparser.c b/HTMLparser.c index 1c5901c9..c252235d 100644 --- a/HTMLparser.c +++ b/HTMLparser.c @@ -113,9 +113,9 @@ htmlParseElementInternal(htmlParserCtxtPtr ctxt); ************************************************************************/ /** - * @param ctxt an HTML parser context - * * Handle an out-of-memory error + * + * @param ctxt an HTML parser context */ static void htmlErrMemory(xmlParserCtxtPtr ctxt) @@ -124,13 +124,13 @@ htmlErrMemory(xmlParserCtxtPtr ctxt) } /** + * Handle a fatal parser error, i.e. violating Well-Formedness constraints + * * @param ctxt an HTML parser context * @param error the error number * @param msg the error message * @param str1 string infor * @param str2 string infor - * - * Handle a fatal parser error, i.e. violating Well-Formedness constraints */ static void LIBXML_ATTR_FORMAT(3,0) htmlParseErr(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -147,11 +147,10 @@ htmlParseErr(xmlParserCtxtPtr ctxt, xmlParserErrors error, ************************************************************************/ /** - * @param ctxt an HTML parser context - * @param value the element name - * * Pushes a new element name on top of the name stack * + * @param ctxt an HTML parser context + * @param value the element name * @returns -1 in case of error, the index in the stack otherwise */ static int @@ -184,10 +183,9 @@ htmlnamePush(htmlParserCtxtPtr ctxt, const xmlChar * value) return (ctxt->nameNr++); } /** - * @param ctxt an HTML parser context - * * Pops the top element name from the name stack * + * @param ctxt an HTML parser context * @returns the name just removed */ static const xmlChar * @@ -210,11 +208,10 @@ htmlnamePop(htmlParserCtxtPtr ctxt) } /** - * @param ctxt an HTML parser context - * @param value the node info - * * Pushes a new element name on top of the node info stack * + * @param ctxt an HTML parser context + * @param value the node info * @returns 0 in case of error, the index in the stack otherwise */ static int @@ -244,10 +241,9 @@ htmlNodeInfoPush(htmlParserCtxtPtr ctxt, htmlParserNodeInfo *value) } /** - * @param ctxt an HTML parser context - * * Pops the top element name from the node info stack * + * @param ctxt an HTML parser context * @returns 0 in case of error, the pointer to NodeInfo otherwise */ static htmlParserNodeInfo * @@ -438,10 +434,9 @@ invalid: } /** - * @param ctxt the HTML parser context - * * skip all blanks character found at that point in the input streams. * + * @param ctxt the HTML parser context * @returns the number of space chars skipped */ @@ -1252,12 +1247,11 @@ htmlCompareTags(const void *key, const void *member) { } /** - * @param tag The tag name in lowercase + * Lookup the HTML tag in the ElementTable * * @deprecated Only supports HTML 4. * - * Lookup the HTML tag in the ElementTable - * + * @param tag The tag name in lowercase * @returns the related htmlElemDescPtr or NULL if not found. */ const htmlElemDesc * @@ -1272,7 +1266,6 @@ htmlTagLookup(const xmlChar *tag) { /** * @param name The name of the element to look up the priority for. - * * @returns value: The "endtag" priority. **/ static int @@ -1301,12 +1294,11 @@ htmlCompareStartClose(const void *vkey, const void *member) { } /** - * @param newtag The new tag name - * @param oldtag The old tag name - * * Checks whether the new tag is one of the registered valid tags for * closing old. * + * @param newtag The new tag name + * @param oldtag The old tag name * @returns 0 if no, 1 if yes. */ static int @@ -1324,10 +1316,10 @@ htmlCheckAutoClose(const xmlChar * newtag, const xmlChar * oldtag) } /** + * The HTML DTD allows an ending tag to implicitly close other tags. + * * @param ctxt an HTML parser context * @param newtag The new tag name - * - * The HTML DTD allows an ending tag to implicitly close other tags. */ static void htmlAutoCloseOnClose(htmlParserCtxtPtr ctxt, const xmlChar * newtag) @@ -1371,9 +1363,9 @@ htmlAutoCloseOnClose(htmlParserCtxtPtr ctxt, const xmlChar * newtag) } /** - * @param ctxt an HTML parser context - * * Close all remaining tags at the end of the stream + * + * @param ctxt an HTML parser context */ static void htmlAutoCloseOnEnd(htmlParserCtxtPtr ctxt) @@ -1394,15 +1386,15 @@ htmlAutoCloseOnEnd(htmlParserCtxtPtr ctxt) } /** - * @param ctxt an HTML parser context - * @param newtag The new tag name or NULL - * * The HTML DTD allows a tag to implicitly close other tags. * The list is kept in htmlStartClose array. This function is * called when a new tag has been detected and generates the * appropriates closes if possible/needed. * If newtag is NULL this mean we are at the end of the resource * and we should check + * + * @param ctxt an HTML parser context + * @param newtag The new tag name or NULL */ static void htmlAutoClose(htmlParserCtxtPtr ctxt, const xmlChar * newtag) @@ -1423,17 +1415,16 @@ htmlAutoClose(htmlParserCtxtPtr ctxt, const xmlChar * newtag) } /** - * @param doc the HTML document - * @param name The tag name - * @param elem the HTML element - * - * @deprecated Internal function, don't use. - * * The HTML DTD allows a tag to implicitly close other tags. * The list is kept in htmlStartClose array. This function checks * if the element or one of it's children would autoclose the * given tag. * + * @deprecated Internal function, don't use. + * + * @param doc the HTML document + * @param name The tag name + * @param elem the HTML element * @returns 1 if autoclose, 0 otherwise */ int @@ -1452,15 +1443,14 @@ htmlAutoCloseTag(htmlDocPtr doc, const xmlChar *name, htmlNodePtr elem) { } /** - * @param doc the HTML document - * @param elem the HTML element - * - * @deprecated Internal function, don't use. - * * The HTML DTD allows a tag to implicitly close other tags. * The list is kept in htmlStartClose array. This function checks * if a tag is autoclosed by one of it's child * + * @deprecated Internal function, don't use. + * + * @param doc the HTML document + * @param elem the HTML element * @returns 1 if autoclosed, 0 otherwise */ int @@ -1477,12 +1467,12 @@ htmlIsAutoClosed(htmlDocPtr doc, htmlNodePtr elem) { } /** - * @param ctxt an HTML parser context - * @param newtag The new tag name - * * The HTML DTD allows a tag to exists only implicitly * called when a new tag has been detected and generates the * appropriates implicit tags if missing + * + * @param ctxt an HTML parser context + * @param newtag The new tag name */ static void htmlCheckImplied(htmlParserCtxtPtr ctxt, const xmlChar *newtag) { @@ -1542,9 +1532,9 @@ htmlCheckImplied(htmlParserCtxtPtr ctxt, const xmlChar *newtag) { } /** - * @param ctxt an HTML parser context - * * Prepare for non-whitespace character data. + * + * @param ctxt an HTML parser context */ static void @@ -1560,12 +1550,11 @@ htmlStartCharData(htmlParserCtxtPtr ctxt) { } /** - * @param name an attribute name + * Check if an attribute is of content type Script * * @deprecated Only supports HTML 4. * - * Check if an attribute is of content type Script - * + * @param name an attribute name * @returns 1 is the attribute is a script 0 otherwise */ int @@ -1885,14 +1874,13 @@ static const htmlEntityDesc html40EntitiesTable[] = { ************************************************************************/ /** - * @param name the entity name + * Lookup the given entity in EntitiesTable * * @deprecated Only supports HTML 4. * - * Lookup the given entity in EntitiesTable - * * TODO: the linear scan is really ugly, an hash table is really needed. * + * @param name the entity name * @returns the associated htmlEntityDescPtr if found, NULL otherwise. */ const htmlEntityDesc * @@ -1917,14 +1905,13 @@ htmlCompareEntityDesc(const void *vkey, const void *vdesc) { } /** - * @param value the entity's unicode value + * Lookup the given entity in EntitiesTable * * @deprecated Only supports HTML 4. * - * Lookup the given entity in EntitiesTable - * * TODO: the linear scan is really ugly, an hash table is really needed. * + * @param value the entity's unicode value * @returns the associated htmlEntityDescPtr if found, NULL otherwise. */ const htmlEntityDesc * @@ -1940,16 +1927,15 @@ htmlEntityValueLookup(unsigned int value) { } /** + * Take a block of UTF-8 chars in and try to convert it to an ASCII + * plus HTML entities block of chars out. + * + * @deprecated Internal function, don't use. + * * @param out a pointer to an array of bytes to store the result * @param outlen the length of `out` * @param in a pointer to an array of UTF-8 chars * @param inlen the length of `in` - * - * @deprecated Internal function, don't use. - * - * Take a block of UTF-8 chars in and try to convert it to an ASCII - * plus HTML entities block of chars out. - * * @returns 0 if success, -2 if the transcoding fails, or -1 otherwise * The value of `inlen` after return is the number of octets consumed * as the return value is positive, else unpredictable. @@ -2041,17 +2027,16 @@ done: } /** + * Take a block of UTF-8 chars in and try to convert it to an ASCII + * plus HTML entities block of chars out. + * + * @deprecated Only supports HTML 4. + * * @param out a pointer to an array of bytes to store the result * @param outlen the length of `out` * @param in a pointer to an array of UTF-8 chars * @param inlen the length of `in` * @param quoteChar the quote character to escape (' or ") or zero. - * - * @deprecated Only supports HTML 4. - * - * Take a block of UTF-8 chars in and try to convert it to an ASCII - * plus HTML entities block of chars out. - * * @returns 0 if success, -2 if the transcoding fails, or -1 otherwise * The value of `inlen` after return is the number of octets consumed * as the return value is positive, else unpredictable. @@ -2161,12 +2146,11 @@ static const char *allowPCData[] = { }; /** + * Is this a sequence of blank chars that one can ignore ? + * * @param ctxt an HTML parser context * @param str a xmlChar * * @param len the size of `str` - * - * Is this a sequence of blank chars that one can ignore ? - * * @returns 1 if ignorable 0 if whitespace, -1 otherwise. */ @@ -2227,12 +2211,11 @@ static int areBlanks(htmlParserCtxtPtr ctxt, const xmlChar *str, int len) { } /** - * @param URI URI for the dtd, or NULL - * @param ExternalID the external ID of the DTD, or NULL - * * Creates a new HTML document without a DTD node if `URI` and `ExternalID` * are NULL * + * @param URI URI for the dtd, or NULL + * @param ExternalID the external ID of the DTD, or NULL * @returns a new document, do not initialize the DTD if not provided */ htmlDocPtr @@ -2279,11 +2262,10 @@ htmlNewDocNoDtD(const xmlChar *URI, const xmlChar *ExternalID) { } /** - * @param URI URI for the dtd, or NULL - * @param ExternalID the external ID of the DTD, or NULL - * * Creates a new HTML document * + * @param URI URI for the dtd, or NULL + * @param ExternalID the external ID of the DTD, or NULL * @returns a new document */ htmlDocPtr @@ -2311,12 +2293,11 @@ htmlNewDoc(const xmlChar *URI, const xmlChar *ExternalID) { ************************************************************************/ /** - * @param ctxt an HTML parser context - * @param attr whether this is an attribute name - * * parse an HTML tag or attribute name, note that we convert it to lowercase * since HTML names are not case-sensitive. * + * @param ctxt an HTML parser context + * @param attr whether this is an attribute name * @returns the Tag Name parsed or NULL */ @@ -2547,14 +2528,13 @@ htmlFindEntityPrefix(const xmlChar *string, size_t slen, int isAttr, } /** + * Parse data until terminator is reached. + * * @param ctxt an HTML parser context * @param mask mask of terminating characters * @param comment true if parsing a comment * @param refs true if references are allowed * @param maxLength maximum output length - * - * Parse data until terminator is reached. - * * @returns the parsed string or NULL in case of errors. */ @@ -2860,11 +2840,10 @@ error: } /** - * @param ctxt an HTML parser context - * @param str location to store the entity name - * * @deprecated Internal function, don't use. * + * @param ctxt an HTML parser context + * @param str location to store the entity name * @returns NULL. */ const htmlEntityDesc * @@ -2874,13 +2853,12 @@ htmlParseEntityRef(htmlParserCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** - * @param ctxt an HTML parser context - * * parse a value for an attribute * Note: the parser won't do substitution of entities here, this * will be handled later in xmlStringGetNodeList(), unless it was * asked for ctxt->replaceEntities != 0 * + * @param ctxt an HTML parser context * @returns the AttValue parsed or NULL. */ @@ -2968,11 +2946,10 @@ htmlCharDataSAXCallback(htmlParserCtxtPtr ctxt, const xmlChar *buf, } /** - * @param ctxt an HTML parser context - * @param partial true if the input buffer is incomplete - * * Parse character data and references. * + * @param ctxt an HTML parser context + * @param partial true if the input buffer is incomplete * @returns 1 if all data was parsed, 0 otherwise. */ @@ -3358,10 +3335,10 @@ restart: } /** + * Parse an HTML comment + * * @param ctxt an HTML parser context * @param bogus true if this is a bogus comment - * - * Parse an HTML comment */ static void htmlParseComment(htmlParserCtxtPtr ctxt, int bogus) { @@ -3398,10 +3375,9 @@ htmlParseComment(htmlParserCtxtPtr ctxt, int bogus) { } /** - * @param ctxt an HTML parser context - * * @deprecated Internal function, don't use. * + * @param ctxt an HTML parser context * @returns 0 */ int @@ -3411,10 +3387,9 @@ htmlParseCharRef(htmlParserCtxtPtr ctxt ATTRIBUTE_UNUSED) { /** - * @param ctxt an HTML parser context - * * Parse a DOCTYPE SYTSTEM or PUBLIC literal. * + * @param ctxt an HTML parser context * @returns the literal or NULL in case of error. */ @@ -3498,9 +3473,9 @@ htmlSkipBogusDoctype(htmlParserCtxtPtr ctxt) { } /** - * @param ctxt an HTML parser context - * * Parse a DOCTYPE declaration. + * + * @param ctxt an HTML parser context */ static void @@ -3571,9 +3546,6 @@ bogus: } /** - * @param ctxt an HTML parser context - * @param value a xmlChar ** used to store the value of the attribute - * * parse an attribute * * [41] Attribute ::= Name Eq AttValue @@ -3587,6 +3559,8 @@ bogus: * Also the case QName == xmlns:??? is handled independently as a namespace * definition. * + * @param ctxt an HTML parser context + * @param value a xmlChar ** used to store the value of the attribute * @returns the attribute name, and the value in *value. */ @@ -3615,13 +3589,13 @@ htmlParseAttribute(htmlParserCtxtPtr ctxt, xmlChar **value) { } /** - * @param ctxt an HTML parser context - * @param attvalue the attribute value - * * Checks an http-equiv attribute from a Meta tag to detect * the encoding * If a new encoding is detected the parser is switched to decode * it and pass UTF8 + * + * @param ctxt an HTML parser context + * @param attvalue the attribute value */ static void htmlCheckEncoding(htmlParserCtxtPtr ctxt, const xmlChar *attvalue) { @@ -3650,10 +3624,10 @@ htmlCheckEncoding(htmlParserCtxtPtr ctxt, const xmlChar *attvalue) { } /** + * Checks an attributes from a Meta tag + * * @param ctxt an HTML parser context * @param atts the attributes values - * - * Checks an attributes from a Meta tag */ static void htmlCheckMeta(htmlParserCtxtPtr ctxt, const xmlChar **atts) { @@ -3692,14 +3666,13 @@ htmlCheckMeta(htmlParserCtxtPtr ctxt, const xmlChar **atts) { } /** + * Inserts a new attribute into the hash table. + * * @param ctxt parser context * @param size size of the hash table * @param name attribute name * @param hashValue hash value of name * @param aindex attribute index (this is a multiple of 5) - * - * Inserts a new attribute into the hash table. - * * @returns INT_MAX if no existing attribute was found, the attribute * index if an attribute was found, -1 if a memory allocation failed. */ @@ -3733,8 +3706,6 @@ htmlAttrHashInsert(xmlParserCtxtPtr ctxt, unsigned size, const xmlChar *name, } /** - * @param ctxt an HTML parser context - * * parse a start of tag either for rule element or * EmptyElement. In both case we don't parse the tag closing chars. * @@ -3748,6 +3719,7 @@ htmlAttrHashInsert(xmlParserCtxtPtr ctxt, unsigned size, const xmlChar *name, * * [NS 10] EmptyElement ::= '<' QName (S Attribute)* S? '/>' * + * @param ctxt an HTML parser context * @returns 0 in case of success, -1 in case of error and 1 if discarded */ @@ -4004,8 +3976,6 @@ done: } /** - * @param ctxt an HTML parser context - * * parse an end of tag * * [42] ETag ::= '' @@ -4014,6 +3984,7 @@ done: * * [NS 9] ETag ::= '' * + * @param ctxt an HTML parser context * @returns 1 if the current level should be closed. */ @@ -4146,10 +4117,10 @@ htmlParseEndTag(htmlParserCtxtPtr ctxt) } /** - * @param ctxt an HTML parser context - * * Parse a content: comment, sub-element, reference or text. * New version for non recursive htmlParseElementInternal() + * + * @param ctxt an HTML parser context */ static void @@ -4206,9 +4177,9 @@ htmlParseContent(htmlParserCtxtPtr ctxt) { } /** - * @param ctxt an HTML parser context - * * Parse an HTML element, new version, non recursive + * + * @param ctxt an HTML parser context */ static int htmlParseElementInternal(htmlParserCtxtPtr ctxt) { @@ -4277,11 +4248,11 @@ htmlParseElementInternal(htmlParserCtxtPtr ctxt) { } /** - * @param ctxt an HTML parser context + * This is kept for compatibility with previous code versions * * @deprecated Internal function, don't use. * - * This is kept for compatibility with previous code versions + * @param ctxt an HTML parser context */ void htmlParseElement(htmlParserCtxtPtr ctxt) { @@ -4313,7 +4284,6 @@ htmlParseElement(htmlParserCtxtPtr ctxt) { /** * @param ctxt parser context * @param input parser input - * * @returns a node list. */ xmlNodePtr @@ -4367,12 +4337,11 @@ htmlCtxtParseContentInternal(htmlParserCtxtPtr ctxt, xmlParserInputPtr input) { } /** - * @param ctxt an HTML parser context - * * Parse an HTML document and invoke the SAX handlers. This is useful * if you're only interested in custom SAX callbacks. If you want a * document tree, use htmlCtxtParseDocument(). * + * @param ctxt an HTML parser context * @returns 0, -1 in case of error. */ int @@ -4498,12 +4467,11 @@ htmlParseDocument(htmlParserCtxtPtr ctxt) { ************************************************************************/ /** + * Initialize a parser context + * * @param ctxt an HTML parser context * @param sax SAX handler * @param userData user data - * - * Initialize a parser context - * * @returns 0 in case of success and -1 in case of error */ static int @@ -4588,10 +4556,10 @@ htmlInitParserCtxt(htmlParserCtxtPtr ctxt, const htmlSAXHandler *sax, } /** - * @param ctxt an HTML parser context - * * Free all the memory used by a parser context. However the parsed * document in `ctxt->myDoc` is not freed. + * + * @param ctxt an HTML parser context */ void htmlFreeParserCtxt(htmlParserCtxtPtr ctxt) @@ -4620,9 +4588,6 @@ htmlNewParserCtxt(void) } /** - * @param sax SAX handler - * @param userData user data - * * Allocate and initialize a new HTML SAX parser context. If `userData` * is NULL, the parser context will be passed as user data. * @@ -4633,6 +4598,8 @@ htmlNewParserCtxt(void) * * Also see htmlNewParserCtxt(). * + * @param sax SAX handler + * @param userData user data * @returns the htmlParserCtxtPtr or NULL in case of allocation error */ htmlParserCtxtPtr @@ -4683,14 +4650,13 @@ htmlCreateMemoryParserCtxtInternal(const char *url, } /** - * @param buffer a pointer to a char array - * @param size the size of the array - * - * @deprecated Use htmlNewParserCtxt() and htmlCtxtReadMemory(). - * * Create a parser context for an HTML in-memory document. The input * buffer must not contain any terminating null bytes. * + * @deprecated Use htmlNewParserCtxt() and htmlCtxtReadMemory(). + * + * @param buffer a pointer to a char array + * @param size the size of the array * @returns the new parser context or NULL */ htmlParserCtxtPtr @@ -4702,12 +4668,11 @@ htmlCreateMemoryParserCtxt(const char *buffer, int size) { } /** + * Create a parser context for a null-terminated string. + * * @param str a pointer to an array of xmlChar * @param url URL of the document (optional) * @param encoding encoding (optional) - * - * Create a parser context for a null-terminated string. - * * @returns the new parser context or NULL if a memory allocation failed. */ static htmlParserCtxtPtr @@ -4758,10 +4723,10 @@ typedef enum { } xmlLookupStates; /** - * @param ctxt an HTML parser context - * * Check whether there's enough data in the input buffer to finish parsing * a tag. This has to take quotes into account. + * + * @param ctxt an HTML parser context */ static int htmlParseLookupGt(xmlParserCtxtPtr ctxt) { @@ -4855,13 +4820,13 @@ htmlParseLookupGt(xmlParserCtxtPtr ctxt) { } /** + * Check whether the input buffer contains a string. + * * @param ctxt an XML parser context * @param startDelta delta to apply at the start * @param str string * @param strLen length of string * @param extraLen extra length - * - * Check whether the input buffer contains a string. */ static int htmlParseLookupString(xmlParserCtxtPtr ctxt, size_t startDelta, @@ -4909,12 +4874,11 @@ htmlParseLookupString(xmlParserCtxtPtr ctxt, size_t startDelta, } /** - * @param ctxt an HTML parser context - * * Try to find a comment end tag in the input stream * The search includes "-->" as well as WHATWG-recommended * incorrectly-closed tags. * + * @param ctxt an HTML parser context * @returns the index to the current parsing point if the full * sequence is available, -1 otherwise. */ @@ -4951,11 +4915,10 @@ htmlParseLookupCommentEnd(htmlParserCtxtPtr ctxt) /** - * @param ctxt an HTML parser context - * @param terminate last chunk indicator - * * Try to progress on parsing * + * @param ctxt an HTML parser context + * @param terminate last chunk indicator * @returns zero if no parsing was possible */ static void @@ -5154,11 +5117,6 @@ htmlParseTryOrFinish(htmlParserCtxtPtr ctxt, int terminate) { } /** - * @param ctxt an HTML parser context - * @param chunk chunk of memory - * @param size size of chunk in bytes - * @param terminate last chunk indicator - * * Parse a chunk of memory in push parser mode. * * Assumes that the parser context was initialized with @@ -5171,6 +5129,10 @@ htmlParseTryOrFinish(htmlParserCtxtPtr ctxt, int terminate) { * * If the document isn't well-formed, `ctxt->myDoc` is set to NULL. * + * @param ctxt an HTML parser context + * @param chunk chunk of memory + * @param size size of chunk in bytes + * @param terminate last chunk indicator * @returns an xmlParserErrors code (0 on success). */ int @@ -5238,15 +5200,14 @@ htmlParseChunk(htmlParserCtxtPtr ctxt, const char *chunk, int size, ************************************************************************/ /** + * Create a parser context for using the HTML parser in push mode. + * * @param sax a SAX handler (optional) * @param user_data The user data returned on SAX callbacks (optional) * @param chunk a pointer to an array of chars (optional) * @param size number of chars in the array * @param filename only used for error reporting (optional) * @param enc encoding (deprecated, pass XML_CHAR_ENCODING_NONE) - * - * Create a parser context for using the HTML parser in push mode. - * * @returns the new parser context or NULL if a memory allocation * failed. */ @@ -5283,17 +5244,16 @@ htmlCreatePushParserCtxt(htmlSAXHandlerPtr sax, void *user_data, #endif /* LIBXML_PUSH_ENABLED */ /** - * @param cur a pointer to an array of xmlChar - * @param encoding a free form C string describing the HTML document encoding, or NULL - * @param sax the SAX handler block - * @param userData if using SAX, this pointer will be provided on callbacks. - * - * @deprecated Use htmlNewSAXParserCtxt() and htmlCtxtReadDoc(). - * * Parse an HTML in-memory document. If sax is not NULL, use the SAX callbacks * to handle parse events. If sax is NULL, fallback to the default DOM * behavior and return a tree. * + * @deprecated Use htmlNewSAXParserCtxt() and htmlCtxtReadDoc(). + * + * @param cur a pointer to an array of xmlChar + * @param encoding a free form C string describing the HTML document encoding, or NULL + * @param sax the SAX handler block + * @param userData if using SAX, this pointer will be provided on callbacks. * @returns the resulting document tree unless SAX is NULL or the document is * not well formed. */ @@ -5324,15 +5284,14 @@ htmlSAXParseDoc(const xmlChar *cur, const char *encoding, } /** - * @param cur a pointer to an array of xmlChar - * @param encoding the encoding (optional) + * Parse an HTML in-memory document and build a tree. * * @deprecated Use htmlReadDoc(). * - * Parse an HTML in-memory document and build a tree. - * * This function uses deprecated global parser options. * + * @param cur a pointer to an array of xmlChar + * @param encoding the encoding (optional) * @returns the resulting document tree */ @@ -5343,18 +5302,17 @@ htmlParseDoc(const xmlChar *cur, const char *encoding) { /** - * @param filename the filename - * @param encoding optional encoding + * Create a parser context to read from a file. * * @deprecated Use htmlNewParserCtxt() and htmlCtxtReadFile(). * - * Create a parser context to read from a file. - * * A non-NULL encoding overrides encoding declarations in the document. * * Automatic support for ZLIB/Compress compressed document is provided * by default if found at compile-time. * + * @param filename the filename + * @param encoding optional encoding * @returns the new parser context or NULL if a memory allocation failed. */ htmlParserCtxtPtr @@ -5386,18 +5344,17 @@ htmlCreateFileParserCtxt(const char *filename, const char *encoding) } /** - * @param filename the filename - * @param encoding encoding (optional) - * @param sax the SAX handler block - * @param userData if using SAX, this pointer will be provided on callbacks. - * - * @deprecated Use htmlNewSAXParserCtxt() and htmlCtxtReadFile(). - * * parse an HTML file and build a tree. Automatic support for ZLIB/Compress * compressed document is provided by default if found at compile-time. * It use the given SAX function block to handle the parsing callback. * If sax is NULL, fallback to the default DOM tree building routines. * + * @deprecated Use htmlNewSAXParserCtxt() and htmlCtxtReadFile(). + * + * @param filename the filename + * @param encoding encoding (optional) + * @param sax the SAX handler block + * @param userData if using SAX, this pointer will be provided on callbacks. * @returns the resulting document tree unless SAX is NULL or the document is * not well formed. */ @@ -5430,11 +5387,10 @@ htmlSAXParseFile(const char *filename, const char *encoding, htmlSAXHandlerPtr s } /** - * @param filename the filename - * @param encoding encoding (optional) - * * Parse an HTML file and build a tree. * + * @param filename the filename + * @param encoding encoding (optional) * @returns the resulting document tree */ @@ -5444,12 +5400,11 @@ htmlParseFile(const char *filename, const char *encoding) { } /** - * @param val int 0 or 1 + * Set and return the previous value for handling HTML omitted tags. * * @deprecated Use HTML_PARSE_NOIMPLIED * - * Set and return the previous value for handling HTML omitted tags. - * + * @param val int 0 or 1 * @returns the last value for 0 for no handling, 1 for auto insertion. */ @@ -5462,11 +5417,10 @@ htmlHandleOmittedElem(int val) { } /** - * @param parent HTML parent element - * @param elt HTML element - * * @deprecated Don't use. * + * @param parent HTML parent element + * @param elt HTML element * @returns 1 */ int @@ -5476,11 +5430,10 @@ htmlElementAllowedHere(const htmlElemDesc* parent ATTRIBUTE_UNUSED, } /** - * @param parent HTML parent element - * @param elt HTML element - * * @deprecated Don't use. * + * @param parent HTML parent element + * @param elt HTML element * @returns HTML_VALID */ htmlStatus @@ -5490,12 +5443,11 @@ htmlElementStatusHere(const htmlElemDesc* parent ATTRIBUTE_UNUSED, } /** + * @deprecated Don't use. + * * @param elt HTML element * @param attr HTML attribute * @param legacy whether to allow deprecated attributes - * - * @deprecated Don't use. - * * @returns HTML_VALID */ htmlStatus @@ -5506,12 +5458,11 @@ htmlAttrAllowed(const htmlElemDesc* elt ATTRIBUTE_UNUSED, } /** + * @deprecated Don't use. + * * @param node an htmlNodePtr in a tree * @param legacy whether to allow deprecated elements (YES is faster here * for Element nodes) - * - * @deprecated Don't use. - * * @returns HTML_VALID */ htmlStatus @@ -5526,10 +5477,10 @@ htmlNodeStatus(htmlNodePtr node ATTRIBUTE_UNUSED, * * ************************************************************************/ /** - * @param str a string - * * Free a string if it is not owned by the "dict" dictionary in the * current scope + * + * @param str a string */ #define DICT_FREE(str) \ if ((str) && ((!dict) || \ @@ -5537,9 +5488,9 @@ htmlNodeStatus(htmlNodePtr node ATTRIBUTE_UNUSED, xmlFree((char *)(str)); /** - * @param ctxt an HTML parser context - * * Reset a parser context + * + * @param ctxt an HTML parser context */ void htmlCtxtReset(htmlParserCtxtPtr ctxt) @@ -5686,9 +5637,6 @@ htmlCtxtSetOptionsInternal(xmlParserCtxtPtr ctxt, int options, int keepMask) } /** - * @param ctxt an HTML parser context - * @param options a bitmask of htmlParserOption values - * * Applies the options to the parser context. Unset options are * cleared. * @@ -5696,6 +5644,8 @@ htmlCtxtSetOptionsInternal(xmlParserCtxtPtr ctxt, int options, int keepMask) * * With older versions, you can use htmlCtxtUseOptions(). * + * @param ctxt an HTML parser context + * @param options a bitmask of htmlParserOption values * @returns 0 in case of success, the set of unknown or unimplemented options * in case of error. */ @@ -5706,14 +5656,11 @@ htmlCtxtSetOptions(xmlParserCtxtPtr ctxt, int options) } /** - * @param ctxt an HTML parser context - * @param options a combination of htmlParserOption values - * - * @deprecated Use htmlCtxtSetOptions(). - * * Applies the options to the parser context. The following options * are never cleared and can only be enabled: * + * @deprecated Use htmlCtxtSetOptions(). + * * - HTML_PARSE_NODEFDTD * - HTML_PARSE_NOERROR * - HTML_PARSE_NOWARNING @@ -5723,6 +5670,8 @@ htmlCtxtSetOptions(xmlParserCtxtPtr ctxt, int options) * - HTML_PARSE_IGNORE_ENC * - HTML_PARSE_BIG_LINES * + * @param ctxt an HTML parser context + * @param options a combination of htmlParserOption values * @returns 0 in case of success, the set of unknown or unimplemented options * in case of error. */ @@ -5747,13 +5696,12 @@ htmlCtxtUseOptions(htmlParserCtxtPtr ctxt, int options) } /** - * @param ctxt an HTML parser context - * @param input parser input - * * Parse an HTML document and return the resulting document tree. * * @since 2.13.0 * + * @param ctxt an HTML parser context + * @param input parser input * @returns the resulting document tree or NULL */ htmlDocPtr @@ -5789,16 +5737,15 @@ htmlCtxtParseDocument(htmlParserCtxtPtr ctxt, xmlParserInputPtr input) } /** - * @param str a pointer to a zero terminated string - * @param url only used for error reporting (optoinal) - * @param encoding the document encoding (optional) - * @param options a combination of htmlParserOption values - * * Convenience function to parse an HTML document from a zero-terminated * string. * * See htmlCtxtReadDoc() for details. * + * @param str a pointer to a zero terminated string + * @param url only used for error reporting (optoinal) + * @param encoding the document encoding (optional) + * @param options a combination of htmlParserOption values * @returns the resulting document tree. */ htmlDocPtr @@ -5826,15 +5773,14 @@ htmlReadDoc(const xmlChar *str, const char *url, const char *encoding, } /** - * @param filename a file or URL - * @param encoding the document encoding (optional) - * @param options a combination of htmlParserOption values - * * Convenience function to parse an HTML file from the filesystem, * the network or a global user-defined resource loader. * * See htmlCtxtReadFile() for details. * + * @param filename a file or URL + * @param encoding the document encoding (optional) + * @param options a combination of htmlParserOption values * @returns the resulting document tree. */ htmlDocPtr @@ -5860,17 +5806,16 @@ htmlReadFile(const char *filename, const char *encoding, int options) } /** - * @param buffer a pointer to a char array - * @param size the size of the array - * @param url only used for error reporting (optional) - * @param encoding the document encoding, or NULL - * @param options a combination of htmlParserOption values - * * Convenience function to parse an HTML document from memory. * The input buffer must not contain any terminating null bytes. * * See htmlCtxtReadMemory() for details. * + * @param buffer a pointer to a char array + * @param size the size of the array + * @param url only used for error reporting (optional) + * @param encoding the document encoding, or NULL + * @param options a combination of htmlParserOption values * @returns the resulting document tree */ htmlDocPtr @@ -5901,11 +5846,6 @@ htmlReadMemory(const char *buffer, int size, const char *url, } /** - * @param fd an open file descriptor - * @param url only used for error reporting (optional) - * @param encoding the document encoding, or NULL - * @param options a combination of htmlParserOption values - * * Convenience function to parse an HTML document from a * file descriptor. * @@ -5914,6 +5854,10 @@ htmlReadMemory(const char *buffer, int size, const char *url, * * See htmlCtxtReadFd() for details. * + * @param fd an open file descriptor + * @param url only used for error reporting (optional) + * @param encoding the document encoding, or NULL + * @param options a combination of htmlParserOption values * @returns the resulting document tree */ htmlDocPtr @@ -5939,18 +5883,17 @@ htmlReadFd(int fd, const char *url, const char *encoding, int options) } /** + * Convenience function to parse an HTML document from I/O functions + * and context. + * + * See htmlCtxtReadIO() for details. + * * @param ioread an I/O read function * @param ioclose an I/O close function (optional) * @param ioctx an I/O handler * @param url only used for error reporting (optional) * @param encoding the document encoding (optional) * @param options a combination of htmlParserOption values - * - * Convenience function to parse an HTML document from I/O functions - * and context. - * - * See htmlCtxtReadIO() for details. - * * @returns the resulting document tree */ htmlDocPtr @@ -5978,16 +5921,15 @@ htmlReadIO(xmlInputReadCallback ioread, xmlInputCloseCallback ioclose, } /** + * Parse an HTML in-memory document and build a tree. + * + * See htmlCtxtUseOptions() for details. + * * @param ctxt an HTML parser context * @param str a pointer to a zero terminated string * @param URL only used for error reporting (optional) * @param encoding the document encoding (optional) * @param options a combination of htmlParserOption values - * - * Parse an HTML in-memory document and build a tree. - * - * See htmlCtxtUseOptions() for details. - * * @returns the resulting document tree */ htmlDocPtr @@ -6011,16 +5953,15 @@ htmlCtxtReadDoc(htmlParserCtxtPtr ctxt, const xmlChar *str, } /** - * @param ctxt an HTML parser context - * @param filename a file or URL - * @param encoding the document encoding (optional) - * @param options a combination of htmlParserOption values - * * Parse an HTML file from the filesystem, the network or a * user-defined resource loader. * * See htmlCtxtUseOptions() for details. * + * @param ctxt an HTML parser context + * @param filename a file or URL + * @param encoding the document encoding (optional) + * @param options a combination of htmlParserOption values * @returns the resulting document tree */ htmlDocPtr @@ -6043,18 +5984,17 @@ htmlCtxtReadFile(htmlParserCtxtPtr ctxt, const char *filename, } /** + * Parse an HTML in-memory document and build a tree. The input buffer must + * not contain any terminating null bytes. + * + * See htmlCtxtUseOptions() for details. + * * @param ctxt an HTML parser context * @param buffer a pointer to a char array * @param size the size of the array * @param URL only used for error reporting (optional) * @param encoding the document encoding (optinal) * @param options a combination of htmlParserOption values - * - * Parse an HTML in-memory document and build a tree. The input buffer must - * not contain any terminating null bytes. - * - * See htmlCtxtUseOptions() for details. - * * @returns the resulting document tree */ htmlDocPtr @@ -6078,12 +6018,6 @@ htmlCtxtReadMemory(htmlParserCtxtPtr ctxt, const char *buffer, int size, } /** - * @param ctxt an HTML parser context - * @param fd an open file descriptor - * @param URL only used for error reporting (optional) - * @param encoding the document encoding (optinal) - * @param options a combination of htmlParserOption values - * * Parse an HTML from a file descriptor and build a tree. * * See htmlCtxtUseOptions() for details. @@ -6091,6 +6025,11 @@ htmlCtxtReadMemory(htmlParserCtxtPtr ctxt, const char *buffer, int size, * NOTE that the file descriptor will not be closed when the * context is freed or reset. * + * @param ctxt an HTML parser context + * @param fd an open file descriptor + * @param URL only used for error reporting (optional) + * @param encoding the document encoding (optinal) + * @param options a combination of htmlParserOption values * @returns the resulting document tree */ htmlDocPtr @@ -6113,6 +6052,10 @@ htmlCtxtReadFd(htmlParserCtxtPtr ctxt, int fd, } /** + * Parse an HTML document from I/O functions and source and build a tree. + * + * See htmlCtxtUseOptions() for details. + * * @param ctxt an HTML parser context * @param ioread an I/O read function * @param ioclose an I/O close function @@ -6120,11 +6063,6 @@ htmlCtxtReadFd(htmlParserCtxtPtr ctxt, int fd, * @param URL the base URL to use for the document * @param encoding the document encoding, or NULL * @param options a combination of htmlParserOption values - * - * Parse an HTML document from I/O functions and source and build a tree. - * - * See htmlCtxtUseOptions() for details. - * * @returns the resulting document tree */ htmlDocPtr diff --git a/HTMLtree.c b/HTMLtree.c index b602df72..14e08927 100644 --- a/HTMLtree.c +++ b/HTMLtree.c @@ -35,8 +35,6 @@ ************************************************************************/ /** - * @param doc the document - * * Look up and encoding declaration in the meta tags. * * Does not support `` yet. Only supports deprecated @@ -45,6 +43,7 @@ * The returned string points into attribute content. It should be * copied before modifying or freeing nodes. * + * @param doc the document * @returns the encoding ot NULL if not found. */ const xmlChar * @@ -151,9 +150,6 @@ found_content: } /** - * @param doc the document - * @param encoding the encoding string - * * Creates or updates a meta tag with an encoding declaration. * * Does not support `` yet. Only supports deprecated @@ -161,6 +157,8 @@ found_content: * * NOTE: This will not change the document content encoding. * + * @param doc the document + * @param encoding the encoding string * @returns 0 in case of success and -1 in case of error */ int @@ -312,13 +310,12 @@ static const char* const htmlBooleanAttrs[] = { /** - * @param name the name of the attribute to check - * - * @deprecated Internal function, don't use. - * * Determine if a given attribute is a boolean attribute. This * doesn't handle HTML5. * + * @deprecated Internal function, don't use. + * + * @param name the name of the attribute to check * @returns false if the attribute is not boolean, true otherwise. */ int @@ -353,13 +350,12 @@ htmlFindOutputEncoder(const char *encoding, xmlCharEncodingHandler **out) { } /** + * Serialize an HTML document to an xmlBuf. + * * @param buf the xmlBufPtr output * @param doc the document * @param cur the current node * @param format should formatting newlines been added - * - * Serialize an HTML document to an xmlBuf. - * * @returns the number of bytes written or -1 in case of error */ static size_t @@ -397,12 +393,11 @@ htmlBufNodeDumpFormat(xmlBufPtr buf, xmlDocPtr doc, xmlNodePtr cur, } /** + * Serialize an HTML node to an xmlBuffer. Always uses UTF-8. + * * @param buf the HTML buffer output * @param doc the document * @param cur the current node - * - * Serialize an HTML node to an xmlBuffer. Always uses UTF-8. - * * @returns the number of bytes written or -1 in case of error */ int @@ -429,18 +424,17 @@ htmlNodeDump(xmlBufferPtr buf, xmlDocPtr doc, xmlNodePtr cur) { } /** - * @param out the FILE pointer - * @param doc the document - * @param cur the current node - * @param encoding the document encoding (optional) - * @param format should formatting newlines been added - * * Serialize an HTML node to an xmlBuffer. * * If encoding is NULL, ASCII with HTML 4.0 named character entities * will be used. This is inefficient compared to UTF-8 and might be * changed in a future version. * + * @param out the FILE pointer + * @param doc the document + * @param cur the current node + * @param encoding the document encoding (optional) + * @param format should formatting newlines been added * @returns the number of bytes written or -1 in case of failure. */ int @@ -468,13 +462,13 @@ htmlNodeDumpFileFormat(FILE *out, xmlDocPtr doc, } /** - * @param out the FILE pointer - * @param doc the document - * @param cur the current node - * * Same as htmlNodeDumpFileFormat() with `format` set to 1 which is * typically undesired. Use of this function is DISCOURAGED in favor * of htmlNodeDumpFileFormat(). + * + * @param out the FILE pointer + * @param doc the document + * @param cur the current node */ void htmlNodeDumpFile(FILE *out, xmlDocPtr doc, xmlNodePtr cur) { @@ -482,11 +476,6 @@ htmlNodeDumpFile(FILE *out, xmlDocPtr doc, xmlNodePtr cur) { } /** - * @param cur the document - * @param mem OUT: the memory pointer - * @param size OUT: the memory length - * @param format should formatting newlines been added - * * Serialize an HTML node to a memory, also returning the size of * the result. It's up to the caller to free the memory. * @@ -498,6 +487,10 @@ htmlNodeDumpFile(FILE *out, xmlDocPtr doc, xmlNodePtr cur) { * * Use of this function is therefore DISCOURAGED in favor of * htmlDocContentDumpFormatOutput(). + * @param cur the document + * @param mem OUT: the memory pointer + * @param size OUT: the memory length + * @param format should formatting newlines been added */ void htmlDocDumpMemoryFormat(xmlDocPtr cur, xmlChar**mem, int *size, int format) { @@ -539,14 +532,14 @@ htmlDocDumpMemoryFormat(xmlDocPtr cur, xmlChar**mem, int *size, int format) { } /** - * @param cur the document - * @param mem OUT: the memory pointer - * @param size OUT: the memory length - * * Same as htmlDocDumpMemoryFormat() with `format` set to 1 which * is typically undesired. Also see the warnings there. Use of * this function is DISCOURAGED in favor of * htmlDocContentDumpFormatOutput(). + * + * @param cur the document + * @param mem OUT: the memory pointer + * @param size OUT: the memory length */ void htmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int *size) { @@ -561,13 +554,12 @@ htmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int *size) { ************************************************************************/ /** - * @param buf the HTML buffer output - * @param doc the document - * @param encoding the encoding string (unused) - * * Serialize the HTML document's DTD, if any. * * Ignores `encoding` and uses the encoding of the output buffer. + * @param buf the HTML buffer output + * @param doc the document + * @param encoding the encoding string (unused) */ static void htmlDtdDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr doc, @@ -594,11 +586,11 @@ htmlDtdDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr doc, } /** + * Serialize an HTML attribute. + * * @param buf the HTML buffer output * @param doc the document * @param cur the attribute pointer - * - * Serialize an HTML attribute. */ static void htmlAttrDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr doc, xmlAttrPtr cur) { @@ -663,15 +655,14 @@ htmlAttrDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr doc, xmlAttrPtr cur) { } /** + * Serialize an HTML node to an output buffer. + * + * Ignores `encoding` and uses the encoding of the output buffer. * @param buf the HTML buffer output * @param doc the document * @param cur the current node * @param encoding the encoding string (unused) * @param format should formatting newlines been added - * - * Serialize an HTML node to an output buffer. - * - * Ignores `encoding` and uses the encoding of the output buffer. */ void htmlNodeDumpFormatOutput(xmlOutputBufferPtr buf, xmlDocPtr doc, @@ -899,16 +890,15 @@ htmlNodeDumpFormatOutput(xmlOutputBufferPtr buf, xmlDocPtr doc, } /** - * @param buf the HTML buffer output - * @param doc the document - * @param cur the current node - * @param encoding the encoding string (unused) - * * Same as htmlNodeDumpFormatOutput() with `format` set to 1 which is * typically undesired. Use of this function is DISCOURAGED in favor * of htmlNodeDumpFormatOutput(). * * Ignores `encoding` and uses the encoding of the output buffer. + * @param buf the HTML buffer output + * @param doc the document + * @param cur the current node + * @param encoding the encoding string (unused) */ void htmlNodeDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr doc, @@ -917,14 +907,13 @@ htmlNodeDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr doc, } /** + * Serialize an HTML document to an output buffer. + * + * Ignores `encoding` and uses the encoding of the output buffer. * @param buf the HTML buffer output * @param cur the document * @param encoding the encoding string (unused) * @param format should formatting newlines been added - * - * Serialize an HTML document to an output buffer. - * - * Ignores `encoding` and uses the encoding of the output buffer. */ void htmlDocContentDumpFormatOutput(xmlOutputBufferPtr buf, xmlDocPtr cur, @@ -941,15 +930,14 @@ htmlDocContentDumpFormatOutput(xmlOutputBufferPtr buf, xmlDocPtr cur, } /** - * @param buf the HTML buffer output - * @param cur the document - * @param encoding the encoding string (unused) - * * Same as htmlNodeDumpFormatOutput() with `format` set to 1 which is * typically undesired. Use of this function is DISCOURAGED in favor * of htmlDocContentDumpFormatOutput(). * * Ignores `encoding` and uses the encoding of the output buffer. + * @param buf the HTML buffer output + * @param cur the document + * @param encoding the encoding string (unused) */ void htmlDocContentDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr cur, @@ -964,9 +952,6 @@ htmlDocContentDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr cur, ************************************************************************/ /** - * @param f the FILE* - * @param cur the document - * * Serialize an HTML document to an open `FILE`. * * WARNING: Uses the encoding from a deprecated meta tag, see @@ -981,6 +966,8 @@ htmlDocContentDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr cur, * Use of this function is DISCOURAGED in favor of * htmlNodeDumpFileFormat(). * + * @param f the FILE* + * @param cur the document * @returns the number of bytes written or -1 in case of failure. */ int @@ -1009,9 +996,6 @@ htmlDocDump(FILE *f, xmlDocPtr cur) { } /** - * @param filename the filename (or URL) - * @param cur the document - * * Serialize an HTML document to a file. If `filename` is `"-"`, * stdout is used. This is potentially insecure and might be * changed in a future version. @@ -1028,6 +1012,8 @@ htmlDocDump(FILE *f, xmlDocPtr cur) { * Use of this function is DISCOURAGED in favor of * htmlSaveFileFormat(). * + * @param filename the filename (or URL) + * @param cur the document * @returns the number of bytes written or -1 in case of failure. */ int @@ -1056,11 +1042,6 @@ htmlSaveFile(const char *filename, xmlDocPtr cur) { } /** - * @param filename the filename - * @param cur the document - * @param format should formatting newlines been added - * @param encoding the document encoding (optional) - * * Serialize an HTML document to a file using a given encoding. * If `filename` is `"-"`, stdout is used. This is potentially * insecure and might be changed in a future version. @@ -1069,6 +1050,10 @@ htmlSaveFile(const char *filename, xmlDocPtr cur) { * will be used. This is inefficient compared to UTF-8 and might be * changed in a future version. * + * @param filename the filename + * @param cur the document + * @param format should formatting newlines been added + * @param encoding the document encoding (optional) * @returns the number of bytes written or -1 in case of failure. */ int @@ -1104,14 +1089,13 @@ htmlSaveFileFormat(const char *filename, xmlDocPtr cur, } /** - * @param filename the filename - * @param cur the document - * @param encoding the document encoding - * * Same as htmlSaveFileFormat() with `format` set to 1 which is * typically undesired. Also see the warnings there. Use of this * function is DISCOURAGED in favor of htmlSaveFileFormat(). * + * @param filename the filename + * @param cur the document + * @param encoding the document encoding * @returns the number of bytes written or -1 in case of failure. */ int diff --git a/SAX2.c b/SAX2.c index e09ae15c..6da5123c 100644 --- a/SAX2.c +++ b/SAX2.c @@ -40,13 +40,13 @@ xmlSAX2ErrMemory(xmlParserCtxtPtr ctxt) { } /** + * Handle a validation error + * * @param ctxt an XML validation parser context * @param error the error number * @param msg the error message * @param str1 extra data * @param str2 extra data - * - * Handle a validation error */ static void LIBXML_ATTR_FORMAT(3,0) xmlErrValid(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -59,13 +59,13 @@ xmlErrValid(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a fatal parser error, i.e. violating Well-Formedness constraints + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param str1 an error string * @param str2 an error string - * - * Handle a fatal parser error, i.e. violating Well-Formedness constraints */ static void LIBXML_ATTR_FORMAT(3,0) xmlFatalErrMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -76,12 +76,12 @@ xmlFatalErrMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a parser warning + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param str1 an error string - * - * Handle a parser warning */ static void LIBXML_ATTR_FORMAT(3,0) xmlWarnMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -92,13 +92,13 @@ xmlWarnMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a namespace warning + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param str1 an error string * @param str2 an error string - * - * Handle a namespace warning */ static void LIBXML_ATTR_FORMAT(3,0) xmlNsWarnMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -109,10 +109,9 @@ xmlNsWarnMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** - * @param ctx the user data (XML parser context) - * * Provides the public ID e.g. "-//SGMLSOURCE//DTD DEMO//EN" * + * @param ctx the user data (XML parser context) * @returns a xmlChar * */ const xmlChar * @@ -123,11 +122,10 @@ xmlSAX2GetPublicId(void *ctx ATTRIBUTE_UNUSED) } /** - * @param ctx the user data (XML parser context) - * * Provides the system ID, basically URL or filename e.g. * http://www.sgmlsource.com/dtds/memo.dtd * + * @param ctx the user data (XML parser context) * @returns a xmlChar * */ const xmlChar * @@ -139,10 +137,9 @@ xmlSAX2GetSystemId(void *ctx) } /** - * @param ctx the user data (XML parser context) - * * Provide the line number of the current parsing point. * + * @param ctx the user data (XML parser context) * @returns an int */ int @@ -154,10 +151,9 @@ xmlSAX2GetLineNumber(void *ctx) } /** - * @param ctx the user data (XML parser context) - * * Provide the column number of the current parsing point. * + * @param ctx the user data (XML parser context) * @returns an int */ int @@ -169,10 +165,9 @@ xmlSAX2GetColumnNumber(void *ctx) } /** - * @param ctx the user data (XML parser context) - * * Is this document tagged standalone ? * + * @param ctx the user data (XML parser context) * @returns 1 if true */ int @@ -184,10 +179,9 @@ xmlSAX2IsStandalone(void *ctx) } /** - * @param ctx the user data (XML parser context) - * * Does this document has an internal subset * + * @param ctx the user data (XML parser context) * @returns 1 if true */ int @@ -199,10 +193,9 @@ xmlSAX2HasInternalSubset(void *ctx) } /** - * @param ctx the user data (XML parser context) - * * Does this document has an external subset * + * @param ctx the user data (XML parser context) * @returns 1 if true */ int @@ -214,12 +207,12 @@ xmlSAX2HasExternalSubset(void *ctx) } /** + * Callback on internal subset declaration. + * * @param ctx the user data (XML parser context) * @param name the root element name * @param ExternalID the external ID * @param SystemID the SYSTEM ID (e.g. filename or URL) - * - * Callback on internal subset declaration. */ void xmlSAX2InternalSubset(void *ctx, const xmlChar *name, @@ -246,12 +239,12 @@ xmlSAX2InternalSubset(void *ctx, const xmlChar *name, } /** + * Callback on external subset declaration. + * * @param ctx the user data (XML parser context) * @param name the root element name * @param ExternalID the external ID * @param SystemID the SYSTEM ID (e.g. filename or URL) - * - * Callback on external subset declaration. */ void xmlSAX2ExternalSubset(void *ctx, const xmlChar *name, @@ -369,13 +362,12 @@ error: } /** - * @param ctx the user data (XML parser context) - * @param publicId The public ID of the entity - * @param systemId The system ID of the entity - * * This is only used to load DTDs. The preferred way to install * custom resolvers is xmlCtxtSetResourceLoader(). * + * @param ctx the user data (XML parser context) + * @param publicId The public ID of the entity + * @param systemId The system ID of the entity * @returns a parser input. */ xmlParserInputPtr @@ -431,11 +423,10 @@ xmlSAX2ResolveEntity(void *ctx, const xmlChar *publicId, } /** - * @param ctx the user data (XML parser context) - * @param name The entity name - * * Get an entity by name * + * @param ctx the user data (XML parser context) + * @param name The entity name * @returns the xmlEntityPtr if found. */ xmlEntityPtr @@ -476,11 +467,10 @@ xmlSAX2GetEntity(void *ctx, const xmlChar *name) } /** - * @param ctx the user data (XML parser context) - * @param name The entity name - * * Get a parameter entity by name * + * @param ctx the user data (XML parser context) + * @param name The entity name * @returns the xmlEntityPtr if found. */ xmlEntityPtr @@ -497,14 +487,14 @@ xmlSAX2GetParameterEntity(void *ctx, const xmlChar *name) /** + * An entity definition has been parsed + * * @param ctx the user data (XML parser context) * @param name the entity name * @param type the entity type * @param publicId The public ID of the entity * @param systemId The system ID of the entity * @param content the entity value (without processing). - * - * An entity definition has been parsed */ void xmlSAX2EntityDecl(void *ctx, const xmlChar *name, int type, @@ -590,6 +580,8 @@ xmlSAX2EntityDecl(void *ctx, const xmlChar *name, int type, } /** + * An attribute definition has been parsed + * * @param ctx the user data (XML parser context) * @param elem the name of the element * @param fullname the attribute name @@ -597,8 +589,6 @@ xmlSAX2EntityDecl(void *ctx, const xmlChar *name, int type, * @param def the type of default value * @param defaultValue the attribute default value * @param tree the tree of enumerated value set - * - * An attribute definition has been parsed */ void xmlSAX2AttributeDecl(void *ctx, const xmlChar *elem, const xmlChar *fullname, @@ -659,12 +649,12 @@ xmlSAX2AttributeDecl(void *ctx, const xmlChar *elem, const xmlChar *fullname, } /** + * An element definition has been parsed + * * @param ctx the user data (XML parser context) * @param name the element name * @param type the element type * @param content the element value tree - * - * An element definition has been parsed */ void xmlSAX2ElementDecl(void *ctx, const xmlChar * name, int type, @@ -702,12 +692,12 @@ xmlSAX2ElementDecl(void *ctx, const xmlChar * name, int type, } /** + * What to do when a notation declaration has been parsed. + * * @param ctx the user data (XML parser context) * @param name The name of the notation * @param publicId The public ID of the entity * @param systemId The system ID of the entity - * - * What to do when a notation declaration has been parsed. */ void xmlSAX2NotationDecl(void *ctx, const xmlChar *name, @@ -749,13 +739,13 @@ xmlSAX2NotationDecl(void *ctx, const xmlChar *name, } /** + * What to do when an unparsed entity declaration is parsed + * * @param ctx the user data (XML parser context) * @param name The name of the entity * @param publicId The public ID of the entity * @param systemId The system ID of the entity * @param notationName the name of the notation - * - * What to do when an unparsed entity declaration is parsed */ void xmlSAX2UnparsedEntityDecl(void *ctx, const xmlChar *name, @@ -767,11 +757,11 @@ xmlSAX2UnparsedEntityDecl(void *ctx, const xmlChar *name, } /** - * @param ctx the user data (XML parser context) - * @param 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. + * + * @param ctx the user data (XML parser context) + * @param loc A SAX Locator */ void xmlSAX2SetDocumentLocator(void *ctx ATTRIBUTE_UNUSED, xmlSAXLocatorPtr loc ATTRIBUTE_UNUSED) @@ -779,9 +769,9 @@ xmlSAX2SetDocumentLocator(void *ctx ATTRIBUTE_UNUSED, xmlSAXLocatorPtr loc ATTRI } /** - * @param ctx the user data (XML parser context) - * * called when the document start being processed. + * + * @param ctx the user data (XML parser context) */ void xmlSAX2StartDocument(void *ctx) @@ -829,9 +819,9 @@ xmlSAX2StartDocument(void *ctx) } /** - * @param ctx the user data (XML parser context) - * * called when the document end has been detected. + * + * @param ctx the user data (XML parser context) */ void xmlSAX2EndDocument(void *ctx) @@ -896,13 +886,13 @@ xmlSAX2AppendChild(xmlParserCtxtPtr ctxt, xmlNodePtr node) { #if defined(LIBXML_SAX1_ENABLED) /** + * Handle a namespace error + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param str1 an error string * @param str2 an error string - * - * Handle a namespace error */ static void LIBXML_ATTR_FORMAT(3,0) xmlNsErrMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -913,14 +903,13 @@ xmlNsErrMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle an attribute that has been read by the parser. + * + * Deprecated SAX1 interface. * @param ctxt the parser context * @param fullname the attribute name, including namespace prefix * @param value the attribute value * @param prefix the namespace prefix - * - * Handle an attribute that has been read by the parser. - * - * Deprecated SAX1 interface. */ static void xmlSAX1Attribute(xmlParserCtxtPtr ctxt, const xmlChar *fullname, @@ -1360,13 +1349,12 @@ process_external_subset: } /** - * @param ctx the user data (XML parser context) - * @param fullname The element name, including namespace prefix - * @param atts An array of name/value attributes pairs, NULL terminated - * * called when an opening tag has been processed. * * Deprecated SAX1 interface. + * @param ctx the user data (XML parser context) + * @param fullname The element name, including namespace prefix + * @param atts An array of name/value attributes pairs, NULL terminated */ static void xmlSAX1StartElement(void *ctx, const xmlChar *fullname, const xmlChar **atts) @@ -1593,11 +1581,11 @@ xmlSAX2HtmlAttribute(xmlParserCtxtPtr ctxt, const xmlChar *fullname, } /** + * Called when an opening tag has been processed. + * * @param ctxt parser context * @param fullname The element name, including namespace prefix * @param atts An array of name/value attributes pairs, NULL terminated - * - * Called when an opening tag has been processed. */ static void xmlSAX2StartHtmlElement(xmlParserCtxtPtr ctxt, const xmlChar *fullname, @@ -1648,15 +1636,14 @@ xmlSAX2StartHtmlElement(xmlParserCtxtPtr ctxt, const xmlChar *fullname, #endif /* LIBXML_HTML_ENABLED */ /** - * @param ctx the user data (XML parser context) - * @param fullname The element name, including namespace prefix - * @param atts An array of name/value attributes pairs, NULL terminated + * Called when an opening tag has been processed. * * @deprecated Don't call this function directly. * - * Called when an opening tag has been processed. - * * Used for HTML and SAX1. + * @param ctx the user data (XML parser context) + * @param fullname The element name, including namespace prefix + * @param atts An array of name/value attributes pairs, NULL terminated */ void xmlSAX2StartElement(void *ctx, const xmlChar *fullname, const xmlChar **atts) { @@ -1683,14 +1670,13 @@ xmlSAX2StartElement(void *ctx, const xmlChar *fullname, const xmlChar **atts) { } /** - * @param ctx the user data (XML parser context) - * @param name The element name + * called when the end of an element has been detected. * * @deprecated Don't call this function directly. * - * called when the end of an element has been detected. - * * Used for HTML and SAX1. + * @param ctx the user data (XML parser context) + * @param name The element name */ void xmlSAX2EndElement(void *ctx, const xmlChar *name ATTRIBUTE_UNUSED) @@ -1833,17 +1819,16 @@ decode: #endif /* LIBXML_VALID_ENABLED */ /** - * @param ctxt the parser context - * @param localname the local name of the attribute - * @param prefix the attribute namespace prefix if available - * @param value start of the attribute value - * @param valueend end of 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. * + * @param ctxt the parser context + * @param localname the local name of the attribute + * @param prefix the attribute namespace prefix if available + * @param value start of the attribute value + * @param valueend end of the attribute value * @returns the new attribute or NULL in case of error. */ static xmlAttrPtr @@ -2065,6 +2050,10 @@ xmlSAX2AttributeNs(xmlParserCtxtPtr ctxt, } /** + * SAX2 callback when an element start has been detected by the parser. + * It provides the namespace information for the element, as well as + * the new namespace declarations on the element. + * * @param ctx the user data (XML parser context) * @param localname the local name of the element * @param prefix the element namespace prefix if available @@ -2075,10 +2064,6 @@ xmlSAX2AttributeNs(xmlParserCtxtPtr ctxt, * @param nb_defaulted the number of defaulted attributes. * @param attributes pointer to the array of (localname/prefix/URI/value/end) * attribute values. - * - * SAX2 callback when an element start has been detected by the parser. - * It provides the namespace information for the element, as well as - * the new namespace declarations on the element. */ void xmlSAX2StartElementNs(void *ctx, @@ -2340,13 +2325,13 @@ have_attr: } /** + * SAX2 callback when an element end has been detected by the parser. + * It provides the namespace information for the element. + * * @param ctx the user data (XML parser context) * @param localname the local name of the element * @param prefix the element namespace prefix if available * @param URI the element namespace name if available - * - * SAX2 callback when an element end has been detected by the parser. - * It provides the namespace information for the element. */ void xmlSAX2EndElementNs(void *ctx, @@ -2373,10 +2358,10 @@ xmlSAX2EndElementNs(void *ctx, } /** + * called when an entity xmlSAX2Reference() is detected. + * * @param ctx the user data (XML parser context) * @param name The entity name - * - * called when an entity xmlSAX2Reference() is detected. */ void xmlSAX2Reference(void *ctx, const xmlChar *name) @@ -2395,12 +2380,12 @@ xmlSAX2Reference(void *ctx, const xmlChar *name) } /** + * Append characters. + * * @param ctxt the parser context * @param ch a xmlChar string * @param len the number of xmlChar * @param type text or cdata - * - * Append characters. */ static void xmlSAX2Text(xmlParserCtxtPtr ctxt, const xmlChar *ch, int len, @@ -2536,11 +2521,11 @@ xmlSAX2Text(xmlParserCtxtPtr ctxt, const xmlChar *ch, int len, } /** + * receiving some chars from the parser. + * * @param ctx the user data (XML parser context) * @param ch a xmlChar string * @param len the number of xmlChar - * - * receiving some chars from the parser. */ void xmlSAX2Characters(void *ctx, const xmlChar *ch, int len) @@ -2549,12 +2534,12 @@ xmlSAX2Characters(void *ctx, const xmlChar *ch, int len) } /** + * receiving some ignorable whitespaces from the parser. + * UNUSED: by default the DOM building will use xmlSAX2Characters() + * * @param ctx the user data (XML parser context) * @param ch a xmlChar string * @param len the number of xmlChar - * - * receiving some ignorable whitespaces from the parser. - * UNUSED: by default the DOM building will use xmlSAX2Characters() */ void xmlSAX2IgnorableWhitespace(void *ctx ATTRIBUTE_UNUSED, const xmlChar *ch ATTRIBUTE_UNUSED, int len ATTRIBUTE_UNUSED) @@ -2562,11 +2547,11 @@ xmlSAX2IgnorableWhitespace(void *ctx ATTRIBUTE_UNUSED, const xmlChar *ch ATTRIBU } /** + * A processing instruction has been parsed. + * * @param ctx the user data (XML parser context) * @param target the target name * @param data the PI data's - * - * A processing instruction has been parsed. */ void xmlSAX2ProcessingInstruction(void *ctx, const xmlChar *target, @@ -2587,10 +2572,10 @@ xmlSAX2ProcessingInstruction(void *ctx, const xmlChar *target, } /** + * A xmlSAX2Comment() has been parsed. + * * @param ctx the user data (XML parser context) * @param value the xmlSAX2Comment() content - * - * A xmlSAX2Comment() has been parsed. */ void xmlSAX2Comment(void *ctx, const xmlChar *value) @@ -2610,11 +2595,11 @@ xmlSAX2Comment(void *ctx, const xmlChar *value) } /** + * called when a pcdata block has been parsed + * * @param ctx the user data (XML parser context) * @param value The pcdata content * @param len the block length - * - * called when a pcdata block has been parsed */ void xmlSAX2CDataBlock(void *ctx, const xmlChar *value, int len) @@ -2624,12 +2609,11 @@ xmlSAX2CDataBlock(void *ctx, const xmlChar *value, int len) #ifdef LIBXML_SAX1_ENABLED /** - * @param version the version, must be 2 + * Has no effect. * * @deprecated Use parser option XML_PARSE_SAX1. * - * Has no effect. - * + * @param version the version, must be 2 * @returns 2 in case of success and -1 in case of error. */ int @@ -2642,11 +2626,10 @@ xmlSAXDefaultVersion(int version) #endif /* LIBXML_SAX1_ENABLED */ /** - * @param hdlr the SAX handler - * @param version the version, 1 or 2 - * * Initialize the default XML SAX handler according to the version * + * @param hdlr the SAX handler + * @param version the version, 1 or 2 * @returns 0 in case of success and -1 in case of error. */ int @@ -2701,10 +2684,10 @@ xmlSAXVersion(xmlSAXHandler *hdlr, int version) } /** + * Initialize the default XML SAX2 handler + * * @param hdlr the SAX handler * @param warning flag if non-zero sets the handler warning procedure - * - * Initialize the default XML SAX2 handler */ void xmlSAX2InitDefaultSAXHandler(xmlSAXHandler *hdlr, int warning) @@ -2718,10 +2701,11 @@ xmlSAX2InitDefaultSAXHandler(xmlSAXHandler *hdlr, int warning) } /** + * Initialize the default SAX2 handler + * * @deprecated This function is a no-op. Call xmlInitParser() to * initialize the library. * - * Initialize the default SAX2 handler */ void xmlDefaultSAXHandlerInit(void) @@ -2731,9 +2715,9 @@ xmlDefaultSAXHandlerInit(void) #ifdef LIBXML_HTML_ENABLED /** - * @param hdlr the SAX handler - * * Initialize the default HTML SAX2 handler + * + * @param hdlr the SAX handler */ void xmlSAX2InitHtmlDefaultSAXHandler(xmlSAXHandler *hdlr) diff --git a/buf.c b/buf.c index 32c2ab96..32eda5f4 100644 --- a/buf.c +++ b/buf.c @@ -85,10 +85,10 @@ struct _xmlBuf { #endif /* WITH_BUFFER_COMPAT */ /** - * @param buf the buffer - * * Handle an out of memory condition * To be improved... + * + * @param buf the buffer */ static void xmlBufMemoryError(xmlBufPtr buf) @@ -98,10 +98,10 @@ xmlBufMemoryError(xmlBufPtr buf) } /** - * @param buf the buffer - * * Handle a buffer overflow error * To be improved... + * + * @param buf the buffer */ static void xmlBufOverflowError(xmlBufPtr buf) @@ -111,9 +111,9 @@ xmlBufOverflowError(xmlBufPtr buf) } /** - * @param size initial size of buffer - * * routine to create an XML buffer. + * + * @param size initial size of buffer * @returns the new structure. */ xmlBufPtr @@ -145,10 +145,6 @@ xmlBufCreate(size_t size) { } /** - * @param mem a memory area - * @param size size of the buffer excluding terminator - * @param isStatic whether the memory area is static - * * Create a buffer initialized with memory. * * If `isStatic` is set, uses the memory area directly as backing store. @@ -156,6 +152,9 @@ xmlBufCreate(size_t size) { * lifetime of the buffer. A static buffer can't be grown, modified or * detached, but it can be shrunk. * + * @param mem a memory area + * @param size size of the buffer excluding terminator + * @param isStatic whether the memory area is static * @returns a new buffer. */ xmlBufPtr @@ -198,12 +197,11 @@ xmlBufCreateMem(const xmlChar *mem, size_t size, int isStatic) { } /** - * @param buf the buffer - * * Remove the string contained in a buffer and give it back to the * caller. The buffer is reset to an empty content. * This doesn't work with immutable buffers as they can't be reset. * + * @param buf the buffer * @returns the previous string contained by the buffer. */ xmlChar * @@ -230,10 +228,10 @@ xmlBufDetach(xmlBufPtr buf) { } /** - * @param buf the buffer to free - * * Frees an XML buffer. It frees both the content and the structure which * encapsulate it. + * + * @param buf the buffer to free */ void xmlBufFree(xmlBufPtr buf) { @@ -246,9 +244,9 @@ xmlBufFree(xmlBufPtr buf) { } /** - * @param buf the buffer - * * empty a buffer. + * + * @param buf the buffer */ void xmlBufEmpty(xmlBufPtr buf) { @@ -267,16 +265,15 @@ xmlBufEmpty(xmlBufPtr buf) { } /** - * @param buf the buffer to dump - * @param len the number of xmlChar to remove - * - * @deprecated Don't use. - * * Remove the beginning of an XML buffer. * NOTE that this routine behaviour differs from xmlBufferShrink() * as it will return 0 on error instead of -1 due to size_t being * used as the return type. * + * @deprecated Don't use. + * + * @param buf the buffer to dump + * @param len the number of xmlChar to remove * @returns the number of byte removed or 0 in case of failure */ size_t @@ -299,11 +296,10 @@ xmlBufShrink(xmlBufPtr buf, size_t len) { } /** - * @param buf the buffer - * @param len the minimum free size to allocate - * * Grow the available space of an XML buffer, `len` is the target value * + * @param buf the buffer + * @param len the minimum free size to allocate * @returns 0 on success, -1 in case of error */ static int @@ -365,12 +361,11 @@ xmlBufGrowInternal(xmlBufPtr buf, size_t len) { } /** - * @param buf the buffer - * @param len the minimum free size to allocate - * * Grow the available space of an XML buffer, `len` is the target value * This is been kept compatible with xmlBufferGrow() as much as possible * + * @param buf the buffer + * @param len the minimum free size to allocate * @returns 0 on succes, -1 in case of error */ int @@ -390,10 +385,9 @@ xmlBufGrow(xmlBufPtr buf, size_t len) { } /** - * @param buf the buffer - * * Function to extract the content of a buffer * + * @param buf the buffer * @returns the internal content */ @@ -407,10 +401,9 @@ xmlBufContent(const xmlBuf *buf) } /** - * @param buf the buffer - * * Function to extract the end of the content of a buffer * + * @param buf the buffer * @returns the end of the internal content or NULL in case of error */ @@ -425,13 +418,12 @@ xmlBufEnd(xmlBufPtr buf) } /** - * @param buf the buffer - * @param len the size which were added at the end - * * Sometime data may be added at the end of the buffer without * using the xmlBuf APIs that is used to expand the used space * and set the zero terminating at the end of the buffer * + * @param buf the buffer + * @param len the size which were added at the end * @returns -1 in case of error and 0 otherwise */ int @@ -448,10 +440,9 @@ xmlBufAddLen(xmlBufPtr buf, size_t len) { } /** - * @param buf the buffer - * * Function to get the length of a buffer * + * @param buf the buffer * @returns the length of data in the internal content */ @@ -466,13 +457,12 @@ xmlBufUse(const xmlBufPtr buf) } /** - * @param buf the buffer - * * Function to find how much free space is allocated but not * used in the buffer. It reserves one byte for the NUL * terminator character that is usually needed, so there is * no need to subtract 1 from the result anymore. * + * @param buf the buffer * @returns the amount, or 0 if none or if an error occurred. */ @@ -487,10 +477,9 @@ xmlBufAvail(const xmlBufPtr buf) } /** - * @param buf the buffer - * * Tell if a buffer is empty * + * @param buf the buffer * @returns 0 if no, 1 if yes and -1 in case of error */ int @@ -504,13 +493,12 @@ xmlBufIsEmpty(const xmlBufPtr buf) } /** - * @param buf the buffer to dump - * @param str the \#xmlChar string - * @param len the number of \#xmlChar to add - * * Add a string range to an XML buffer. if len == -1, the length of * str is recomputed. * + * @param buf the buffer to dump + * @param str the \#xmlChar string + * @param len the number of \#xmlChar to add * @returns 0 if successful, -1 in case of error. */ int @@ -537,11 +525,10 @@ xmlBufAdd(xmlBufPtr buf, const xmlChar *str, size_t len) { } /** - * @param buf the buffer to add to - * @param str the \#xmlChar string (optional) - * * Append a zero terminated string to an XML buffer. * + * @param buf the buffer to add to + * @param str the \#xmlChar string (optional) * @returns 0 successful, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -553,13 +540,12 @@ xmlBufCat(xmlBufPtr buf, const xmlChar *str) { } /** - * @param buffer incoming old buffer to convert to a new one - * * Helper routine to switch from the old buffer structures in use * in various APIs. It creates a wrapper xmlBufPtr which will be * used for internal processing until the xmlBufBackToBuffer() is * issued. * + * @param buffer incoming old buffer to convert to a new one * @returns a new xmlBufPtr unless the call failed and NULL is returned */ xmlBufPtr @@ -599,15 +585,14 @@ xmlBufFromBuffer(xmlBufferPtr buffer) { } /** - * @param buf new buffer wrapping the old one - * @param ret old buffer - * * Function to be called once internal processing had been done to * update back the buffer provided by the user. This can lead to * a failure in case the size accumulated in the xmlBuf is larger * than what an xmlBuffer can support on 64 bits (INT_MAX) * The xmlBufPtr `buf` wrapper is deallocated by this call in any case. * + * @param buf new buffer wrapping the old one + * @param ret old buffer * @returns 0 on success, -1 on error. */ int @@ -640,11 +625,10 @@ xmlBufBackToBuffer(xmlBufPtr buf, xmlBufferPtr ret) { } /** - * @param buf an xmlBufPtr - * @param input an xmlParserInputPtr - * * Update the input to use the current set of pointers from the buffer. * + * @param buf an xmlBufPtr + * @param input an xmlParserInputPtr * @returns -1 in case of error, 0 otherwise */ int @@ -653,13 +637,12 @@ xmlBufResetInput(xmlBufPtr buf, xmlParserInputPtr input) { } /** - * @param buf an xmlBufPtr - * @param input an xmlParserInputPtr - * @param pos the cur value relative to the beginning of the buffer - * * Update the input to use the base and cur relative to the buffer * after a possible reallocation of its content * + * @param buf an xmlBufPtr + * @param input an xmlParserInputPtr + * @param pos the cur value relative to the beginning of the buffer * @returns -1 in case of error, 0 otherwise */ int @@ -680,22 +663,20 @@ xmlBufUpdateInput(xmlBufPtr buf, xmlParserInputPtr input, size_t pos) { ************************************************************************/ /** - * @param scheme allocation method to use - * - * @deprecated Use xmlBufferSetAllocationScheme(). - * * Set the buffer allocation method. Types are * XML_BUFFER_ALLOC_EXACT - use exact sizes, keeps memory usage down * XML_BUFFER_ALLOC_DOUBLEIT - double buffer when extra needed, * improves performance + * + * @deprecated Use xmlBufferSetAllocationScheme(). + * + * @param scheme allocation method to use */ void xmlSetBufferAllocationScheme(xmlBufferAllocationScheme scheme ATTRIBUTE_UNUSED) { } /** - * @deprecated Use xmlBufferSetAllocationScheme(). - * * Types are * XML_BUFFER_ALLOC_EXACT - use exact sizes, keeps memory usage down * XML_BUFFER_ALLOC_DOUBLEIT - double buffer when extra needed, @@ -704,6 +685,8 @@ xmlSetBufferAllocationScheme(xmlBufferAllocationScheme scheme ATTRIBUTE_UNUSED) * in normal usage, and doubleit on large strings to avoid * pathological performance. * + * @deprecated Use xmlBufferSetAllocationScheme(). + * * @returns the current allocation scheme */ xmlBufferAllocationScheme @@ -739,9 +722,9 @@ xmlBufferCreate(void) { } /** - * @param size initial size of buffer - * * routine to create an XML buffer. + * + * @param size initial size of buffer * @returns the new structure. */ xmlBufferPtr @@ -776,12 +759,11 @@ xmlBufferCreateSize(size_t size) { } /** - * @param buf the buffer - * * Remove the string contained in a buffer and gie it back to the * caller. The buffer is reset to an empty content. * This doesn't work with immutable buffers as they can't be reset. * + * @param buf the buffer * @returns the previous string contained by the buffer. */ xmlChar * @@ -810,7 +792,6 @@ xmlBufferDetach(xmlBufferPtr buf) { /** * @param mem the memory area * @param size the size in byte - * * @returns an XML buffer initialized with bytes. */ xmlBufferPtr @@ -822,13 +803,12 @@ xmlBufferCreateStatic(void *mem, size_t size) { } /** - * @param buf the buffer to tune - * @param scheme allocation scheme to use - * * Sets the allocation scheme for this buffer. * * For libxml2 before 2.14, it is recommended to set this to * XML_BUFFER_ALLOC_DOUBLE_IT. Has no effect on 2.14 or later. + * @param buf the buffer to tune + * @param scheme allocation scheme to use */ void xmlBufferSetAllocationScheme(xmlBufferPtr buf ATTRIBUTE_UNUSED, @@ -836,10 +816,10 @@ xmlBufferSetAllocationScheme(xmlBufferPtr buf ATTRIBUTE_UNUSED, } /** - * @param buf the buffer to free - * * Frees an XML buffer. It frees both the content and the structure which * encapsulate it. + * + * @param buf the buffer to free */ void xmlBufferFree(xmlBufferPtr buf) { @@ -855,9 +835,9 @@ xmlBufferFree(xmlBufferPtr buf) { } /** - * @param buf the buffer - * * empty a buffer. + * + * @param buf the buffer */ void xmlBufferEmpty(xmlBufferPtr buf) { @@ -878,13 +858,12 @@ xmlBufferEmpty(xmlBufferPtr buf) { } /** - * @param buf the buffer to dump - * @param len the number of xmlChar to remove + * Remove the beginning of an XML buffer. * * @deprecated Don't use. * - * Remove the beginning of an XML buffer. - * + * @param buf the buffer to dump + * @param len the number of xmlChar to remove * @returns the number of \#xmlChar removed, or -1 in case of failure. */ int @@ -909,13 +888,12 @@ xmlBufferShrink(xmlBufferPtr buf, unsigned int len) { } /** - * @param buf the buffer - * @param len the minimum free size to allocate + * Grow the available space of an XML buffer. * * @deprecated Don't use. * - * Grow the available space of an XML buffer. - * + * @param buf the buffer + * @param len the minimum free size to allocate * @returns the new available space or -1 in case of error */ int @@ -965,10 +943,10 @@ xmlBufferGrow(xmlBufferPtr buf, unsigned int len) { } /** + * Dumps an XML buffer to a FILE *. + * * @param file the file output * @param buf the buffer to dump - * - * Dumps an XML buffer to a FILE *. * @returns the number of \#xmlChar written */ int @@ -986,10 +964,9 @@ xmlBufferDump(FILE *file, xmlBufferPtr buf) { } /** - * @param buf the buffer - * * Function to extract the content of a buffer * + * @param buf the buffer * @returns the internal content */ @@ -1003,10 +980,9 @@ xmlBufferContent(const xmlBuffer *buf) } /** - * @param buf the buffer - * * Function to get the length of a buffer * + * @param buf the buffer * @returns the length of data in the internal content */ @@ -1020,13 +996,12 @@ xmlBufferLength(const xmlBuffer *buf) } /** - * @param buf the buffer to resize - * @param size the desired size - * * @deprecated Don't use. * Resize a buffer to accommodate minimum size of `size`. * + * @param buf the buffer to resize + * @param size the desired size * @returns 0 in case of problems, 1 otherwise */ int @@ -1044,13 +1019,12 @@ xmlBufferResize(xmlBufferPtr buf, unsigned int size) } /** - * @param buf the buffer to dump - * @param str the \#xmlChar string - * @param len the number of \#xmlChar to add - * * Add a string range to an XML buffer. if len == -1, the length of * str is recomputed. * + * @param buf the buffer to dump + * @param str the \#xmlChar string + * @param len the number of \#xmlChar to add * @returns a xmlParserErrors code. */ int @@ -1075,13 +1049,12 @@ xmlBufferAdd(xmlBufferPtr buf, const xmlChar *str, int len) { } /** - * @param buf the buffer - * @param str the \#xmlChar string - * @param len the number of \#xmlChar to add - * * Add a string range to the beginning of an XML buffer. * if len == -1, the length of `str` is recomputed. * + * @param buf the buffer + * @param str the \#xmlChar string + * @param len the number of \#xmlChar to add * @returns a xmlParserErrors code. */ int @@ -1130,11 +1103,10 @@ xmlBufferAddHead(xmlBufferPtr buf, const xmlChar *str, int len) { } /** - * @param buf the buffer to add to - * @param str the \#xmlChar string - * * Append a zero terminated string to an XML buffer. * + * @param buf the buffer to add to + * @param str the \#xmlChar string * @returns 0 successful, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -1144,11 +1116,10 @@ xmlBufferCat(xmlBufferPtr buf, const xmlChar *str) { } /** - * @param buf the buffer to dump - * @param str the C char string - * * Append a zero terminated C string to an XML buffer. * + * @param buf the buffer to dump + * @param str the C char string * @returns 0 successful, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -1158,11 +1129,11 @@ xmlBufferCCat(xmlBufferPtr buf, const char *str) { } /** - * @param buf the XML buffer - * @param string the string to add - * * routine which manages and grows an output buffer. This one adds * xmlChars at the end of the buffer. + * + * @param buf the XML buffer + * @param string the string to add */ void xmlBufferWriteCHAR(xmlBufferPtr buf, const xmlChar *string) { @@ -1170,11 +1141,11 @@ xmlBufferWriteCHAR(xmlBufferPtr buf, const xmlChar *string) { } /** - * @param buf the XML buffer output - * @param string the string to add - * * routine which manage and grows an output buffer. This one add * C chars at the end of the array. + * + * @param buf the XML buffer output + * @param string the string to add */ void xmlBufferWriteChar(xmlBufferPtr buf, const char *string) { @@ -1183,12 +1154,12 @@ xmlBufferWriteChar(xmlBufferPtr buf, const char *string) { /** - * @param buf the XML buffer output - * @param string the string to add - * * routine which manage and grows an output buffer. This one writes * a quoted or double quoted \#xmlChar string, checking first if it holds * quote or double-quotes internally + * + * @param buf the XML buffer output + * @param string the string to add */ void xmlBufferWriteQuotedString(xmlBufferPtr buf, const xmlChar *string) { diff --git a/c14n.c b/c14n.c index 8ecd1cfe..12537b12 100644 --- a/c14n.c +++ b/c14n.c @@ -129,9 +129,9 @@ static xmlChar *xmlC11NNormalizeString(const xmlChar * input, ************************************************************************/ /** - * @param ctxt a C14N evaluation context - * * Handle a redefinition of memory error + * + * @param ctxt a C14N evaluation context */ static void xmlC14NErrMemory(xmlC14NCtxPtr ctxt) @@ -163,9 +163,9 @@ xmlC14NErrFull(xmlC14NCtxPtr ctxt, xmlNodePtr node, int code, const char *str1, } /** - * @param ctxt a C14N evaluation context - * * Handle a param error + * + * @param ctxt a C14N evaluation context */ static void xmlC14NErrParam(xmlC14NCtxPtr ctxt) @@ -175,11 +175,11 @@ xmlC14NErrParam(xmlC14NCtxPtr ctxt) } /** + * Handle an invalid node error + * * @param ctxt a C14N evaluation context * @param node_type node type * @param extra extra information - * - * Handle an invalid node error */ static void xmlC14NErrInvalidNode(xmlC14NCtxPtr ctxt, const char *node_type, @@ -190,11 +190,11 @@ xmlC14NErrInvalidNode(xmlC14NCtxPtr ctxt, const char *node_type, } /** + * Handle an unknown node error + * * @param ctxt a C14N evaluation context * @param node_type node type * @param extra extra information - * - * Handle an unknown node error */ static void xmlC14NErrUnknownNode(xmlC14NCtxPtr ctxt, int node_type, const char *extra) @@ -204,10 +204,10 @@ xmlC14NErrUnknownNode(xmlC14NCtxPtr ctxt, int node_type, const char *extra) } /** + * Handle a relative namespace error + * * @param ctxt a C14N evaluation context * @param ns_uri namespace URI - * - * Handle a relative namespace error */ static void xmlC14NErrRelativeNamespace(xmlC14NCtxPtr ctxt, const char *ns_uri) @@ -219,12 +219,12 @@ xmlC14NErrRelativeNamespace(xmlC14NCtxPtr ctxt, const char *ns_uri) /** + * Handle an error + * * @param ctxt a C14N evaluation context * @param node the context node * @param error the error code * @param msg the message - * - * Handle an error */ static void xmlC14NErr(xmlC14NCtxPtr ctxt, xmlNodePtr node, int error, @@ -379,11 +379,10 @@ xmlC14NStrEqual(const xmlChar *str1, const xmlChar *str2) { } /** - * @param cur the visible stack - * @param ns the namespace to check - * * Checks whether the given namespace was already rendered or not * + * @param cur the visible stack + * @param ns the namespace to check * @returns 1 if we already wrote this namespace or 0 otherwise */ static int @@ -461,11 +460,10 @@ xmlExcC14NVisibleNsStackFind(xmlC14NVisibleNsStackPtr cur, xmlNsPtr ns, xmlC14NC /** - * @param ns the namespace to check - * * Checks whether the given namespace is a default "xml:" namespace * with href="http://www.w3.org/XML/1998/namespace" * + * @param ns the namespace to check * @returns 1 if the node is default or 0 otherwise */ @@ -480,11 +478,10 @@ xmlC14NIsXmlNs(xmlNsPtr ns) /** - * @param data1 the pointer to first namespace - * @param data2 the pointer to second namespace - * * Compares the namespaces by names (prefixes). * + * @param data1 the pointer to first namespace + * @param data2 the pointer to second namespace * @returns -1 if ns1 < ns2, 0 if ns1 == ns2 or 1 if ns1 > ns2. */ static int @@ -504,11 +501,10 @@ xmlC14NNsCompare(const void *data1, const void *data2) /** - * @param ns the pointer to namespace - * @param ctx the C14N context - * * Prints the given namespace to the output buffer from C14N context. * + * @param ns the pointer to namespace + * @param ctx the C14N context * @returns 1 on success or 0 on fail. */ static int @@ -541,10 +537,6 @@ xmlC14NPrintNamespacesWalker(const void *ns, void *ctx) { } /** - * @param ctx the C14N context - * @param cur the current node - * @param visible the visibility of node - * * Prints out canonical namespace axis of the current node to the * buffer from C14N context as follows * @@ -577,6 +569,9 @@ xmlC14NPrintNamespacesWalker(const void *ns, void *ctx) { * the document subset). This search and copying are omitted from the * Exclusive XML Canonicalization method. * + * @param ctx the C14N context + * @param cur the current node + * @param visible the visibility of node * @returns 0 on success or -1 on fail. */ static int @@ -659,10 +654,6 @@ error: /** - * @param ctx the C14N context - * @param cur the current node - * @param visible the visibility of node - * * Prints out exclusive canonical namespace axis of the current node to the * buffer from C14N context as follows * @@ -686,6 +677,9 @@ error: * 3. After the recursion returns, pop thestate stack. * * + * @param ctx the C14N context + * @param cur the current node + * @param visible the visibility of node * @returns 0 on success or -1 on fail. */ static int @@ -846,11 +840,10 @@ error: /** - * @param attr the attr to check - * * Checks whether the given attribute is a default "xml:" namespace * with href="http://www.w3.org/XML/1998/namespace" * + * @param attr the attr to check * @returns 1 if the node is default or 0 otherwise */ @@ -864,11 +857,10 @@ xmlC14NIsXmlAttr(xmlAttrPtr attr) /** - * @param data1 the pointer tls o first attr - * @param data2 the pointer to second attr - * * Prints the given attribute to the output buffer from C14N context. * + * @param data1 the pointer tls o first attr + * @param data2 the pointer to second attr * @returns -1 if attr1 < attr2, 0 if attr1 == attr2 or 1 if attr1 > attr2. */ static int @@ -914,14 +906,13 @@ xmlC14NAttrsCompare(const void *data1, const void *data2) /** - * @param data the pointer to attr - * @param user the C14N context - * * Prints out canonical attribute urrent node to the * buffer from C14N context as follows * * Canonical XML v 1.0 (http://www.w3.org/TR/xml-c14n) * + * @param data the pointer to attr + * @param user the C14N context * @returns 1 on success or 0 on fail. */ static int @@ -1089,10 +1080,6 @@ xmlC14NFixupBaseAttr(xmlC14NCtxPtr ctx, xmlAttrPtr xml_base_attr) } /** - * @param ctx the C14N context - * @param cur the current node - * @param parent_visible the visibility of the parent node - * * Prints out canonical attribute axis of the current node to the * buffer from C14N context as follows * @@ -1117,6 +1104,9 @@ xmlC14NFixupBaseAttr(xmlC14NCtxPtr ctx, xmlAttrPtr xml_base_attr) * the document subset). This search and copying are omitted from the * Exclusive XML Canonicalization method. * + * @param ctx the C14N context + * @param cur the current node + * @param parent_visible the visibility of the parent node * @returns 0 on success or -1 on fail. */ static int @@ -1339,11 +1329,10 @@ xmlC14NProcessAttrsAxis(xmlC14NCtxPtr ctx, xmlNodePtr cur, int parent_visible) } /** - * @param ctx the C14N context - * @param cur the current element node - * * Checks that current element node has no relative namespaces defined * + * @param ctx the C14N context + * @param cur the current element node * @returns 0 if the node has no relative namespaces or -1 otherwise. */ static int @@ -1384,10 +1373,6 @@ xmlC14NCheckForRelativeNamespaces(xmlC14NCtxPtr ctx, xmlNodePtr cur) } /** - * @param ctx the pointer to C14N context object - * @param cur the node to process - * @param visible this node is visible - * * Canonical XML v 1.0 (http://www.w3.org/TR/xml-c14n) * * Element Nodes @@ -1402,6 +1387,9 @@ xmlC14NCheckForRelativeNamespaces(xmlC14NCtxPtr ctx, xmlNodePtr cur) * open angle bracket, a forward slash (/), the element QName, and a close * angle bracket. * + * @param ctx the pointer to C14N context object + * @param cur the node to process + * @param visible this node is visible * @returns non-negative value on success or negative value on fail */ static int @@ -1495,11 +1483,10 @@ xmlC14NProcessElementNode(xmlC14NCtxPtr ctx, xmlNodePtr cur, int visible) } /** - * @param ctx the pointer to C14N context object - * @param cur the node to process - * * Processes the given node * + * @param ctx the pointer to C14N context object + * @param cur the node to process * @returns non-negative value on success or negative value on fail */ static int @@ -1682,11 +1669,10 @@ xmlC14NProcessNode(xmlC14NCtxPtr ctx, xmlNodePtr cur) } /** - * @param ctx the pointer to C14N context object - * @param cur the node to start from - * * Processes all nodes in the row starting from cur. * + * @param ctx the pointer to C14N context object + * @param cur the node to start from * @returns non-negative value on success or negative value on fail */ static int @@ -1707,9 +1693,9 @@ xmlC14NProcessNodeList(xmlC14NCtxPtr ctx, xmlNodePtr cur) /** - * @param ctx the pointer to C14N context object - * * Cleanups the C14N context object. + * + * @param ctx the pointer to C14N context object */ static void @@ -1727,6 +1713,8 @@ xmlC14NFreeCtx(xmlC14NCtxPtr ctx) } /** + * Creates new C14N context object to store C14N parameters. + * * @param doc the XML document for canonization * @param is_visible_callback the function to use to determine is node visible * or not @@ -1741,9 +1729,6 @@ xmlC14NFreeCtx(xmlC14NCtxPtr ctx) * @param buf the output buffer to store canonical XML; this * buffer MUST have encoder==NULL because C14N requires * UTF-8 output - * - * Creates new C14N context object to store C14N parameters. - * * @returns pointer to newly created object (success) or NULL (fail) */ static xmlC14NCtxPtr @@ -1809,6 +1794,10 @@ xmlC14NNewCtx(xmlDocPtr doc, } /** + * Dumps the canonized image of given XML document into the provided buffer. + * For details see "Canonical XML" (http://www.w3.org/TR/xml-c14n) or + * "Exclusive XML Canonicalization" (http://www.w3.org/TR/xml-exc-c14n) + * * @param doc the XML document for canonization * @param is_visible_callback the function to use to determine is node visible * or not @@ -1823,11 +1812,6 @@ xmlC14NNewCtx(xmlDocPtr doc, * @param buf the output buffer to store canonical XML; this * buffer MUST have encoder==NULL because C14N requires * UTF-8 output - * - * Dumps the canonized image of given XML document into the provided buffer. - * For details see "Canonical XML" (http://www.w3.org/TR/xml-c14n) or - * "Exclusive XML Canonicalization" (http://www.w3.org/TR/xml-exc-c14n) - * * @returns non-negative value on success or a negative value on fail */ int @@ -1911,6 +1895,10 @@ xmlC14NExecute(xmlDocPtr doc, xmlC14NIsVisibleCallback is_visible_callback, } /** + * Dumps the canonized image of given XML document into the provided buffer. + * For details see "Canonical XML" (http://www.w3.org/TR/xml-c14n) or + * "Exclusive XML Canonicalization" (http://www.w3.org/TR/xml-exc-c14n) + * * @param doc the XML document for canonization * @param nodes the nodes set to be included in the canonized image * or NULL if all document nodes should be included @@ -1923,11 +1911,6 @@ xmlC14NExecute(xmlDocPtr doc, xmlC14NIsVisibleCallback is_visible_callback, * @param buf the output buffer to store canonical XML; this * buffer MUST have encoder==NULL because C14N requires * UTF-8 output - * - * Dumps the canonized image of given XML document into the provided buffer. - * For details see "Canonical XML" (http://www.w3.org/TR/xml-c14n) or - * "Exclusive XML Canonicalization" (http://www.w3.org/TR/xml-exc-c14n) - * * @returns non-negative value on success or a negative value on fail */ int @@ -1945,6 +1928,10 @@ xmlC14NDocSaveTo(xmlDocPtr doc, xmlNodeSetPtr nodes, /** + * Dumps the canonized image of given XML document into memory. + * For details see "Canonical XML" (http://www.w3.org/TR/xml-c14n) or + * "Exclusive XML Canonicalization" (http://www.w3.org/TR/xml-exc-c14n) + * * @param doc the XML document for canonization * @param nodes the nodes set to be included in the canonized image * or NULL if all document nodes should be included @@ -1957,11 +1944,6 @@ xmlC14NDocSaveTo(xmlDocPtr doc, xmlNodeSetPtr nodes, * @param doc_txt_ptr the memory pointer for allocated canonical XML text; * the caller of this functions is responsible for calling * xmlFree() to free allocated memory - * - * Dumps the canonized image of given XML document into memory. - * For details see "Canonical XML" (http://www.w3.org/TR/xml-c14n) or - * "Exclusive XML Canonicalization" (http://www.w3.org/TR/xml-exc-c14n) - * * @returns the number of bytes written on success or a negative value on fail */ int @@ -2012,6 +1994,10 @@ xmlC14NDocDumpMemory(xmlDocPtr doc, xmlNodeSetPtr nodes, } /** + * Dumps the canonized image of given XML document into the file. + * For details see "Canonical XML" (http://www.w3.org/TR/xml-c14n) or + * "Exclusive XML Canonicalization" (http://www.w3.org/TR/xml-exc-c14n) + * * @param doc the XML document for canonization * @param nodes the nodes set to be included in the canonized image * or NULL if all document nodes should be included @@ -2026,11 +2012,6 @@ xmlC14NDocDumpMemory(xmlDocPtr doc, xmlNodeSetPtr nodes, * -1 - libxml default, * 0 - uncompressed, * >0 - compression level - * - * Dumps the canonized image of given XML document into the file. - * For details see "Canonical XML" (http://www.w3.org/TR/xml-c14n) or - * "Exclusive XML Canonicalization" (http://www.w3.org/TR/xml-exc-c14n) - * * @returns the number of bytes written success or a negative value on fail */ int @@ -2077,13 +2058,12 @@ xmlC14NDocSave(xmlDocPtr doc, xmlNodeSetPtr nodes, } /** - * @param input the input string - * @param mode the normalization mode (attribute, comment, PI or text) - * * Converts a string to a canonical (normalized) format. The code is stolen * from xmlEncodeEntitiesReentrant(). Added normalization of `\x09`, `\x0a`, * `\x0A` and the `mode` parameter. * + * @param input the input string + * @param mode the normalization mode (attribute, comment, PI or text) * @returns a normalized string (caller is responsible for calling xmlFree()) * or NULL if an error occurs */ diff --git a/catalog.c b/catalog.c index 0ad8debb..0e846075 100644 --- a/catalog.c +++ b/catalog.c @@ -194,6 +194,8 @@ xmlCatalogErrMemory(void) } /** + * Handle a catalog error + * * @param catal the Catalog entry * @param node the context node * @param error the error code @@ -201,8 +203,6 @@ xmlCatalogErrMemory(void) * @param str1 error string 1 * @param str2 error string 2 * @param str3 error string 3 - * - * Handle a catalog error */ static void LIBXML_ATTR_FORMAT(4,0) xmlCatalogErr(xmlCatalogEntryPtr catal, xmlNodePtr node, int error, @@ -236,16 +236,15 @@ xmlCatalogPrintDebug(const char *fmt, ...) { ************************************************************************/ /** + * create a new Catalog entry, this type is shared both by XML and + * SGML catalogs, but the acceptable types values differs. + * * @param type type of entry * @param name name of the entry * @param value value of the entry * @param URL URL of the entry * @param prefer the PUBLIC vs. SYSTEM current preference value * @param group for members of a group, the group entry - * - * create a new Catalog entry, this type is shared both by XML and - * SGML catalogs, but the acceptable types values differs. - * * @returns the xmlCatalogEntryPtr or NULL in case of error */ static xmlCatalogEntryPtr @@ -296,10 +295,10 @@ static void xmlFreeCatalogEntryList(xmlCatalogEntryPtr ret); /** + * Free the memory allocated to a Catalog entry + * * @param payload a Catalog entry * @param name unused - * - * Free the memory allocated to a Catalog entry */ static void xmlFreeCatalogEntry(void *payload, const xmlChar *name ATTRIBUTE_UNUSED) { @@ -335,9 +334,9 @@ xmlFreeCatalogEntry(void *payload, const xmlChar *name ATTRIBUTE_UNUSED) { } /** - * @param ret a Catalog entry list - * * Free the memory allocated to a full chained list of Catalog entries + * + * @param ret a Catalog entry list */ static void xmlFreeCatalogEntryList(xmlCatalogEntryPtr ret) { @@ -351,11 +350,11 @@ xmlFreeCatalogEntryList(xmlCatalogEntryPtr ret) { } /** - * @param payload a Catalog entry list - * @param name unused - * * Free the memory allocated to list of Catalog entries from the * catalog file hash. + * + * @param payload a Catalog entry list + * @param name unused */ static void xmlFreeCatalogHashEntryList(void *payload, @@ -379,12 +378,11 @@ xmlFreeCatalogHashEntryList(void *payload, } /** - * @param type type of catalog - * @param prefer the PUBLIC vs. SYSTEM current preference value - * * create a new Catalog, this type is shared both by XML and * SGML catalogs, but the acceptable types values differs. * + * @param type type of catalog + * @param prefer the PUBLIC vs. SYSTEM current preference value * @returns the xmlCatalogPtr or NULL in case of error */ static xmlCatalogPtr @@ -407,9 +405,9 @@ xmlCreateNewCatalog(xmlCatalogType type, xmlCatalogPrefer prefer) { } /** - * @param catal a Catalog - * * Free the memory allocated to a Catalog + * + * @param catal a Catalog */ void xmlFreeCatalog(xmlCatalogPtr catal) { @@ -430,11 +428,11 @@ xmlFreeCatalog(xmlCatalogPtr catal) { #ifdef LIBXML_OUTPUT_ENABLED /** + * Serialize an SGML Catalog entry + * * @param payload the catalog entry * @param data the file. * @param name unused - * - * Serialize an SGML Catalog entry */ static void xmlCatalogDumpEntry(void *payload, void *data, @@ -506,14 +504,14 @@ xmlCatalogDumpEntry(void *payload, void *data, } /** + * Serializes a Catalog entry, called by xmlDumpXMLCatalog() and recursively + * for group entries + * * @param catal top catalog entry * @param catalog pointer to the xml tree * @param doc the containing document * @param ns the current namespace * @param cgroup group node for group members - * - * Serializes a Catalog entry, called by xmlDumpXMLCatalog() and recursively - * for group entries */ static void xmlDumpXMLCatalogNode(xmlCatalogEntryPtr catal, xmlNodePtr catalog, xmlDocPtr doc, xmlNsPtr ns, xmlCatalogEntryPtr cgroup) { @@ -695,11 +693,11 @@ BAD_CAST "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"); ************************************************************************/ /** + * Convert one entry from the catalog + * * @param payload the entry * @param data pointer to the catalog being converted * @param name unused - * - * Convert one entry from the catalog */ static void xmlCatalogConvertEntry(void *payload, void *data, @@ -761,10 +759,9 @@ xmlCatalogConvertEntry(void *payload, void *data, } /** - * @param catal the catalog - * * Convert all the SGML catalog entries as XML ones * + * @param catal the catalog * @returns the number of entries converted if successful, -1 otherwise */ int @@ -788,10 +785,9 @@ xmlConvertSGMLCatalog(xmlCatalogPtr catal) { ************************************************************************/ /** - * @param urn an "urn:publicid:" to unwrap - * * Expand the URN into the equivalent Public Identifier * + * @param urn an "urn:publicid:" to unwrap * @returns the new identifier or NULL, the string must be deallocated * by the caller. */ @@ -852,13 +848,12 @@ xmlCatalogUnWrapURN(const xmlChar *urn) { } /** - * @param filename the filename - * - * @deprecated Use XML_PARSE_NO_SYS_CATALOG. - * * parse an XML file and build a tree. It's like xmlParseFile() * except it bypass all catalog lookups. * + * @deprecated Use XML_PARSE_NO_SYS_CATALOG. + * + * @param filename the filename * @returns the resulting document tree or NULL in case of error */ @@ -919,10 +914,9 @@ xmlParseCatalogFile(const char *filename) { } /** - * @param filename a file path - * * Load a file content into memory. * + * @param filename a file path * @returns a pointer to the 0 terminated string or NULL in case of error */ static xmlChar * @@ -965,13 +959,12 @@ xmlLoadFileContent(const char *filename) } /** - * @param pubID the public ID string - * * Normalizes the Public Identifier * * Implements 6.2. Public Identifier Normalization * from http://www.oasis-open.org/committees/entity/spec-2001-08-06.html * + * @param pubID the public ID string * @returns the new string or NULL, the string must be deallocated * by the caller. */ @@ -1037,10 +1030,9 @@ xmlCatalogListXMLResolveURI(xmlCatalogEntryPtr catal, const xmlChar *URI); /** - * @param name the name - * * lookup the internal type associated to an XML catalog entry name * + * @param name the name * @returns the type associated with that name */ static xmlCatalogEntryType @@ -1070,6 +1062,9 @@ xmlGetXMLCatalogEntryType(const xmlChar *name) { } /** + * Finishes the examination of an XML tree node of a catalog and build + * a Catalog entry from it. + * * @param cur the XML node * @param type the type of Catalog entry * @param name the name of the node @@ -1077,10 +1072,6 @@ xmlGetXMLCatalogEntryType(const xmlChar *name) { * @param uriAttrName the attribute holding the URI-Reference * @param prefer the PUBLIC vs. SYSTEM current preference value * @param cgroup the group which includes this node - * - * Finishes the examination of an XML tree node of a catalog and build - * a Catalog entry from it. - * * @returns the new Catalog entry node or NULL in case of error. */ static xmlCatalogEntryPtr @@ -1145,14 +1136,14 @@ xmlParseXMLCatalogOneNode(xmlNodePtr cur, xmlCatalogEntryType type, } /** + * Examines an XML tree node of a catalog and build + * a Catalog entry from it adding it to its parent. The examination can + * be recursive. + * * @param cur the XML node * @param prefer the PUBLIC vs. SYSTEM current preference value * @param parent the parent Catalog entry * @param cgroup the group which includes this node - * - * Examines an XML tree node of a catalog and build - * a Catalog entry from it adding it to its parent. The examination can - * be recursive. */ static void xmlParseXMLCatalogNode(xmlNodePtr cur, xmlCatalogPrefer prefer, @@ -1247,14 +1238,14 @@ xmlParseXMLCatalogNode(xmlNodePtr cur, xmlCatalogPrefer prefer, } /** + * Examines a list of XML sibling nodes of a catalog and build + * a list of Catalog entry from it adding it to the parent. + * The examination will recurse to examine node subtrees. + * * @param cur the XML node list of siblings * @param prefer the PUBLIC vs. SYSTEM current preference value * @param parent the parent Catalog entry * @param cgroup the group which includes this list - * - * Examines a list of XML sibling nodes of a catalog and build - * a list of Catalog entry from it adding it to the parent. - * The examination will recurse to examine node subtrees. */ static void xmlParseXMLCatalogNodeList(xmlNodePtr cur, xmlCatalogPrefer prefer, @@ -1270,12 +1261,11 @@ xmlParseXMLCatalogNodeList(xmlNodePtr cur, xmlCatalogPrefer prefer, } /** - * @param prefer the PUBLIC vs. SYSTEM current preference value - * @param filename the filename for the catalog - * * Parses the catalog file to extract the XML tree and then analyze the * tree to build a list of Catalog entries corresponding to this catalog * + * @param prefer the PUBLIC vs. SYSTEM current preference value + * @param filename the filename for the catalog * @returns the resulting Catalog entries list */ static xmlCatalogEntryPtr @@ -1339,10 +1329,9 @@ xmlParseXMLCatalogFile(xmlCatalogPrefer prefer, const xmlChar *filename) { } /** - * @param catal an existing but incomplete catalog entry - * * Fetch and parse the subcatalog referenced by an entry * + * @param catal an existing but incomplete catalog entry * @returns 0 in case of success, -1 otherwise */ static int @@ -1423,14 +1412,13 @@ xmlFetchXMLCatalogFile(xmlCatalogEntryPtr catal) { ************************************************************************/ /** + * Add an entry in the XML catalog, it may overwrite existing but + * different entries. + * * @param catal top of an XML catalog * @param type the type of record to add to the catalog * @param orig the system, public or prefix to match (or NULL) * @param replace the replacement value for the match - * - * Add an entry in the XML catalog, it may overwrite existing but - * different entries. - * * @returns 0 if successful, -1 otherwise */ static int @@ -1502,12 +1490,11 @@ xmlAddXMLCatalog(xmlCatalogEntryPtr catal, const xmlChar *type, } /** - * @param catal top of an XML catalog - * @param value the value to remove from the catalog - * * Remove entries in the XML catalog where the value or the URI * is equal to `value` * + * @param catal top of an XML catalog + * @param value the value to remove from the catalog * @returns the number of entries removed if successful, -1 otherwise */ static int @@ -1548,16 +1535,15 @@ xmlDelXMLCatalog(xmlCatalogEntryPtr catal, const xmlChar *value) { } /** - * @param catal a catalog list - * @param pubID the public ID string - * @param sysID the system ID string - * * Do a complete resolution lookup of an External Identifier for a * list of catalog entries. * * Implements (or tries to) 7.1. External Identifier Resolution * from http://www.oasis-open.org/committees/entity/spec-2001-08-06.html * + * @param catal a catalog list + * @param pubID the public ID string + * @param sysID the system ID string * @returns the URI of the resource or NULL if not found */ static xmlChar * @@ -1780,15 +1766,14 @@ xmlCatalogXMLResolve(xmlCatalogEntryPtr catal, const xmlChar *pubID, } /** - * @param catal a catalog list - * @param URI the URI - * * Do a complete resolution lookup of an External Identifier for a * list of catalog entries. * * Implements (or tries to) 7.2.2. URI Resolution * from http://www.oasis-open.org/committees/entity/spec-2001-08-06.html * + * @param catal a catalog list + * @param URI the URI * @returns the URI of the resource or NULL if not found */ static xmlChar * @@ -1921,16 +1906,15 @@ xmlCatalogXMLResolveURI(xmlCatalogEntryPtr catal, const xmlChar *URI) { } /** - * @param catal a catalog list - * @param pubID the public ID string - * @param sysID the system ID string - * * Do a complete resolution lookup of an External Identifier for a * list of catalogs * * Implements (or tries to) 7.1. External Identifier Resolution * from http://www.oasis-open.org/committees/entity/spec-2001-08-06.html * + * @param catal a catalog list + * @param pubID the public ID string + * @param sysID the system ID string * @returns the URI of the resource or NULL if not found */ static xmlChar * @@ -2012,14 +1996,13 @@ xmlCatalogListXMLResolve(xmlCatalogEntryPtr catal, const xmlChar *pubID, } /** - * @param catal a catalog list - * @param URI the URI - * * Do a complete resolution lookup of an URI for a list of catalogs * * Implements (or tries to) 7.2. URI Resolution * from http://www.oasis-open.org/committees/entity/spec-2001-08-06.html * + * @param catal a catalog list + * @param URI the URI * @returns the URI of the resource or NULL if not found */ static xmlChar * @@ -2077,10 +2060,9 @@ xmlCatalogListXMLResolveURI(xmlCatalogEntryPtr catal, const xmlChar *URI) { #define SKIP_BLANKS while (IS_BLANK_CH(*cur)) NEXT; /** - * @param cur the current character - * * Skip a comment in an SGML catalog * + * @param cur the current character * @returns new current character */ static const xmlChar * @@ -2097,11 +2079,10 @@ xmlParseSGMLCatalogComment(const xmlChar *cur) { } /** - * @param cur the current character - * @param id the return location - * * Parse an SGML catalog ID * + * @param cur the current character + * @param id the return location * @returns new current character and store the value in `id` */ static const xmlChar * @@ -2172,11 +2153,10 @@ xmlParseSGMLCatalogPubid(const xmlChar *cur, xmlChar **id) { } /** - * @param cur the current character - * @param name the return location - * * Parse an SGML catalog name * + * @param cur the current character + * @param name the return location * @returns new current character and store the value in `name` */ static const xmlChar * @@ -2209,10 +2189,9 @@ xmlParseSGMLCatalogName(const xmlChar *cur, xmlChar **name) { } /** - * @param name the entry name - * * Get the Catalog entry type for a given SGML Catalog name * + * @param name the entry name * @returns Catalog entry type */ static xmlCatalogEntryType @@ -2244,15 +2223,14 @@ xmlGetSGMLCatalogEntryType(const xmlChar *name) { } /** + * Parse an SGML catalog content and fill up the `catal` hash table with + * the new entries found. + * * @param catal the SGML Catalog * @param value the content of the SGML Catalog serialization * @param file the filepath for the catalog * @param super should this be handled as a Super Catalog in which case * parsing is not recursive - * - * Parse an SGML catalog content and fill up the `catal` hash table with - * the new entries found. - * * @returns 0 in case of success, -1 in case of error. */ static int @@ -2469,11 +2447,10 @@ xmlParseSGMLCatalog(xmlCatalogPtr catal, const xmlChar *value, ************************************************************************/ /** - * @param catal an SGML catalog hash - * @param pubID the public ID string - * * Try to lookup the catalog local reference associated to a public ID * + * @param catal an SGML catalog hash + * @param pubID the public ID string * @returns the local resource if found or NULL otherwise. */ static const xmlChar * @@ -2505,11 +2482,10 @@ xmlCatalogGetSGMLPublic(xmlHashTablePtr catal, const xmlChar *pubID) { } /** - * @param catal an SGML catalog hash - * @param sysID the system ID string - * * Try to lookup the catalog local reference for a system ID * + * @param catal an SGML catalog hash + * @param sysID the system ID string * @returns the local resource if found or NULL otherwise. */ static const xmlChar * @@ -2528,12 +2504,11 @@ xmlCatalogGetSGMLSystem(xmlHashTablePtr catal, const xmlChar *sysID) { } /** + * Do a complete resolution lookup of an External Identifier + * * @param catal the SGML catalog * @param pubID the public ID string * @param sysID the system ID string - * - * Do a complete resolution lookup of an External Identifier - * * @returns the URI of the resource or NULL if not found */ static const xmlChar * @@ -2562,12 +2537,11 @@ xmlCatalogSGMLResolve(xmlCatalogPtr catal, const xmlChar *pubID, ************************************************************************/ /** - * @param filename a file path - * * Load an SGML super catalog. It won't expand CATALOG or DELEGATE * references. This is only needed for manipulating SGML Super Catalogs * like adding and removing CATALOG or DELEGATE entries. * + * @param filename a file path * @returns the catalog parsed or NULL in case of error */ xmlCatalogPtr @@ -2597,13 +2571,12 @@ xmlLoadSGMLSuperCatalog(const char *filename) } /** - * @param filename a file path - * * Load the catalog and build the associated data structures. * This can be either an XML Catalog or an SGML Catalog * It will recurse in SGML CATALOG entries. On the other hand XML * Catalogs are not handled recursively. * + * @param filename a file path * @returns the catalog parsed or NULL in case of error */ xmlCatalogPtr @@ -2652,12 +2625,11 @@ xmlLoadACatalog(const char *filename) } /** - * @param catal a catalog - * @param filename a file path - * * Load the catalog and expand the existing catal structure. * This can be either an XML Catalog or an SGML Catalog * + * @param catal a catalog + * @param filename a file path * @returns 0 in case of success, -1 in case of error */ static int @@ -2699,11 +2671,10 @@ xmlExpandCatalog(xmlCatalogPtr catal, const char *filename) } /** - * @param catal a Catalog - * @param sysID the system ID string - * * Try to lookup the catalog resource for a system ID * + * @param catal a Catalog + * @param sysID the system ID string * @returns the resource if found or NULL otherwise, the value returned * must be freed by the caller. */ @@ -2733,11 +2704,10 @@ xmlACatalogResolveSystem(xmlCatalogPtr catal, const xmlChar *sysID) { } /** - * @param catal a Catalog - * @param pubID the public ID string - * * Try to lookup the catalog local reference associated to a public ID in that catalog * + * @param catal a Catalog + * @param pubID the public ID string * @returns the local resource if found or NULL otherwise, the value returned * must be freed by the caller. */ @@ -2767,12 +2737,11 @@ xmlACatalogResolvePublic(xmlCatalogPtr catal, const xmlChar *pubID) { } /** + * Do a complete resolution lookup of an External Identifier + * * @param catal a Catalog * @param pubID the public ID string * @param sysID the system ID string - * - * Do a complete resolution lookup of an External Identifier - * * @returns the URI of the resource or NULL if not found, it must be freed * by the caller. */ @@ -2813,11 +2782,10 @@ xmlACatalogResolve(xmlCatalogPtr catal, const xmlChar * pubID, } /** - * @param catal a Catalog - * @param URI the URI - * * Do a complete resolution lookup of an URI * + * @param catal a Catalog + * @param URI the URI * @returns the URI of the resource or NULL if not found, it must be freed * by the caller. */ @@ -2848,10 +2816,10 @@ xmlACatalogResolveURI(xmlCatalogPtr catal, const xmlChar *URI) { #ifdef LIBXML_OUTPUT_ENABLED /** + * Dump the given catalog to the given file. + * * @param catal a Catalog * @param out the file. - * - * Dump the given catalog to the given file. */ void xmlACatalogDump(xmlCatalogPtr catal, FILE *out) { @@ -2867,14 +2835,13 @@ xmlACatalogDump(xmlCatalogPtr catal, FILE *out) { #endif /* LIBXML_OUTPUT_ENABLED */ /** + * Add an entry in the catalog, it may overwrite existing but + * different entries. + * * @param catal a Catalog * @param type the type of record to add to the catalog * @param orig the system, public or prefix to match * @param replace the replacement value for the match - * - * Add an entry in the catalog, it may overwrite existing but - * different entries. - * * @returns 0 if successful, -1 otherwise */ int @@ -2908,11 +2875,10 @@ xmlACatalogAdd(xmlCatalogPtr catal, const xmlChar * type, } /** - * @param catal a Catalog - * @param value the value to remove - * * Remove an entry from the catalog * + * @param catal a Catalog + * @param value the value to remove * @returns the number of entries removed if successful, -1 otherwise */ int @@ -2933,10 +2899,9 @@ xmlACatalogRemove(xmlCatalogPtr catal, const xmlChar *value) { } /** - * @param sgml should this create an SGML catalog - * * create a new Catalog. * + * @param sgml should this create an SGML catalog * @returns the xmlCatalogPtr or NULL in case of error */ xmlCatalogPtr @@ -2955,10 +2920,9 @@ xmlNewCatalog(int sgml) { } /** - * @param catal should this create an SGML catalog - * * Check is a catalog is empty * + * @param catal should this create an SGML catalog * @returns 1 if the catalog is empty, 0 if not, amd -1 in case of error. */ int @@ -3064,13 +3028,12 @@ xmlInitializeCatalog(void) { /** - * @param filename a file path - * * Load the catalog and makes its definitions effective for the default * external entity loader. It will recurse in SGML CATALOG entries. * this function is not thread safe, catalog initialization should * preferably be done once at startup * + * @param filename a file path * @returns 0 in case of success -1 in case of error */ int @@ -3102,12 +3065,12 @@ xmlLoadCatalog(const char *filename) } /** - * @param pathss a list of directories separated by a colon or a space. - * * Load the catalogs and makes their definitions effective for the default * external entity loader. * this function is not thread safe, catalog initialization should * preferably be done once at startup + * + * @param pathss a list of directories separated by a colon or a space. */ void xmlLoadCatalogs(const char *pathss) { @@ -3176,10 +3139,9 @@ xmlCleanupCatalogInternal(void) { } /** - * @param sysID the system ID string - * * Try to lookup the catalog resource for a system ID * + * @param sysID the system ID string * @returns the resource if found or NULL otherwise, the value returned * must be freed by the caller. */ @@ -3195,10 +3157,9 @@ xmlCatalogResolveSystem(const xmlChar *sysID) { } /** - * @param pubID the public ID string - * * Try to lookup the catalog reference associated to a public ID * + * @param pubID the public ID string * @returns the resource if found or NULL otherwise, the value returned * must be freed by the caller. */ @@ -3214,11 +3175,10 @@ xmlCatalogResolvePublic(const xmlChar *pubID) { } /** - * @param pubID the public ID string - * @param sysID the system ID string - * * Do a complete resolution lookup of an External Identifier * + * @param pubID the public ID string + * @param sysID the system ID string * @returns the URI of the resource or NULL if not found, it must be freed * by the caller. */ @@ -3234,10 +3194,9 @@ xmlCatalogResolve(const xmlChar *pubID, const xmlChar *sysID) { } /** - * @param URI the URI - * * Do a complete resolution lookup of an URI * + * @param URI the URI * @returns the URI of the resource or NULL if not found, it must be freed * by the caller. */ @@ -3254,9 +3213,9 @@ xmlCatalogResolveURI(const xmlChar *URI) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param out the file. - * * Dump all the global catalog content to the given file. + * + * @param out the file. */ void xmlCatalogDump(FILE *out) { @@ -3271,15 +3230,14 @@ xmlCatalogDump(FILE *out) { #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param type the type of record to add to the catalog - * @param orig the system, public or prefix to match - * @param replace the replacement value for the match - * * Add an entry in the catalog, it may overwrite existing but * different entries. * If called before any other catalog routine, allows to override the * default shared catalog put in place by xmlInitializeCatalog(); * + * @param type the type of record to add to the catalog + * @param orig the system, public or prefix to match + * @param replace the replacement value for the match * @returns 0 if successful, -1 otherwise */ int @@ -3312,10 +3270,9 @@ xmlCatalogAdd(const xmlChar *type, const xmlChar *orig, const xmlChar *replace) } /** - * @param value the value to remove - * * Remove an entry from the catalog * + * @param value the value to remove * @returns the number of entries removed if successful, -1 otherwise */ int @@ -3356,12 +3313,12 @@ xmlCatalogConvert(void) { ************************************************************************/ /** - * @deprecated Use XML_PARSE_NO_SYS_CATALOG and - * XML_PARSE_CATALOG_PI. - * * Used to get the user preference w.r.t. to what catalogs should * be accepted * + * @deprecated Use XML_PARSE_NO_SYS_CATALOG and + * XML_PARSE_CATALOG_PI. + * * @returns the current xmlCatalogAllow value */ xmlCatalogAllow @@ -3370,13 +3327,13 @@ xmlCatalogGetDefaults(void) { } /** - * @param allow what catalogs should be accepted + * Used to set the user preference w.r.t. to what catalogs should + * be accepted * * @deprecated Use XML_PARSE_NO_SYS_CATALOG and * XML_PARSE_CATALOG_PI. * - * Used to set the user preference w.r.t. to what catalogs should - * be accepted + * @param allow what catalogs should be accepted */ void xmlCatalogSetDefaults(xmlCatalogAllow allow) { @@ -3404,14 +3361,13 @@ xmlCatalogSetDefaults(xmlCatalogAllow allow) { } /** - * @param prefer the default preference for delegation - * - * @deprecated This setting is global and not thread-safe. - * * Allows to set the preference between public and system for deletion * in XML Catalog resolution. C.f. section 4.1.1 of the spec * Values accepted are XML_CATA_PREFER_PUBLIC or XML_CATA_PREFER_SYSTEM * + * @deprecated This setting is global and not thread-safe. + * + * @param prefer the default preference for delegation * @returns the previous value of the default preference for delegation */ xmlCatalogPrefer @@ -3440,11 +3396,10 @@ xmlCatalogSetDefaultPrefer(xmlCatalogPrefer prefer) { } /** - * @param level the debug level of catalogs required - * * Used to set the debug level for catalog operation, 0 disable * debugging, 1 enable it * + * @param level the debug level of catalogs required * @returns the previous value of the catalog debugging level */ int @@ -3465,9 +3420,9 @@ xmlCatalogSetDebug(int level) { ************************************************************************/ /** - * @param catalogs a document's list of catalogs - * * Free up the memory associated to the catalog list + * + * @param catalogs a document's list of catalogs */ void xmlCatalogFreeLocal(void *catalogs) { @@ -3480,11 +3435,10 @@ xmlCatalogFreeLocal(void *catalogs) { /** - * @param catalogs a document's list of catalogs - * @param URL the URL to a new local catalog - * * Add the new entry to the catalog list * + * @param catalogs a document's list of catalogs + * @param URL the URL to a new local catalog * @returns the updated list */ void * @@ -3516,13 +3470,12 @@ xmlCatalogAddLocal(void *catalogs, const xmlChar *URL) { } /** - * @param catalogs a document's list of catalogs - * @param pubID the public ID string - * @param sysID the system ID string - * * Do a complete resolution lookup of an External Identifier using a * document's private catalog list * + * @param catalogs a document's list of catalogs + * @param pubID the public ID string + * @param sysID the system ID string * @returns the URI of the resource or NULL if not found, it must be freed * by the caller. */ @@ -3558,12 +3511,11 @@ xmlCatalogLocalResolve(void *catalogs, const xmlChar *pubID, } /** - * @param catalogs a document's list of catalogs - * @param URI the URI - * * Do a complete resolution lookup of an URI using a * document's private catalog list * + * @param catalogs a document's list of catalogs + * @param URI the URI * @returns the URI of the resource or NULL if not found, it must be freed * by the caller. */ @@ -3594,12 +3546,11 @@ xmlCatalogLocalResolveURI(void *catalogs, const xmlChar *URI) { * * ************************************************************************/ /** - * @param sysID the system ID string - * * Try to lookup the catalog reference associated to a system ID * * @deprecated use xmlCatalogResolveSystem() * + * @param sysID the system ID string * @returns the resource if found or NULL otherwise. */ const xmlChar * @@ -3638,12 +3589,11 @@ xmlCatalogGetSystem(const xmlChar *sysID) { } /** - * @param pubID the public ID string - * * Try to lookup the catalog reference associated to a public ID * * @deprecated use xmlCatalogResolvePublic() * + * @param pubID the public ID string * @returns the resource if found or NULL otherwise. */ const xmlChar * diff --git a/chvalid.c b/chvalid.c index 82077c1e..b80cc844 100644 --- a/chvalid.c +++ b/chvalid.c @@ -156,12 +156,11 @@ const xmlChRangeGroup xmlIsIdeographicGroup = /** - * @param val character to be validated - * @param rptr pointer to range to be used to validate - * * Does a binary search of the range table to determine if char * is valid * + * @param val character to be validated + * @param rptr pointer to range to be used to validate * @returns true if character valid, false otherwise */ int @@ -214,11 +213,10 @@ xmlCharInRange (unsigned int val, const xmlChRangeGroup *rptr) { /** - * @param ch character to validate - * * This function is DEPRECATED. * Use xmlIsBaseChar_ch() or xmlIsBaseCharQ() instead * + * @param ch character to validate * @returns true if argument valid, false otherwise */ int @@ -228,11 +226,10 @@ xmlIsBaseChar(unsigned int ch) { /** - * @param ch character to validate - * * This function is DEPRECATED. * Use xmlIsBlank_ch() or xmlIsBlankQ() instead * + * @param ch character to validate * @returns true if argument valid, false otherwise */ int @@ -242,11 +239,10 @@ xmlIsBlank(unsigned int ch) { /** - * @param ch character to validate - * * This function is DEPRECATED. * Use xmlIsChar_ch() or xmlIsCharQ() instead * + * @param ch character to validate * @returns true if argument valid, false otherwise */ int @@ -256,11 +252,10 @@ xmlIsChar(unsigned int ch) { /** - * @param ch character to validate - * * This function is DEPRECATED. * Use xmlIsCombiningQ() instead * + * @param ch character to validate * @returns true if argument valid, false otherwise */ int @@ -270,11 +265,10 @@ xmlIsCombining(unsigned int ch) { /** - * @param ch character to validate - * * This function is DEPRECATED. * Use xmlIsDigit_ch() or xmlIsDigitQ() instead * + * @param ch character to validate * @returns true if argument valid, false otherwise */ int @@ -284,11 +278,10 @@ xmlIsDigit(unsigned int ch) { /** - * @param ch character to validate - * * This function is DEPRECATED. * Use xmlIsExtender_ch() or xmlIsExtenderQ() instead * + * @param ch character to validate * @returns true if argument valid, false otherwise */ int @@ -298,11 +291,10 @@ xmlIsExtender(unsigned int ch) { /** - * @param ch character to validate - * * This function is DEPRECATED. * Use xmlIsIdeographicQ() instead * + * @param ch character to validate * @returns true if argument valid, false otherwise */ int @@ -312,11 +304,10 @@ xmlIsIdeographic(unsigned int ch) { /** - * @param ch character to validate - * * This function is DEPRECATED. * Use xmlIsPubidChar_ch() or xmlIsPubidCharQ() instead * + * @param ch character to validate * @returns true if argument valid, false otherwise */ int diff --git a/debugXML.c b/debugXML.c index 7d63d6f7..94cb62b3 100644 --- a/debugXML.c +++ b/debugXML.c @@ -70,11 +70,10 @@ xmlCtxtDumpCleanCtxt(xmlDebugCtxtPtr ctxt ATTRIBUTE_UNUSED) } /** - * @param node the node - * @param ns the namespace node - * * Check that a given namespace is in scope on a node. * + * @param node the node + * @param ns the namespace node * @returns 1 if in scope, -1 in case of argument error, * -2 if the namespace is not in scope, and -3 if not on * an ancestor node. @@ -138,11 +137,11 @@ xmlCtxtDumpSpaces(xmlDebugCtxtPtr ctxt) } /** + * Handle a debug error. + * * @param ctxt a debug context * @param error the error code * @param msg the error message - * - * Handle a debug error. */ static void xmlDebugErr(xmlDebugCtxtPtr ctxt, int error, const char *msg) @@ -166,11 +165,11 @@ xmlDebugErr3(xmlDebugCtxtPtr ctxt, int error, const char *msg, const char *extra } /** + * Report if a given namespace is is not in scope. + * * @param ctxt the debugging context * @param node the node * @param ns the namespace node - * - * Report if a given namespace is is not in scope. */ static void xmlCtxtNsCheckScope(xmlDebugCtxtPtr ctxt, xmlNodePtr node, xmlNsPtr ns) @@ -199,10 +198,10 @@ xmlCtxtNsCheckScope(xmlDebugCtxtPtr ctxt, xmlNodePtr node, xmlNsPtr ns) } /** + * Do debugging on the string, currently it just checks the UTF-8 content + * * @param ctxt the debug context * @param str the string - * - * Do debugging on the string, currently it just checks the UTF-8 content */ static void xmlCtxtCheckString(xmlDebugCtxtPtr ctxt, const xmlChar * str) @@ -217,11 +216,11 @@ xmlCtxtCheckString(xmlDebugCtxtPtr ctxt, const xmlChar * str) } /** - * @param ctxt the debug context - * @param name the name - * * Do debugging on the name, for example the dictionary status and * conformance to the Name production. + * + * @param ctxt the debug context + * @param name the name */ static void xmlCtxtCheckName(xmlDebugCtxtPtr ctxt, const xmlChar * name) @@ -779,10 +778,10 @@ xmlCtxtDumpEntity(xmlDebugCtxtPtr ctxt, xmlEntityPtr ent) } /** + * Dumps debug information for the attribute + * * @param ctxt the debug context * @param attr the attribute - * - * Dumps debug information for the attribute */ static void xmlCtxtDumpAttr(xmlDebugCtxtPtr ctxt, xmlAttrPtr attr) @@ -815,10 +814,10 @@ xmlCtxtDumpAttr(xmlDebugCtxtPtr ctxt, xmlAttrPtr attr) } /** + * Dumps debug information for the attribute list + * * @param ctxt the debug context * @param attr the attribute list - * - * Dumps debug information for the attribute list */ static void xmlCtxtDumpAttrList(xmlDebugCtxtPtr ctxt, xmlAttrPtr attr) @@ -830,10 +829,10 @@ xmlCtxtDumpAttrList(xmlDebugCtxtPtr ctxt, xmlAttrPtr attr) } /** + * Dumps debug information for the element node, it is not recursive/ + * * @param ctxt the debug context * @param node the node - * - * Dumps debug information for the element node, it is not recursive/ */ static void xmlCtxtDumpOneNode(xmlDebugCtxtPtr ctxt, xmlNodePtr node) @@ -1011,10 +1010,10 @@ xmlCtxtDumpOneNode(xmlDebugCtxtPtr ctxt, xmlNodePtr node) } /** + * Dumps debug information for the element node, it is recursive + * * @param ctxt the debug context * @param node the node - * - * Dumps debug information for the element node, it is recursive */ static void xmlCtxtDumpNode(xmlDebugCtxtPtr ctxt, xmlNodePtr node) @@ -1036,10 +1035,10 @@ xmlCtxtDumpNode(xmlDebugCtxtPtr ctxt, xmlNodePtr node) } /** + * Dumps debug information for the list of element node, it is recursive + * * @param ctxt the debug context * @param node the node list - * - * Dumps debug information for the list of element node, it is recursive */ static void xmlCtxtDumpNodeList(xmlDebugCtxtPtr ctxt, xmlNodePtr node) @@ -1120,10 +1119,10 @@ xmlCtxtDumpDocHead(xmlDebugCtxtPtr ctxt, xmlDocPtr doc) } /** + * Dumps debug information concerning the document, not recursive + * * @param ctxt the debug context * @param doc the document - * - * Dumps debug information concerning the document, not recursive */ static void xmlCtxtDumpDocumentHead(xmlDebugCtxtPtr ctxt, xmlDocPtr doc) @@ -1159,10 +1158,10 @@ xmlCtxtDumpDocumentHead(xmlDebugCtxtPtr ctxt, xmlDocPtr doc) } /** + * Dumps debug information for the document, it's recursive + * * @param ctxt the debug context * @param doc the document - * - * Dumps debug information for the document, it's recursive */ static void xmlCtxtDumpDocument(xmlDebugCtxtPtr ctxt, xmlDocPtr doc) @@ -1229,10 +1228,10 @@ xmlCtxtDumpEntityCallback(void *payload, void *data, } /** + * Dumps debug information for all the entities in use by the document + * * @param ctxt the debug context * @param doc the document - * - * Dumps debug information for all the entities in use by the document */ static void xmlCtxtDumpEntities(xmlDebugCtxtPtr ctxt, xmlDocPtr doc) @@ -1260,10 +1259,10 @@ xmlCtxtDumpEntities(xmlDebugCtxtPtr ctxt, xmlDocPtr doc) } /** + * Dumps debug information for the DTD + * * @param ctxt the debug context * @param dtd the DTD - * - * Dumps debug information for the DTD */ static void xmlCtxtDumpDTD(xmlDebugCtxtPtr ctxt, xmlDtdPtr dtd) @@ -1290,10 +1289,10 @@ xmlCtxtDumpDTD(xmlDebugCtxtPtr ctxt, xmlDtdPtr dtd) ************************************************************************/ /** + * Dumps information about the string, shorten it if necessary + * * @param output the FILE * for the output * @param str the string - * - * Dumps information about the string, shorten it if necessary */ void xmlDebugDumpString(FILE * output, const xmlChar * str) @@ -1319,11 +1318,11 @@ xmlDebugDumpString(FILE * output, const xmlChar * str) } /** + * Dumps debug information for the attribute + * * @param output the FILE * for the output * @param attr the attribute * @param depth the indentation level. - * - * Dumps debug information for the attribute */ void xmlDebugDumpAttr(FILE *output, xmlAttrPtr attr, int depth) { @@ -1339,10 +1338,10 @@ xmlDebugDumpAttr(FILE *output, xmlAttrPtr attr, int depth) { /** + * Dumps debug information for all the entities in use by the document + * * @param output the FILE * for the output * @param doc the document - * - * Dumps debug information for all the entities in use by the document */ void xmlDebugDumpEntities(FILE * output, xmlDocPtr doc) @@ -1357,11 +1356,11 @@ xmlDebugDumpEntities(FILE * output, xmlDocPtr doc) } /** + * Dumps debug information for the attribute list + * * @param output the FILE * for the output * @param attr the attribute list * @param depth the indentation level. - * - * Dumps debug information for the attribute list */ void xmlDebugDumpAttrList(FILE * output, xmlAttrPtr attr, int depth) @@ -1377,11 +1376,11 @@ xmlDebugDumpAttrList(FILE * output, xmlAttrPtr attr, int depth) } /** + * Dumps debug information for the element node, it is not recursive + * * @param output the FILE * for the output * @param node the node * @param depth the indentation level. - * - * Dumps debug information for the element node, it is not recursive */ void xmlDebugDumpOneNode(FILE * output, xmlNodePtr node, int depth) @@ -1397,11 +1396,11 @@ xmlDebugDumpOneNode(FILE * output, xmlNodePtr node, int depth) } /** + * Dumps debug information for the element node, it is recursive + * * @param output the FILE * for the output * @param node the node * @param depth the indentation level. - * - * Dumps debug information for the element node, it is recursive */ void xmlDebugDumpNode(FILE * output, xmlNodePtr node, int depth) @@ -1418,11 +1417,11 @@ xmlDebugDumpNode(FILE * output, xmlNodePtr node, int depth) } /** + * Dumps debug information for the list of element node, it is recursive + * * @param output the FILE * for the output * @param node the node list * @param depth the indentation level. - * - * Dumps debug information for the list of element node, it is recursive */ void xmlDebugDumpNodeList(FILE * output, xmlNodePtr node, int depth) @@ -1439,10 +1438,10 @@ xmlDebugDumpNodeList(FILE * output, xmlNodePtr node, int depth) } /** + * Dumps debug information concerning the document, not recursive + * * @param output the FILE * for the output * @param doc the document - * - * Dumps debug information concerning the document, not recursive */ void xmlDebugDumpDocumentHead(FILE * output, xmlDocPtr doc) @@ -1459,10 +1458,10 @@ xmlDebugDumpDocumentHead(FILE * output, xmlDocPtr doc) } /** + * Dumps debug information for the document, it's recursive + * * @param output the FILE * for the output * @param doc the document - * - * Dumps debug information for the document, it's recursive */ void xmlDebugDumpDocument(FILE * output, xmlDocPtr doc) @@ -1479,10 +1478,10 @@ xmlDebugDumpDocument(FILE * output, xmlDocPtr doc) } /** + * Dumps debug information for the DTD + * * @param output the FILE * for the output * @param dtd the DTD - * - * Dumps debug information for the DTD */ void xmlDebugDumpDTD(FILE * output, xmlDtdPtr dtd) @@ -1505,12 +1504,11 @@ xmlDebugDumpDTD(FILE * output, xmlDtdPtr dtd) ************************************************************************/ /** - * @param output the FILE * for the output - * @param doc the document - * * Check the document for potential content problems, and output * the errors to `output` * + * @param output the FILE * for the output + * @param doc the document * @returns the number of errors found */ int diff --git a/dict.c b/dict.c index 6eb952d9..9daae58c 100644 --- a/dict.c +++ b/dict.c @@ -274,13 +274,12 @@ xmlDictCreate(void) { } /** - * @param sub an existing dictionary - * * Create a new dictionary, inheriting strings from the read-only * dictionary `sub`. On lookup, strings are first searched in the * new dictionary, then in `sub`, and if not found are created in the * new dictionary. * + * @param sub an existing dictionary * @returns the newly created dictionary, or NULL if an error occurred. */ xmlDictPtr @@ -296,10 +295,9 @@ xmlDictCreateSub(xmlDictPtr sub) { } /** - * @param dict the dictionary - * * Increment the reference counter of a dictionary * + * @param dict the dictionary * @returns 0 in case of success and -1 in case of error */ int @@ -312,10 +310,10 @@ xmlDictReference(xmlDictPtr dict) { } /** - * @param dict the dictionary - * * Free the hash `dict` and its contents. The userdata is * deallocated with `f` if provided. + * + * @param dict the dictionary */ void xmlDictFree(xmlDictPtr dict) { @@ -351,11 +349,10 @@ xmlDictFree(xmlDictPtr dict) { } /** - * @param dict the dictionary - * @param str the string - * * check if a string is owned by the dictionary * + * @param dict the dictionary + * @param str the string * @returns 1 if true, 0 if false and -1 in case of error * -1 in case of error */ @@ -377,10 +374,9 @@ xmlDictOwns(xmlDictPtr dict, const xmlChar *str) { } /** - * @param dict the dictionary - * * Query the number of elements installed in the hash `dict`. * + * @param dict the dictionary * @returns the number of elements in the dictionary or * -1 in case of error */ @@ -394,12 +390,11 @@ xmlDictSize(xmlDictPtr dict) { } /** - * @param dict the dictionary - * @param limit the limit in bytes - * * Set a size limit for the dictionary * Added in 2.9.0 * + * @param dict the dictionary + * @param limit the limit in bytes * @returns the previous limit of the dictionary or 0 */ size_t @@ -414,11 +409,10 @@ xmlDictSetLimit(xmlDictPtr dict, size_t limit) { } /** - * @param dict the dictionary - * * Get how much memory is used by a dictionary for strings * Added in 2.9.0 * + * @param dict the dictionary * @returns the amount of strings allocated */ size_t @@ -493,11 +487,10 @@ xmlDictHashQName(unsigned seed, const xmlChar *prefix, const xmlChar *name, } /** - * @param dict dictionary - * @param string C string - * * Compute the hash value of a C string. * + * @param dict dictionary + * @param string C string * @returns the hash value. */ unsigned @@ -509,11 +502,10 @@ xmlDictComputeHash(const xmlDict *dict, const xmlChar *string) { #define HASH_ROL31(x,n) ((x) << (n) | ((x) & 0x7FFFFFFF) >> (31 - (n))) /** - * @param v1 first hash value - * @param v2 second hash value - * * Combine two hash values. * + * @param v1 first hash value + * @param v2 second hash value * @returns the combined hash value. */ ATTRIBUTE_NO_SANITIZE_INTEGER @@ -530,16 +522,16 @@ xmlDictCombineHash(unsigned v1, unsigned v2) { } /** + * Try to find a matching hash table entry. If an entry was found, set + * `found` to 1 and return the entry. Otherwise, set `found` to 0 and return + * the location where a new entry should be inserted. + * * @param dict dict * @param prefix optional QName prefix * @param name string * @param len length of string * @param hashValue valid hash value of string * @param pfound result of search - * - * Try to find a matching hash table entry. If an entry was found, set - * `found` to 1 and return the entry. Otherwise, set `found` to 0 and return - * the location where a new entry should be inserted. */ ATTRIBUTE_NO_SANITIZE_INTEGER static xmlDictEntry * @@ -596,11 +588,10 @@ xmlDictFindEntry(const xmlDict *dict, const xmlChar *prefix, } /** - * @param dict dictionary - * @param size new size of the dictionary - * * Resize the dictionary hash table. * + * @param dict dictionary + * @param size new size of the dictionary * @returns 0 in case of success, -1 if a memory allocation failed. */ static int @@ -662,13 +653,13 @@ done: } /** + * Internal lookup and update function. + * * @param dict dict * @param prefix optional QName prefix * @param name string * @param maybeLen length of string or -1 if unknown * @param update whether the string should be added - * - * Internal lookup and update function. */ ATTRIBUTE_NO_SANITIZE_INTEGER static const xmlDictEntry * @@ -811,12 +802,11 @@ xmlDictLookupInternal(xmlDictPtr dict, const xmlChar *prefix, } /** + * Lookup a string and add it to the dictionary if it wasn't found. + * * @param dict dictionary * @param name string key * @param len length of the key, if -1 it is recomputed - * - * Lookup a string and add it to the dictionary if it wasn't found. - * * @returns the interned copy of the string or NULL if a memory allocation * failed. */ @@ -831,13 +821,12 @@ xmlDictLookup(xmlDictPtr dict, const xmlChar *name, int len) { } /** - * @param dict dictionary - * @param name string key - * @param len length of the key, if -1 it is recomputed - * * Lookup a dictionary entry and add the string to the dictionary if * it wasn't found. * + * @param dict dictionary + * @param name string key + * @param len length of the key, if -1 it is recomputed * @returns the dictionary entry. */ xmlHashedString @@ -858,12 +847,11 @@ xmlDictLookupHashed(xmlDictPtr dict, const xmlChar *name, int len) { } /** + * Check if a string exists in the dictionary. + * * @param dict the dictionary * @param name the name of the userdata * @param len the length of the name, if -1 it is recomputed - * - * Check if a string exists in the dictionary. - * * @returns the internal copy of the name or NULL if not found. */ const xmlChar * @@ -877,13 +865,12 @@ xmlDictExists(xmlDictPtr dict, const xmlChar *name, int len) { } /** - * @param dict the dictionary - * @param prefix the prefix - * @param name the name - * * Lookup the QName `prefix:name` and add it to the dictionary if * it wasn't found. * + * @param dict the dictionary + * @param prefix the prefix + * @param name the name * @returns the interned copy of the string or NULL if a memory allocation * failed. */ diff --git a/encoding.c b/encoding.c index f87e1d53..cae07c06 100644 --- a/encoding.c +++ b/encoding.c @@ -256,13 +256,12 @@ xmlCharEncUconv(const char *name, xmlCharEncFlags flags, ************************************************************************/ /** - * @param in a pointer to the first bytes of the XML entity, must be at least - * 2 bytes long (at least 4 if encoding is UTF4 variant). - * @param len pointer to the length of the buffer - * * Guess the encoding of the entity using the first bytes of the entity content * according to the non-normative appendix F of the XML-1.0 recommendation. * + * @param in a pointer to the first bytes of the XML entity, must be at least + * 2 bytes long (at least 4 if encoding is UTF4 variant). + * @param len pointer to the length of the buffer * @returns a xmlCharEncoding value. */ xmlCharEncoding @@ -315,10 +314,11 @@ xmlDetectCharEncoding(const unsigned char* in, int len) } /** + * Unregisters all aliases. + * * @deprecated This function modifies global state and is not * thread-safe. See xmlCtxtSetCharEncConvImpl() for an alternative. * - * Unregisters all aliases. */ void xmlCleanupEncodingAliases(void) { @@ -340,12 +340,11 @@ xmlCleanupEncodingAliases(void) { } /** - * @param alias the alias name as parsed, in UTF-8 format (ASCII actually) + * Lookup an encoding name for the given alias. * * @deprecated This function is not thread-safe. * - * Lookup an encoding name for the given alias. - * + * @param alias the alias name as parsed, in UTF-8 format (ASCII actually) * @returns NULL if not found, otherwise the original name. */ const char * @@ -377,15 +376,14 @@ xmlGetEncodingAlias(const char *alias) { } /** - * @param name the encoding name as parsed, in UTF-8 format (ASCII actually) - * @param alias the alias name as parsed, in UTF-8 format (ASCII actually) + * Registers an alias `alias` for an encoding named `name`. Existing + * aliases will be overwritten. * * @deprecated This function modifies global state and is not * thread-safe. See xmlCtxtSetCharEncConvImpl() for an alternative. * - * Registers an alias `alias` for an encoding named `name`. Existing - * aliases will be overwritten. - * + * @param name the encoding name as parsed, in UTF-8 format (ASCII actually) + * @param alias the alias name as parsed, in UTF-8 format (ASCII actually) * @returns 0 in case of success, -1 in case of error. */ int @@ -452,13 +450,12 @@ xmlAddEncodingAlias(const char *name, const char *alias) { } /** - * @param alias the alias name as parsed, in UTF-8 format (ASCII actually) + * Unregisters an encoding alias. * * @deprecated This function modifies global state and is not * thread-safe. See xmlCtxtSetCharEncConvImpl() for an alternative. * - * Unregisters an encoding alias. - * + * @param alias the alias name as parsed, in UTF-8 format (ASCII actually) * @returns 0 in case of success, -1 in case of error. */ int @@ -512,12 +509,11 @@ xmlParseCharEncodingInternal(const char *name) } /** - * @param name the encoding name as parsed, in UTF-8 format (ASCII actually) - * * Compare the string to the encoding schemes already known. Note * that the comparison is case insensitive accordingly to the section * [XML] 4.3.3 Character Encoding in Entities. * + * @param name the encoding name as parsed, in UTF-8 format (ASCII actually) * @returns one of the xmlCharEncoding values or XML_CHAR_ENCODING_NONE * if not recognized. */ @@ -534,12 +530,11 @@ xmlParseCharEncoding(const char *name) } /** - * @param enc the encoding - * * The "canonical" name for XML encoding. * C.f. http://www.w3.org/TR/REC-xml#charencoding * Section 4.3.3 Character Encoding in Entities * + * @param enc the encoding * @returns the canonical name for the given encoding. */ const char* @@ -570,15 +565,14 @@ xmlGetCharEncodingName(xmlCharEncoding enc) { ************************************************************************/ /** - * @param name the encoding name, in UTF-8 format (ASCII actually) - * @param input the xmlCharEncodingInputFunc to read that encoding - * @param output the xmlCharEncodingOutputFunc to write that encoding + * Create and registers an xmlCharEncodingHandler. * * @deprecated This function modifies global state and is not * thread-safe. See xmlCtxtSetCharEncConvImpl() for an alternative. * - * Create and registers an xmlCharEncodingHandler. - * + * @param name the encoding name, in UTF-8 format (ASCII actually) + * @param input the xmlCharEncodingInputFunc to read that encoding + * @param output the xmlCharEncodingOutputFunc to write that encoding * @returns the xmlCharEncodingHandlerPtr created (or NULL in case of error). */ xmlCharEncodingHandlerPtr @@ -635,6 +629,8 @@ xmlNewCharEncodingHandler(const char *name, } /** + * Create a custom xmlCharEncodingHandler. + * * @param name the encoding name * @param input input callback which converts to UTF-8 * @param output output callback which converts from UTF-8 @@ -642,9 +638,6 @@ xmlNewCharEncodingHandler(const char *name, * @param inputCtxt context for input callback * @param outputCtxt context for output callback * @param out pointer to resulting handler - * - * Create a custom xmlCharEncodingHandler. - * * @returns an xmlParserErrors code. */ xmlParserErrors @@ -712,13 +705,14 @@ xmlInitEncodingInternal(void) { } /** + * Cleanup the memory allocated for the char encoding support, it + * unregisters all the encoding handlers and the aliases. + * * @deprecated This function will be made private. Call xmlCleanupParser() * to free global state but see the warnings there. xmlCleanupParser() * should be only called once at program exit. In most cases, you don't * have call cleanup functions at all. * - * Cleanup the memory allocated for the char encoding support, it - * unregisters all the encoding handlers and the aliases. */ void xmlCleanupCharEncodingHandlers(void) { @@ -743,12 +737,12 @@ xmlCleanupCharEncodingHandlers(void) { } /** - * @param handler the xmlCharEncodingHandlerPtr handler block + * Register the char encoding handler. * * @deprecated This function modifies global state and is not * thread-safe. See xmlCtxtSetCharEncConvImpl() for an alternative. * - * Register the char encoding handler. + * @param handler the xmlCharEncodingHandlerPtr handler block */ void xmlRegisterCharEncodingHandler(xmlCharEncodingHandlerPtr handler) { @@ -776,15 +770,14 @@ free_handler: } /** + * Search the non-default handlers for an exact match. + * * @param norig name of the char encoding * @param name potentially aliased name of the encoding * @param flags bit mask of flags * @param impl a conversion implementation (optional) * @param implCtxt user data for conversion implementation (optional) * @param out pointer to resulting handler - * - * Search the non-default handlers for an exact match. - * * @returns an xmlParserErrors error code. */ static xmlParserErrors @@ -846,9 +839,6 @@ xmlFindExtraHandler(const char *norig, const char *name, xmlCharEncFlags flags, } /** - * @param enc an xmlCharEncoding value. - * @param out pointer to result - * * Find or create a handler matching the encoding. The following * converters are looked up in order: * @@ -864,6 +854,8 @@ xmlFindExtraHandler(const char *norig, const char *name, xmlCharEncFlags flags, * * @since 2.13.0 * + * @param enc an xmlCharEncoding value. + * @param out pointer to result * @returns XML_ERR_OK, XML_ERR_UNSUPPORTED_ENCODING or another * xmlParserErrors error code. */ @@ -904,11 +896,10 @@ xmlLookupCharEncodingHandler(xmlCharEncoding enc, } /** - * @param enc an xmlCharEncoding value. - * * @deprecated Use xmlLookupCharEncodingHandler() which has better error * reporting. * + * @param enc an xmlCharEncoding value. * @returns the handler or NULL if no handler was found or an error * occurred. */ @@ -921,12 +912,6 @@ xmlGetCharEncodingHandler(xmlCharEncoding enc) { } /** - * @param name a string describing the char encoding. - * @param flags bit mask of flags - * @param impl a conversion implementation (optional) - * @param implCtxt user data for conversion implementation (optional) - * @param out pointer to result - * * Find or create a handler matching the encoding. The following * converters are looked up in order: * @@ -945,6 +930,11 @@ xmlGetCharEncodingHandler(xmlCharEncoding enc) { * * @since 2.14.0 * + * @param name a string describing the char encoding. + * @param flags bit mask of flags + * @param impl a conversion implementation (optional) + * @param implCtxt user data for conversion implementation (optional) + * @param out pointer to result * @returns XML_ERR_OK, XML_ERR_UNSUPPORTED_ENCODING or another * xmlParserErrors error code. */ @@ -987,10 +977,6 @@ xmlCreateCharEncodingHandler(const char *name, xmlCharEncFlags flags, } /** - * @param name a string describing the char encoding. - * @param output boolean, use handler for output - * @param out pointer to result - * * Find or create a handler matching the encoding. The following * converters are looked up in order: * @@ -1006,6 +992,9 @@ xmlCreateCharEncodingHandler(const char *name, xmlCharEncFlags flags, * * @since 2.13.0 * + * @param name a string describing the char encoding. + * @param output boolean, use handler for output + * @param out pointer to result * @returns XML_ERR_OK, XML_ERR_UNSUPPORTED_ENCODING or another * xmlParserErrors error code. */ @@ -1018,14 +1007,13 @@ xmlOpenCharEncodingHandler(const char *name, int output, } /** - * @param name a string describing the char encoding. + * If the encoding is UTF-8, this will return a no-op handler that + * shouldn't be used. * * @deprecated Use xmlOpenCharEncodingHandler() which has better error * reporting. * - * If the encoding is UTF-8, this will return a no-op handler that - * shouldn't be used. - * + * @param name a string describing the char encoding. * @returns the handler or NULL if no handler was found or an error * occurred. */ @@ -1063,16 +1051,15 @@ typedef struct { } xmlIconvCtxt; /** + * The value of `inlen` after return is the number of bytes consumed. + * The value of `outlen` after return is the number of bytes produced. + * * @param vctxt conversion context * @param out a pointer to an array of bytes to store the result * @param outlen the length of `out` * @param in a pointer to an array of input bytes * @param inlen the length of `in` * @param flush end of input - * - * The value of `inlen` after return is the number of bytes consumed. - * The value of `outlen` after return is the number of bytes produced. - * * @returns an xmlCharEncError code. */ static xmlCharEncError @@ -1295,16 +1282,15 @@ struct _uconv_t { }; /** + * The value of `inlen` after return is the number of bytes consumed. + * The value of `outlen` after return is the number of bytes produced. + * * @param vctxt conversion context * @param out a pointer to an array of bytes to store the result * @param outlen the length of `out` * @param in a pointer to an array of input bytes * @param inlen the length of `in` * @param flush end of input - * - * The value of `inlen` after return is the number of bytes consumed. - * The value of `outlen` after return is the number of bytes produced. - * * @returns an xmlCharEncError code. */ static xmlCharEncError @@ -1488,9 +1474,9 @@ error: ************************************************************************/ /** - * @param code xmlCharEncError code - * * Convert xmlCharEncError to xmlParserErrors code. + * + * @param code xmlCharEncError code */ static xmlParserErrors xmlEncConvertError(xmlCharEncError code) { @@ -1515,16 +1501,15 @@ xmlEncConvertError(xmlCharEncError code) { } /** + * The value of `inlen` after return is the number of bytes consumed. + * The value of `outlen` after return is the number of bytes produced. + * * @param handler encoding handler * @param out a pointer to an array of bytes to store the result * @param outlen the length of `out` * @param in a pointer to an array of input bytes * @param inlen the length of `in` * @param flush end of input - * - * The value of `inlen` after return is the number of bytes consumed. - * The value of `outlen` after return is the number of bytes produced. - * * @returns an xmlCharEncError code. */ xmlCharEncError @@ -1570,15 +1555,14 @@ xmlEncInputChunk(xmlCharEncodingHandler *handler, unsigned char *out, } /** + * The value of `inlen` after return is the number of bytes consumed. + * The value of `outlen` after return is the number of bytes produced. + * * @param handler encoding handler * @param out a pointer to an array of bytes to store the result * @param outlen the length of `out` * @param in a pointer to an array of input bytes * @param inlen the length of `in` - * - * The value of `inlen` after return is the number of bytes consumed. - * The value of `outlen` after return is the number of bytes produced. - * * @returns an xmlCharEncError code. */ static xmlCharEncError @@ -1615,12 +1599,11 @@ xmlEncOutputChunk(xmlCharEncodingHandler *handler, unsigned char *out, } /** + * DEPERECATED: Don't use. + * * @param handler encoding handler * @param out an xmlBuffer for the output. * @param in an xmlBuffer for the input - * - * DEPERECATED: Don't use. - * * @returns the number of bytes written or an xmlCharEncError code. */ int @@ -1630,15 +1613,14 @@ xmlCharEncFirstLine(xmlCharEncodingHandler *handler, xmlBufferPtr out, } /** - * @param input a parser input buffer - * @param sizeOut pointer to output size - * @param flush end of input - * * Generic front-end for input encoding conversion. * * `sizeOut` should be set to the maximum output size (or SIZE_MAX). * After return, it is set to the number of bytes written. * + * @param input a parser input buffer + * @param sizeOut pointer to output size + * @param flush end of input * @returns an xmlCharEncError code. */ xmlCharEncError @@ -1733,12 +1715,11 @@ xmlCharEncInput(xmlParserInputBufferPtr input, size_t *sizeOut, int flush) } /** + * Generic front-end for input encoding conversion. + * * @param handler encoding handler * @param out an xmlBuffer for the output. * @param in an xmlBuffer for the input - * - * Generic front-end for input encoding conversion. - * * @returns the number of bytes written or an xmlCharEncError code. */ int @@ -1775,9 +1756,6 @@ xmlCharEncInFunc(xmlCharEncodingHandler * handler, xmlBufferPtr out, #ifdef LIBXML_OUTPUT_ENABLED /** - * @param output a parser output buffer - * @param init is this an initialization call without data - * * Generic front-end for output encoding conversion. * * A first call with `init` set to 1 has to be made to write a BOM. @@ -1786,6 +1764,8 @@ xmlCharEncInFunc(xmlCharEncodingHandler * handler, xmlBufferPtr out, * encoding will be automatically replaced with a numeric character * reference. * + * @param output a parser output buffer + * @param init is this an initialization call without data * @returns the number of bytes written or an xmlCharEncError code. */ int @@ -1898,10 +1878,6 @@ error: #endif /** - * @param handler encoding handler - * @param out an xmlBuffer for the output. - * @param in an xmlBuffer for the input - * * Generic front-end for output encoding conversion. * * A first call with `in` set to NULL has to be made to write a BOM. @@ -1910,6 +1886,9 @@ error: * encoding will be automatically replaced with a numeric character * reference. * + * @param handler encoding handler + * @param out an xmlBuffer for the output. + * @param in an xmlBuffer for the input * @returns the number of bytes written or an xmlCharEncError code. */ int @@ -1998,11 +1977,10 @@ retry: } /** - * @param handler encoding handler - * * Releases an xmlCharEncodingHandler. Must be called after * a handler is no longer in use. * + * @param handler encoding handler * @returns 0. */ int @@ -2023,10 +2001,6 @@ xmlCharEncCloseFunc(xmlCharEncodingHandler *handler) { } /** - * @param ctxt an XML parser context - * - * @deprecated Don't use. - * * This function provides the current index of the parser relative * to the start of the current entity. This function is computed in * bytes from the beginning starting at zero and finishing at the @@ -2034,6 +2008,9 @@ xmlCharEncCloseFunc(xmlCharEncodingHandler *handler) { * of constant cost if the input is UTF-8 but can be costly if run * on non-UTF-8 input. * + * @deprecated Don't use. + * + * @param ctxt an XML parser context * @returns the index in bytes from the beginning of the entity or -1 * in case the index could not be computed. */ @@ -2177,17 +2154,16 @@ done: } /** - * @param out a pointer to an array of bytes to store the result - * @param outlen the length of `out` - * @param in a pointer to an array of ISO Latin 1 chars - * @param inlen the length of `in` - * * Take a block of ISO Latin 1 chars in and try to convert it to an UTF-8 * block of chars out. * * The value of `inlen` after return is the number of bytes consumed. * The value of `outlen` after return is the number of bytes produced. * + * @param out a pointer to an array of bytes to store the result + * @param outlen the length of `out` + * @param in a pointer to an array of ISO Latin 1 chars + * @param inlen the length of `in` * @returns the number of bytes written or an xmlCharEncError code. */ int @@ -2281,17 +2257,16 @@ done: } /** - * @param out a pointer to an array of bytes to store the result - * @param outlen the length of `out` - * @param in a pointer to an array of UTF-8 chars - * @param inlen the length of `in` - * * Take a block of UTF-8 chars in and try to convert it to an ISO Latin 1 * block of chars out. * * The value of `inlen` after return is the number of bytes consumed. * The value of `outlen` after return is the number of bytes produced. * + * @param out a pointer to an array of bytes to store the result + * @param outlen the length of `out` + * @param in a pointer to an array of UTF-8 chars + * @param inlen the length of `in` * @returns the number of bytes written or an xmlCharEncError code. */ int diff --git a/entities.c b/entities.c index e34a670f..d8be0f44 100644 --- a/entities.c +++ b/entities.c @@ -74,9 +74,9 @@ static xmlEntity xmlEntityApos = { }; /** - * @param entity an entity - * * Frees the entity. + * + * @param entity an entity */ void xmlFreeEntity(xmlEntityPtr entity) @@ -166,6 +166,10 @@ error: } /** + * Register a new entity for this document. + * + * @since 2.13.0 + * * @param doc the document * @param extSubset add to the external or internal subset * @param name the entity name @@ -174,11 +178,6 @@ error: * @param SystemID the entity system ID (optional) * @param content the entity content * @param out pointer to resulting entity (optional) - * - * Register a new entity for this document. - * - * @since 2.13.0 - * * @returns an xmlParserErrors error code. */ int @@ -296,10 +295,9 @@ xmlAddEntity(xmlDocPtr doc, int extSubset, const xmlChar *name, int type, } /** - * @param name the entity name - * * Look up a predefined entity. * + * @param name the entity name * @returns the entity, or NULL if not found. */ xmlEntityPtr @@ -331,17 +329,16 @@ xmlGetPredefinedEntity(const xmlChar *name) { } /** + * Add a new entity to the document's external subset. + * + * xmlAddEntity() offers better error handling. + * * @param doc the document * @param name the entity name * @param type an xmlEntityType value * @param ExternalID the entity external ID (optional) * @param SystemID the entity system ID (optional) * @param content the entity content - * - * Add a new entity to the document's external subset. - * - * xmlAddEntity() offers better error handling. - * * @returns a pointer to the entity or NULL in case of error */ xmlEntityPtr @@ -355,17 +352,16 @@ xmlAddDtdEntity(xmlDocPtr doc, const xmlChar *name, int type, } /** + * Add a new entity to the document's internal subset. + * + * xmlAddEntity() offers better error handling. + * * @param doc the document * @param name the entity name * @param type an xmlEntityType value * @param ExternalID the entity external ID (optional) * @param SystemID the entity system ID (optional) * @param content the entity content - * - * Add a new entity to the document's internal subset. - * - * xmlAddEntity() offers better error handling. - * * @returns a pointer to the entity or NULL in case of error */ xmlEntityPtr @@ -379,13 +375,6 @@ xmlAddDocEntity(xmlDocPtr doc, const xmlChar *name, int type, } /** - * @param doc the document (optional) - * @param name the entity name - * @param type an xmlEntityType value - * @param ExternalID the entity external ID (optional) - * @param SystemID the entity system ID (optional) - * @param content the entity content - * * Create a new entity. * * Like xmlAddDocEntity(), but if `doc` is NULL or has no internal @@ -393,6 +382,12 @@ xmlAddDocEntity(xmlDocPtr doc, const xmlChar *name, int type, * the responsibility of the caller to link it to the document later * or free it when not needed anymore. * + * @param doc the document (optional) + * @param name the entity name + * @param type an xmlEntityType value + * @param ExternalID the entity external ID (optional) + * @param SystemID the entity system ID (optional) + * @param content the entity content * @returns a pointer to the entity or NULL in case of error */ xmlEntityPtr @@ -408,11 +403,10 @@ xmlNewEntity(xmlDocPtr doc, const xmlChar *name, int type, } /** - * @param table an entity table - * @param name the entity name - * * Look up an entity in a table. * + * @param table an entity table + * @param name the entity name * @returns a pointer to the entity or NULL if not found. */ static xmlEntityPtr @@ -421,12 +415,11 @@ xmlGetEntityFromTable(xmlEntitiesTablePtr table, const xmlChar *name) { } /** - * @param doc the document - * @param name the entity name - * * Look up a paramater entity in the internal and external subset * of `doc`. * + * @param doc the document + * @param name the entity name * @returns a pointer to the entity or NULL if not found. */ xmlEntityPtr @@ -450,11 +443,10 @@ xmlGetParameterEntity(xmlDocPtr doc, const xmlChar *name) { } /** - * @param doc the document - * @param name the entity name - * * Look up a general entity in the external subset of `doc`. * + * @param doc the document + * @param name the entity name * @returns a pointer to the entity or NULL if not found. */ xmlEntityPtr @@ -471,12 +463,11 @@ xmlGetDtdEntity(xmlDocPtr doc, const xmlChar *name) { } /** - * @param doc the document referencing the entity - * @param name the entity name - * * Look up a general entity in the internal and external subset * of `doc`. Also checks for predefined entities. * + * @param doc the document referencing the entity + * @param name the entity name * @returns a pointer to the entity or NULL if not found. */ xmlEntityPtr @@ -769,12 +760,11 @@ xmlEscapeText(const xmlChar *text, int flags) { } /** + * See xmlEncodeEntitiesReentrant(). Allows extra flags. + * * @param doc the document containing the string (optional) * @param input A string to convert to XML. * @param flags XML_ESCAPE flags - * - * See xmlEncodeEntitiesReentrant(). Allows extra flags. - * * @returns a newly allocated string with substitutions. */ xmlChar * @@ -792,9 +782,6 @@ xmlEncodeEntitiesInternal(xmlDocPtr doc, const xmlChar *input, } /** - * @param doc the document containing the string (optional) - * @param input A string to convert to XML. - * * Replace special characters with predefined entities or numeric * character references. * @@ -809,6 +796,8 @@ xmlEncodeEntitiesInternal(xmlDocPtr doc, const xmlChar *input, * Silently removes some invalid characters like ASCII control * codes. * + * @param doc the document containing the string (optional) + * @param input A string to convert to XML. * @returns a newly allocated string with substitutions. */ xmlChar * @@ -817,15 +806,14 @@ xmlEncodeEntitiesReentrant(xmlDocPtr doc, const xmlChar *input) { } /** - * @param doc unused - * @param input A string to convert to XML. - * * Replace special characters with predefined entities or numeric * character references. * * Replaces `<`, `>`, `&` and `"` with predefined entities. Carriage * return is replaced with ` `. * + * @param doc unused + * @param input A string to convert to XML. * @returns a newly allocated string with substitutions. */ xmlChar * @@ -848,10 +836,10 @@ xmlCreateEntitiesTable(void) { } /** + * Deallocate the memory used by an entities in the hash table. + * * @param entity An entity * @param name its name - * - * Deallocate the memory used by an entities in the hash table. */ static void xmlFreeEntityWrapper(void *entity, const xmlChar *name ATTRIBUTE_UNUSED) { @@ -860,9 +848,9 @@ xmlFreeEntityWrapper(void *entity, const xmlChar *name ATTRIBUTE_UNUSED) { } /** - * @param table An entity table - * * Deallocate the memory used by an entities hash table. + * + * @param table An entity table */ void xmlFreeEntitiesTable(xmlEntitiesTablePtr table) { @@ -870,11 +858,10 @@ xmlFreeEntitiesTable(xmlEntitiesTablePtr table) { } /** - * @param payload An entity - * @param name unused - * * Build a copy of an entity * + * @param payload An entity + * @param name unused * @returns the new xmlEntitiesPtr or NULL in case of error. */ static void * @@ -927,10 +914,9 @@ error: } /** - * @param table An entity table - * * Build a copy of an entity table. * + * @param table An entity table * @returns the new xmlEntitiesTablePtr or NULL in case of error. */ xmlEntitiesTablePtr @@ -941,11 +927,11 @@ xmlCopyEntitiesTable(xmlEntitiesTablePtr table) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param buf An XML buffer. - * @param ent An entity table - * * This will dump the content of the entity table as an XML DTD * definition. + * + * @param buf An XML buffer. + * @param ent An entity table */ void xmlDumpEntityDecl(xmlBufferPtr buf, xmlEntityPtr ent) { @@ -961,12 +947,12 @@ xmlDumpEntityDecl(xmlBufferPtr buf, xmlEntityPtr ent) { } /** + * When using the hash table scan function, arguments need to be + * reversed. + * * @param ent an entity table * @param save a save context * @param name unused - * - * When using the hash table scan function, arguments need to be - * reversed. */ static void xmlDumpEntityDeclScan(void *ent, void *save, @@ -975,11 +961,11 @@ xmlDumpEntityDeclScan(void *ent, void *save, } /** - * @param buf An XML buffer. - * @param table An entity table - * * This will dump the content of the entity table as an XML DTD * definition. + * + * @param buf An XML buffer. + * @param table An entity table */ void xmlDumpEntitiesTable(xmlBufferPtr buf, xmlEntitiesTablePtr table) { diff --git a/error.c b/error.c index 0ab2febc..8fc80ae2 100644 --- a/error.c +++ b/error.c @@ -21,9 +21,6 @@ #include "private/string.h" /** - * @param level error level - * @param code error code - * * This currently comprises * * - OOM errors @@ -32,6 +29,8 @@ * - I/O errors * - unexpected errors from external libraries * + * @param level error level + * @param code error code * @returns true if an error is catastrophic. */ int @@ -222,11 +221,11 @@ xmlVUpdateError(xmlError *err, ************************************************************************/ /** + * Default handler for out-of-context error messages. + * * @param ctx user data (unused) * @param msg printf-like format string * @param ... arguments to format - * - * Default handler for out-of-context error messages. */ void xmlGenericErrorDefaultFunc(void *ctx ATTRIBUTE_UNUSED, const char *msg, ...) { @@ -241,16 +240,13 @@ xmlGenericErrorDefaultFunc(void *ctx ATTRIBUTE_UNUSED, const char *msg, ...) { } /** - * @param ctx the new error handling context - * @param handler the new handler function - * - * @deprecated See xmlSetStructuredErrorFunc() for alternatives. - * * Set the thread-local "generic" handler and context for error * messages. The generic error handler will only receive fragments * of error messages which should be concatenated or printed to a * stream. * + * @deprecated See xmlSetStructuredErrorFunc() for alternatives. + * * If handler is NULL, use the built-in default handler which prints * to stderr. * @@ -262,6 +258,8 @@ xmlGenericErrorDefaultFunc(void *ctx ATTRIBUTE_UNUSED, const char *msg, ...) { * * For multi-threaded applications, this must be set separately for * each thread. + * @param ctx the new error handling context + * @param handler the new handler function */ void xmlSetGenericErrorFunc(void *ctx, xmlGenericErrorFunc handler) { @@ -273,13 +271,10 @@ xmlSetGenericErrorFunc(void *ctx, xmlGenericErrorFunc handler) { } /** - * @param ctx the new error handling context - * @param handler the new handler function + * It's recommended to use the per-context error handlers instead: * * @deprecated Use a per-context error handler. * - * It's recommended to use the per-context error handlers instead: - * * - xmlCtxtSetErrorHandler() (since 2.13.0) * - xmlTextReaderSetStructuredErrorHandler() * - xmlXPathSetErrorHandler() (since 2.13.0) @@ -303,6 +298,8 @@ xmlSetGenericErrorFunc(void *ctx, xmlGenericErrorFunc handler) { * * For multi-threaded applications, this must be set separately for * each thread. + * @param ctx the new error handling context + * @param handler the new handler function */ void xmlSetStructuredErrorFunc(void *ctx, xmlStructuredErrorFunc handler) { @@ -317,12 +314,12 @@ xmlSetStructuredErrorFunc(void *ctx, xmlStructuredErrorFunc handler) { ************************************************************************/ /** - * @param input an xmlParserInputPtr input + * Displays the associated file and line information for the + * current input. * * @deprecated Use xmlFormatError(). * - * Displays the associated file and line information for the - * current input. + * @param input an xmlParserInputPtr input */ void @@ -339,12 +336,12 @@ xmlParserPrintFileInfo(xmlParserInputPtr input) { } /** + * Displays current context within the input content for + * error reporting. + * * @param input an xmlParserInputPtr input * @param channel output callback * @param data user data for output callback - * - * Displays current context within the input content for - * error reporting. */ static void @@ -412,12 +409,12 @@ xmlParserPrintFileContextInternal(xmlParserInputPtr input , } /** - * @param input an xmlParserInputPtr input + * Displays current context within the input content for + * error reporting. * * @deprecated Use xmlFormatError(). * - * Displays current context within the input content for - * error reporting. + * @param input an xmlParserInputPtr input */ void xmlParserPrintFileContext(xmlParserInputPtr input) { @@ -426,16 +423,15 @@ xmlParserPrintFileContext(xmlParserInputPtr input) { } /** - * @param err the error - * @param channel callback - * @param data user data for callback - * * Report a formatted error to a printf-like callback. * * This can result in a verbose multi-line report including additional * information from the parser context. * * @since 2.13.0 + * @param err the error + * @param channel callback + * @param data user data for callback */ void xmlFormatError(const xmlError *err, xmlGenericErrorFunc channel, void *data) @@ -643,17 +639,16 @@ xmlFormatError(const xmlError *err, xmlGenericErrorFunc channel, void *data) } /** - * @param schannel the structured callback channel - * @param channel the old callback channel - * @param data the callback data - * @param domain the domain for the error - * @param error optional error struct to be filled - * * Update the global and optional error structure, then forward the * error to an error handler. * * This function doesn't make memory allocations which are likely * to fail after an OOM error. + * @param schannel the structured callback channel + * @param channel the old callback channel + * @param data the callback data + * @param domain the domain for the error + * @param error optional error struct to be filled */ void xmlRaiseMemoryError(xmlStructuredErrorFunc schannel, xmlGenericErrorFunc channel, @@ -683,6 +678,10 @@ xmlRaiseMemoryError(xmlStructuredErrorFunc schannel, xmlGenericErrorFunc channel } /** + * Update the appropriate global or contextual error structure, + * then forward the error message down the parser or generic + * error callback handler + * * @param schannel the structured callback channel * @param channel the old callback channel * @param data the callback data @@ -700,11 +699,6 @@ xmlRaiseMemoryError(xmlStructuredErrorFunc schannel, xmlGenericErrorFunc channel * @param col column number of the error or 0 if N/A * @param msg the message to display/transmit * @param ap extra parameters for the message display - * - * Update the appropriate global or contextual error structure, - * then forward the error message down the parser or generic - * error callback handler - * * @returns 0 on success, -1 if a memory allocation failed. */ int @@ -767,6 +761,10 @@ xmlVRaiseError(xmlStructuredErrorFunc schannel, } /** + * Update the appropriate global or contextual error structure, + * then forward the error message down the parser or generic + * error callback handler + * * @param schannel the structured callback channel * @param channel the old callback channel * @param data the callback data @@ -784,11 +782,6 @@ xmlVRaiseError(xmlStructuredErrorFunc schannel, * @param col column number of the error or 0 if N/A * @param msg printf-like format string * @param ... arguments to format - * - * Update the appropriate global or contextual error structure, - * then forward the error message down the parser or generic - * error callback handler - * * @returns 0 on success, -1 if a memory allocation failed. */ int @@ -848,18 +841,17 @@ xmlVFormatLegacyError(void *ctx, const char *level, } /** - * @param ctx an XML parser context - * @param msg printf-like format string - * @param ... arguments to format - * - * @deprecated Do not call directly. - * * This is the default SAX error handler, but it will never be * called. If it isn't replaced by the user, errors will be * handled by xmlFormatError(). * + * @deprecated Do not call directly. + * * Format an error message with additional detail from the * parser context and print to generic error handler. + * @param ctx an XML parser context + * @param msg printf-like format string + * @param ... arguments to format */ void xmlParserError(void *ctx, const char *msg ATTRIBUTE_UNUSED, ...) @@ -872,18 +864,17 @@ xmlParserError(void *ctx, const char *msg ATTRIBUTE_UNUSED, ...) } /** - * @param ctx an XML parser context - * @param msg printf-like format string - * @param ... arguments to format - * - * @deprecated Do not call directly. - * * This is the default SAX warning handler, but it will never be * called. If it isn't replaced by the user, warnings will be * handled by xmlFormatError(). * + * @deprecated Do not call directly. + * * Format an warning message with additional detail from the * parser context and print to generic error handler. + * @param ctx an XML parser context + * @param msg printf-like format string + * @param ... arguments to format */ void xmlParserWarning(void *ctx, const char *msg ATTRIBUTE_UNUSED, ...) @@ -896,18 +887,17 @@ xmlParserWarning(void *ctx, const char *msg ATTRIBUTE_UNUSED, ...) } /** - * @param ctx an XML parser context - * @param msg printf-like format string - * @param ... arguments to format - * - * @deprecated Do not call directly. - * * This is the default validity error handler, but it will never be * called. If it isn't replaced by the user, errors will be * handled by xmlFormatError(). * + * @deprecated Do not call directly. + * * Format an error message with additional detail from the * parser context and print to generic error handler. + * @param ctx an XML parser context + * @param msg printf-like format string + * @param ... arguments to format */ void xmlParserValidityError(void *ctx, const char *msg ATTRIBUTE_UNUSED, ...) @@ -920,18 +910,17 @@ xmlParserValidityError(void *ctx, const char *msg ATTRIBUTE_UNUSED, ...) } /** - * @param ctx an XML parser context - * @param msg printf-like format string - * @param ... arguments to format - * - * @deprecated Do not call directly. - * * This is the default validity warning handler, but it will never * be called. If it isn't replaced by the user, warnings will be * handled by xmlFormatError(). * + * @deprecated Do not call directly. + * * Format an warning message with additional detail from the * parser context and print to generic error handler. + * @param ctx an XML parser context + * @param msg printf-like format string + * @param ... arguments to format */ void xmlParserValidityWarning(void *ctx, const char *msg ATTRIBUTE_UNUSED, ...) @@ -966,9 +955,9 @@ xmlGetLastError(void) } /** - * @param err pointer to the error - * * Reset the error to success. + * + * @param err pointer to the error */ void xmlResetError(xmlErrorPtr err) @@ -1004,11 +993,10 @@ xmlResetLastError(void) } /** - * @param from a source error - * @param to a target error - * * Copy an error. * + * @param from a source error + * @param to a target error * @returns 0 in case of success and -1 in case of error. */ int @@ -1031,7 +1019,6 @@ xmlCopyError(const xmlError *from, xmlErrorPtr to) { /** * @param code an xmlParserErrors code - * * @returns an error message for a code. */ const char * @@ -1362,10 +1349,10 @@ xmlErrString(xmlParserErrors code) { } /** + * Prints to stderr. + * * @param fmt printf-like format string * @param ap arguments - * - * Prints to stderr. */ void xmlVPrintErrorMessage(const char *fmt, va_list ap) { @@ -1373,10 +1360,10 @@ xmlVPrintErrorMessage(const char *fmt, va_list ap) { } /** + * Prints to stderr. + * * @param fmt printf-like format string * @param ... arguments - * - * Prints to stderr. */ void xmlPrintErrorMessage(const char *fmt, ...) { @@ -1388,10 +1375,10 @@ xmlPrintErrorMessage(const char *fmt, ...) { } /** + * Print message to stderr and abort. + * * @param fmt printf-like format string * @param ... arguments - * - * Print message to stderr and abort. */ void xmlAbort(const char *fmt, ...) { diff --git a/globals.c b/globals.c index 09677878..c5110a7e 100644 --- a/globals.c +++ b/globals.c @@ -190,43 +190,39 @@ static xmlGlobalState globalState; */ /** - * @param mem an already allocated block of memory - * * The variable holding the libxml free() implementation + * + * @param mem an already allocated block of memory */ xmlFreeFunc xmlFree = free; /** - * @param size the size requested in bytes - * * 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; /** - * @param size the size requested in bytes - * * 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; /** - * @param mem an already allocated block of memory - * @param size the new size requested in bytes - * * 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; /** - * @param cur the input char * - * * a strdup implementation with a type signature matching POSIX * + * @param cur the input char * * @returns a new xmlChar * or NULL */ static char * @@ -234,10 +230,9 @@ xmlPosixStrdup(const char *cur) { return((char*) xmlCharStrdup(cur)); } /** - * @param str a zero terminated string - * * The variable holding the libxml strdup() implementation * + * @param str a zero terminated string * @returns the copy of the string or NULL in case of error */ xmlStrdupFunc xmlMemStrdup = xmlPosixStrdup; @@ -275,10 +270,11 @@ static int xmlSaveNoEmptyTagsThrDef = 0; #ifdef LIBXML_SAX1_ENABLED /** + * Default SAX version1 handler for XML, builds the DOM tree + * * @deprecated This handler is unused and will be removed from future * versions. * - * Default SAX version1 handler for XML, builds the DOM tree */ const xmlSAXHandlerV1 xmlDefaultSAXHandler = { xmlSAX2InternalSubset, @@ -313,10 +309,11 @@ const xmlSAXHandlerV1 xmlDefaultSAXHandler = { #endif /* LIBXML_SAX1_ENABLED */ /** - * @deprecated Don't use - * * The default SAX Locator * { getPublicId, getSystemId, getLineNumber, getColumnNumber} + * + * @deprecated Don't use + * */ const xmlSAXLocator xmlDefaultSAXLocator = { xmlSAX2GetPublicId, @@ -327,10 +324,11 @@ const xmlSAXLocator xmlDefaultSAXLocator = { #if defined(LIBXML_HTML_ENABLED) && defined(LIBXML_SAX1_ENABLED) /** + * Default old SAX v1 handler for HTML, builds the DOM tree + * * @deprecated This handler is unused and will be removed from future * versions. * - * Default old SAX v1 handler for HTML, builds the DOM tree */ const xmlSAXHandlerV1 htmlDefaultSAXHandler = { xmlSAX2InternalSubset, @@ -772,11 +770,10 @@ xmlGetLocalRngState(void) { * library functions to make sure that thread-local storage was * allocated properly. * + * @since 2.12.0 * @returns 0 on success or -1 if a memory allocation failed. A failed * allocation signals a typically fatal and irrecoverable out-of-memory * situation. Don't call any library functions in this case. - * - * @since 2.12.0 */ int xmlCheckThreadLocalStorage(void) { @@ -798,13 +795,12 @@ xmlGetLastErrorInternal(void) { /** @cond IGNORE */ /** - * @param hinstDLL handle to DLL instance - * @param fdwReason Reason code for entry - * @param lpvReserved generic pointer (depends upon reason code) - * * Entry point for Windows library. It is being used to free thread-specific * storage. * + * @param hinstDLL handle to DLL instance + * @param fdwReason Reason code for entry + * @param lpvReserved generic pointer (depends upon reason code) * @returns TRUE always */ #ifdef USE_DLL_MAIN diff --git a/hash.c b/hash.c index 34a562fb..f7bd199d 100644 --- a/hash.c +++ b/hash.c @@ -148,11 +148,10 @@ xmlHashQNameValue(unsigned seed, } /** - * @param size initial size of the hash table - * * Create a new hash table. Set size to zero if the number of entries * can't be estimated. * + * @param size initial size of the hash table * @returns the newly created object, or NULL if a memory allocation failed. */ xmlHashTablePtr @@ -194,13 +193,12 @@ xmlHashCreate(int size) { } /** - * @param size the size of the hash table - * @param dict a dictionary to use for the hash - * * Create a new hash table backed by a dictionary. This can reduce * resource usage considerably if most keys passed to API functions * originate from this dictionary. * + * @param size the size of the hash table + * @param dict a dictionary to use for the hash * @returns the newly created object, or NULL if a memory allocation failed. */ xmlHashTablePtr @@ -216,11 +214,11 @@ xmlHashCreateDict(int size, xmlDictPtr dict) { } /** - * @param hash hash table - * @param dealloc deallocator function or NULL - * * Free the hash and its contents. The payload is deallocated with * `dealloc` if provided. + * + * @param hash hash table + * @param dealloc deallocator function or NULL */ void xmlHashFree(xmlHashTablePtr hash, xmlHashDeallocator dealloc) { @@ -256,10 +254,10 @@ xmlHashFree(xmlHashTablePtr hash, xmlHashDeallocator dealloc) { } /** + * Compare two strings for equality, allowing NULL values. + * * @param s1 string * @param s2 string - * - * Compare two strings for equality, allowing NULL values. */ static int xmlFastStrEqual(const xmlChar *s1, const xmlChar *s2) { @@ -271,16 +269,16 @@ xmlFastStrEqual(const xmlChar *s1, const xmlChar *s2) { } /** + * Try to find a matching hash table entry. If an entry was found, set + * `found` to 1 and return the entry. Otherwise, set `found` to 0 and return + * the location where a new entry should be inserted. + * * @param hash hash table, non-NULL, size > 0 * @param key first string key, non-NULL * @param key2 second string key * @param key3 third string key * @param hashValue valid hash value of keys * @param pfound result of search - * - * Try to find a matching hash table entry. If an entry was found, set - * `found` to 1 and return the entry. Otherwise, set `found` to 0 and return - * the location where a new entry should be inserted. */ ATTRIBUTE_NO_SANITIZE_INTEGER static xmlHashEntry * @@ -337,11 +335,10 @@ xmlHashFindEntry(const xmlHashTable *hash, const xmlChar *key, } /** - * @param hash hash table - * @param size new size of the hash table - * * Resize the hash table. * + * @param hash hash table + * @param size new size of the hash table * @returns 0 in case of success, -1 if a memory allocation failed. */ static int @@ -403,6 +400,8 @@ done: } /** + * Internal function to add or update hash entries. + * * @param hash hash table * @param key first string key * @param key2 second string key @@ -410,8 +409,6 @@ done: * @param payload pointer to the payload * @param dealloc deallocator function for replaced item or NULL * @param update whether existing entries should be updated - * - * Internal function to add or update hash entries. */ ATTRIBUTE_NO_SANITIZE_INTEGER static int @@ -586,10 +583,10 @@ xmlHashUpdateInternal(xmlHashTablePtr hash, const xmlChar *key, } /** + * Free a hash table entry with xmlFree. + * * @param entry hash table entry * @param key the entry's string key - * - * Free a hash table entry with xmlFree. */ void xmlHashDefaultDeallocator(void *entry, const xmlChar *key ATTRIBUTE_UNUSED) { @@ -597,10 +594,6 @@ xmlHashDefaultDeallocator(void *entry, const xmlChar *key ATTRIBUTE_UNUSED) { } /** - * @param hash hash table - * @param key string key - * @param payload pointer to the payload - * * Add a hash table entry. If an entry with this key already exists, * payload will not be updated and 0 is returned. This return value * can't be distinguished from out-of-memory errors, so this function @@ -608,6 +601,9 @@ xmlHashDefaultDeallocator(void *entry, const xmlChar *key ATTRIBUTE_UNUSED) { * * @since 2.13.0 * + * @param hash hash table + * @param key string key + * @param payload pointer to the payload * @returns 1 on success, 0 if an entry exists and -1 in case of error. */ int @@ -616,17 +612,16 @@ xmlHashAdd(xmlHashTablePtr hash, const xmlChar *key, void *payload) { } /** - * @param hash hash table - * @param key first string key - * @param key2 second string key - * @param payload pointer to the payload - * * Add a hash table entry with two strings as key. * * See xmlHashAdd(). * * @since 2.13.0 * + * @param hash hash table + * @param key first string key + * @param key2 second string key + * @param payload pointer to the payload * @returns 1 on success, 0 if an entry exists and -1 in case of error. */ int @@ -636,18 +631,17 @@ xmlHashAdd2(xmlHashTablePtr hash, const xmlChar *key, } /** - * @param hash hash table - * @param key first string key - * @param key2 second string key - * @param key3 third string key - * @param payload pointer to the payload - * * Add a hash table entry with three strings as key. * * See xmlHashAdd(). * * @since 2.13.0 * + * @param hash hash table + * @param key first string key + * @param key2 second string key + * @param key3 third string key + * @param payload pointer to the payload * @returns 1 on success, 0 if an entry exists and -1 in case of error. */ int @@ -658,10 +652,6 @@ xmlHashAdd3(xmlHashTablePtr hash, const xmlChar *key, } /** - * @param hash hash table - * @param key string key - * @param payload pointer to the payload - * * Add a hash table entry. If an entry with this key already exists, * payload will not be updated and -1 is returned. This return value * can't be distinguished from out-of-memory errors, so this function @@ -670,6 +660,9 @@ xmlHashAdd3(xmlHashTablePtr hash, const xmlChar *key, * NOTE: This function doesn't allow to distinguish malloc failures from * existing entries. Use xmlHashAdd() instead. * + * @param hash hash table + * @param key string key + * @param payload pointer to the payload * @returns 0 on success and -1 in case of error. */ int @@ -685,15 +678,14 @@ xmlHashAddEntry(xmlHashTablePtr hash, const xmlChar *key, void *payload) { } /** - * @param hash hash table - * @param key first string key - * @param key2 second string key - * @param payload pointer to the payload - * * Add a hash table entry with two strings as key. * * See xmlHashAddEntry(). * + * @param hash hash table + * @param key first string key + * @param key2 second string key + * @param payload pointer to the payload * @returns 0 on success and -1 in case of error. */ int @@ -710,16 +702,15 @@ xmlHashAddEntry2(xmlHashTablePtr hash, const xmlChar *key, } /** + * Add a hash table entry with three strings as key. + * + * See xmlHashAddEntry(). + * * @param hash hash table * @param key first string key * @param key2 second string key * @param key3 third string key * @param payload pointer to the payload - * - * Add a hash table entry with three strings as key. - * - * See xmlHashAddEntry(). - * * @returns 0 on success and -1 in case of error. */ int @@ -737,14 +728,13 @@ xmlHashAddEntry3(xmlHashTablePtr hash, const xmlChar *key, } /** + * Add a hash table entry. If an entry with this key already exists, + * the old payload will be freed and updated with the new value. + * * @param hash hash table * @param key string key * @param payload pointer to the payload * @param dealloc deallocator function for replaced item or NULL - * - * Add a hash table entry. If an entry with this key already exists, - * the old payload will be freed and updated with the new value. - * * @returns 0 in case of success, -1 if a memory allocation failed. */ int @@ -760,16 +750,15 @@ xmlHashUpdateEntry(xmlHashTablePtr hash, const xmlChar *key, } /** + * Add a hash table entry with two strings as key. + * + * See xmlHashUpdateEntry(). + * * @param hash hash table * @param key first string key * @param key2 second string key * @param payload pointer to the payload * @param dealloc deallocator function for replaced item or NULL - * - * Add a hash table entry with two strings as key. - * - * See xmlHashUpdateEntry(). - * * @returns 0 on success and -1 in case of error. */ int @@ -786,17 +775,16 @@ xmlHashUpdateEntry2(xmlHashTablePtr hash, const xmlChar *key, } /** + * Add a hash table entry with three strings as key. + * + * See xmlHashUpdateEntry(). + * * @param hash hash table * @param key first string key * @param key2 second string key * @param key3 third string key * @param payload pointer to the payload * @param dealloc deallocator function for replaced item or NULL - * - * Add a hash table entry with three strings as key. - * - * See xmlHashUpdateEntry(). - * * @returns 0 on success and -1 in case of error. */ int @@ -813,11 +801,10 @@ xmlHashUpdateEntry3(xmlHashTablePtr hash, const xmlChar *key, } /** - * @param hash hash table - * @param key string key - * * Find the entry specified by `key`. * + * @param hash hash table + * @param key string key * @returns a pointer to the payload or NULL if no entry was found. */ void * @@ -826,12 +813,11 @@ xmlHashLookup(xmlHashTablePtr hash, const xmlChar *key) { } /** + * Find the payload specified by the (`key`, `key2`) tuple. + * * @param hash hash table * @param key first string key * @param key2 second string key - * - * Find the payload specified by the (`key`, `key2`) tuple. - * * @returns a pointer to the payload or NULL if no entry was found. */ void * @@ -841,12 +827,11 @@ xmlHashLookup2(xmlHashTablePtr hash, const xmlChar *key, } /** + * Find the payload specified by the QName `prefix:name` or `name`. + * * @param hash hash table * @param prefix prefix of the string key * @param name local name of the string key - * - * Find the payload specified by the QName `prefix:name` or `name`. - * * @returns a pointer to the payload or NULL if no entry was found. */ void * @@ -856,14 +841,13 @@ xmlHashQLookup(xmlHashTablePtr hash, const xmlChar *prefix, } /** + * Find the payload specified by the QNames tuple. + * * @param hash hash table * @param prefix first prefix * @param name first local name * @param prefix2 second prefix * @param name2 second local name - * - * Find the payload specified by the QNames tuple. - * * @returns a pointer to the payload or NULL if no entry was found. */ void * @@ -874,13 +858,12 @@ xmlHashQLookup2(xmlHashTablePtr hash, const xmlChar *prefix, } /** + * Find the payload specified by the (`key`, `key2`, `key3`) tuple. + * * @param hash hash table * @param key first string key * @param key2 second string key * @param key3 third string key - * - * Find the payload specified by the (`key`, `key2`, `key3`) tuple. - * * @returns a pointer to the payload or NULL if no entry was found. */ void * @@ -900,6 +883,8 @@ xmlHashLookup3(xmlHashTablePtr hash, const xmlChar *key, } /** + * Find the payload specified by the QNames tuple. + * * @param hash hash table * @param prefix first prefix * @param name first local name @@ -907,9 +892,6 @@ xmlHashLookup3(xmlHashTablePtr hash, const xmlChar *key, * @param name2 second local name * @param prefix3 third prefix * @param name3 third local name - * - * Find the payload specified by the QNames tuple. - * * @returns a pointer to the payload or NULL if no entry was found. */ ATTRIBUTE_NO_SANITIZE_INTEGER @@ -967,11 +949,11 @@ stubHashScannerFull(void *payload, void *data, const xmlChar *key, } /** + * Scan the hash `table` and apply `scan` to each value. + * * @param hash hash table * @param scan scanner function for items in the hash * @param data extra data passed to `scan` - * - * Scan the hash `table` and apply `scan` to each value. */ void xmlHashScan(xmlHashTablePtr hash, xmlHashScanner scan, void *data) { @@ -982,11 +964,11 @@ xmlHashScan(xmlHashTablePtr hash, xmlHashScanner scan, void *data) { } /** + * Scan the hash `table` and apply `scan` to each value. + * * @param hash hash table * @param scan scanner function for items in the hash * @param data extra data passed to `scan` - * - * Scan the hash `table` and apply `scan` to each value. */ void xmlHashScanFull(xmlHashTablePtr hash, xmlHashScannerFull scan, void *data) { @@ -1031,16 +1013,16 @@ xmlHashScanFull(xmlHashTablePtr hash, xmlHashScannerFull scan, void *data) { } /** + * Scan the hash `table` and apply `scan` to each value matching + * (`key`, `key2`, `key3`) tuple. If one of the keys is null, + * the comparison is considered to match. + * * @param hash hash table * @param key first string key or NULL * @param key2 second string key or NULL * @param key3 third string key or NULL * @param scan scanner function for items in the hash * @param data extra data passed to `scan` - * - * Scan the hash `table` and apply `scan` to each value matching - * (`key`, `key2`, `key3`) tuple. If one of the keys is null, - * the comparison is considered to match. */ void xmlHashScan3(xmlHashTablePtr hash, const xmlChar *key, @@ -1053,16 +1035,16 @@ xmlHashScan3(xmlHashTablePtr hash, const xmlChar *key, } /** + * Scan the hash `table` and apply `scan` to each value matching + * (`key`, `key2`, `key3`) tuple. If one of the keys is null, + * the comparison is considered to match. + * * @param hash hash table * @param key first string key or NULL * @param key2 second string key or NULL * @param key3 third string key or NULL * @param scan scanner function for items in the hash * @param data extra data passed to `scan` - * - * Scan the hash `table` and apply `scan` to each value matching - * (`key`, `key2`, `key3`) tuple. If one of the keys is null, - * the comparison is considered to match. */ void xmlHashScanFull3(xmlHashTablePtr hash, const xmlChar *key, @@ -1181,10 +1163,9 @@ xmlHashCopy(xmlHashTablePtr hash, xmlHashCopier copy) { } /** - * @param hash hash table - * * Query the number of elements in the hash table. * + * @param hash hash table * @returns the number of elements in the hash table or * -1 in case of error. */ @@ -1196,13 +1177,12 @@ xmlHashSize(xmlHashTablePtr hash) { } /** - * @param hash hash table - * @param key string key - * @param dealloc deallocator function for removed item or NULL - * * Find the entry specified by the `key` and remove it from the hash table. * Payload will be freed with `dealloc`. * + * @param hash hash table + * @param key string key + * @param dealloc deallocator function for removed item or NULL * @returns 0 on success and -1 if no entry was found. */ int xmlHashRemoveEntry(xmlHashTablePtr hash, const xmlChar *key, @@ -1211,15 +1191,14 @@ int xmlHashRemoveEntry(xmlHashTablePtr hash, const xmlChar *key, } /** - * @param hash hash table - * @param key first string key - * @param key2 second string key - * @param dealloc deallocator function for removed item or NULL - * * Remove an entry with two strings as key. * * See xmlHashRemoveEntry(). * + * @param hash hash table + * @param key first string key + * @param key2 second string key + * @param dealloc deallocator function for removed item or NULL * @returns 0 on success and -1 in case of error. */ int @@ -1229,16 +1208,15 @@ xmlHashRemoveEntry2(xmlHashTablePtr hash, const xmlChar *key, } /** + * Remove an entry with three strings as key. + * + * See xmlHashRemoveEntry(). + * * @param hash hash table * @param key first string key * @param key2 second string key * @param key3 third string key * @param dealloc deallocator function for removed item or NULL - * - * Remove an entry with three strings as key. - * - * See xmlHashRemoveEntry(). - * * @returns 0 on success and -1 in case of error. */ ATTRIBUTE_NO_SANITIZE_INTEGER diff --git a/include/libxml/c14n.h b/include/libxml/c14n.h index ee941802..61d829bd 100644 --- a/include/libxml/c14n.h +++ b/include/libxml/c14n.h @@ -87,12 +87,11 @@ XMLPUBFUN int * This is the core C14N function */ /** + * Signature for a C14N callback on visible nodes + * * @param user_data user data * @param node the current node * @param parent the parent node - * - * Signature for a C14N callback on visible nodes - * * @returns 1 if the node should be included */ typedef int (*xmlC14NIsVisibleCallback) (void* user_data, diff --git a/include/libxml/chvalid.h b/include/libxml/chvalid.h index 8c8b86ad..9d2ddbd7 100644 --- a/include/libxml/chvalid.h +++ b/include/libxml/chvalid.h @@ -58,9 +58,9 @@ XMLPUBFUN int /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsBaseChar_ch(c) (((0x41 <= (c)) && ((c) <= 0x5a)) || \ ((0x61 <= (c)) && ((c) <= 0x7a)) || \ @@ -69,9 +69,9 @@ XMLPUBFUN int (0xf8 <= (c))) /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsBaseCharQ(c) (((c) < 0x100) ? \ xmlIsBaseChar_ch((c)) : \ @@ -80,36 +80,36 @@ XMLPUBFUN int XMLPUBVAR const xmlChRangeGroup xmlIsBaseCharGroup; /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsBlank_ch(c) (((c) == 0x20) || \ ((0x9 <= (c)) && ((c) <= 0xa)) || \ ((c) == 0xd)) /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsBlankQ(c) (((c) < 0x100) ? \ xmlIsBlank_ch((c)) : 0) /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsChar_ch(c) (((0x9 <= (c)) && ((c) <= 0xa)) || \ ((c) == 0xd) || \ (0x20 <= (c))) /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsCharQ(c) (((c) < 0x100) ? \ xmlIsChar_ch((c)) :\ @@ -120,9 +120,9 @@ XMLPUBVAR const xmlChRangeGroup xmlIsBaseCharGroup; XMLPUBVAR const xmlChRangeGroup xmlIsCharGroup; /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsCombiningQ(c) (((c) < 0x100) ? \ 0 : \ @@ -131,16 +131,16 @@ XMLPUBVAR const xmlChRangeGroup xmlIsCharGroup; XMLPUBVAR const xmlChRangeGroup xmlIsCombiningGroup; /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsDigit_ch(c) (((0x30 <= (c)) && ((c) <= 0x39))) /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsDigitQ(c) (((c) < 0x100) ? \ xmlIsDigit_ch((c)) : \ @@ -149,16 +149,16 @@ XMLPUBVAR const xmlChRangeGroup xmlIsCombiningGroup; XMLPUBVAR const xmlChRangeGroup xmlIsDigitGroup; /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsExtender_ch(c) (((c) == 0xb7)) /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsExtenderQ(c) (((c) < 0x100) ? \ xmlIsExtender_ch((c)) : \ @@ -167,9 +167,9 @@ XMLPUBVAR const xmlChRangeGroup xmlIsDigitGroup; XMLPUBVAR const xmlChRangeGroup xmlIsExtenderGroup; /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsIdeographicQ(c) (((c) < 0x100) ? \ 0 :\ @@ -181,16 +181,16 @@ XMLPUBVAR const xmlChRangeGroup xmlIsIdeographicGroup; XMLPUBVAR const unsigned char xmlIsPubidChar_tab[256]; /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsPubidChar_ch(c) (xmlIsPubidChar_tab[(c)]) /** - * @param c char to validate - * * Automatically generated by genChRanges.py + * + * @param c char to validate */ #define xmlIsPubidCharQ(c) (((c) < 0x100) ? \ xmlIsPubidChar_ch((c)) : 0) diff --git a/include/libxml/encoding.h b/include/libxml/encoding.h index 13d5287f..76375bb2 100644 --- a/include/libxml/encoding.h +++ b/include/libxml/encoding.h @@ -121,16 +121,15 @@ typedef enum { } xmlCharEncFlags; /** - * @param out a pointer to an array of bytes to store the UTF-8 result - * @param outlen the length of `out` - * @param in a pointer to an array of chars in the original encoding - * @param inlen the length of `in` - * * Convert characters to UTF-8. * * On success, the value of `inlen` after return is the number of * bytes consumed and `outlen` is the number of bytes produced. * + * @param out a pointer to an array of bytes to store the UTF-8 result + * @param outlen the length of `out` + * @param in a pointer to an array of chars in the original encoding + * @param inlen the length of `in` * @returns the number of bytes written or an xmlCharEncError code. */ typedef int (*xmlCharEncodingInputFunc)(unsigned char *out, int *outlen, @@ -138,16 +137,15 @@ typedef int (*xmlCharEncodingInputFunc)(unsigned char *out, int *outlen, /** - * @param out a pointer to an array of bytes to store the result - * @param outlen the length of `out` - * @param in a pointer to an array of UTF-8 chars - * @param inlen the length of `in` - * * Convert characters from UTF-8. * * On success, the value of `inlen` after return is the number of * bytes consumed and `outlen` is the number of bytes produced. * + * @param out a pointer to an array of bytes to store the result + * @param outlen the length of `out` + * @param in a pointer to an array of UTF-8 chars + * @param inlen the length of `in` * @returns the number of bytes written or an xmlCharEncError code. */ typedef int (*xmlCharEncodingOutputFunc)(unsigned char *out, int *outlen, @@ -155,13 +153,6 @@ typedef int (*xmlCharEncodingOutputFunc)(unsigned char *out, int *outlen, /** - * @param vctxt conversion context - * @param out a pointer to an array of bytes to store the result - * @param outlen the length of `out` - * @param in a pointer to an array of input bytes - * @param inlen the length of `in` - * @param flush end of input - * * Convert between character encodings. * * The value of `inlen` after return is the number of bytes consumed @@ -171,6 +162,12 @@ typedef int (*xmlCharEncodingOutputFunc)(unsigned char *out, int *outlen, * `flush` flag can be used to detect truncated sequences at EOF. * Otherwise, the flag can be ignored. * + * @param vctxt conversion context + * @param out a pointer to an array of bytes to store the result + * @param outlen the length of `out` + * @param in a pointer to an array of input bytes + * @param inlen the length of `in` + * @param flush end of input * @returns an xmlCharEncError code. */ typedef xmlCharEncError @@ -178,9 +175,9 @@ typedef xmlCharEncError const unsigned char *in, int *inlen, int flush); /** - * @param vctxt conversion context - * * Free a conversion context. + * + * @param vctxt conversion context */ typedef void (*xmlCharEncConvCtxtDtor)(void *vctxt); @@ -209,17 +206,16 @@ struct _xmlCharEncodingHandler { }; /** - * @param vctxt user data - * @param name encoding name - * @param flags bit mask of flags - * @param out pointer to resulting handler - * * If this function returns XML_ERR_OK, it must fill the `out` * pointer with an encoding handler. The handler can be obtained * from xmlCharEncNewCustomHandler(). * * `flags` can contain XML_ENC_INPUT, XML_ENC_OUTPUT or both. * + * @param vctxt user data + * @param name encoding name + * @param flags bit mask of flags + * @param out pointer to resulting handler * @returns an xmlParserErrors code. */ typedef xmlParserErrors diff --git a/include/libxml/hash.h b/include/libxml/hash.h index df2f273b..e383126f 100644 --- a/include/libxml/hash.h +++ b/include/libxml/hash.h @@ -34,8 +34,6 @@ typedef xmlHashTable *xmlHashTablePtr; * serious trouble within the library. */ /** - * @param fptr pointer to a function - * * Macro to do a casting from an object pointer to a * function pointer without encountering a warning from * gcc @@ -43,6 +41,7 @@ typedef xmlHashTable *xmlHashTablePtr; * \#define XML_CAST_FPTR(fptr) (*(void **)(&fptr)) * This macro violated ISO C aliasing rules (gcc4 on s390 broke) * so it is disabled now + * @param fptr pointer to a function */ #define XML_CAST_FPTR(fptr) fptr @@ -51,37 +50,36 @@ typedef xmlHashTable *xmlHashTablePtr; * function types: */ /** + * Callback to free data from a hash. + * * @param payload the data in the hash * @param name the name associated - * - * Callback to free data from a hash. */ typedef void (*xmlHashDeallocator)(void *payload, const xmlChar *name); /** - * @param payload the data in the hash - * @param name the name associated - * * Callback to copy data from a hash. * + * @param payload the data in the hash + * @param name the name associated * @returns a copy of the data or NULL in case of error. */ typedef void *(*xmlHashCopier)(void *payload, const xmlChar *name); /** + * Callback when scanning data in a hash with the simple scanner. + * * @param payload the data in the hash * @param data extra scanner data * @param name the name associated - * - * Callback when scanning data in a hash with the simple scanner. */ typedef void (*xmlHashScanner)(void *payload, void *data, const xmlChar *name); /** + * Callback when scanning data in a hash with the full scanner. + * * @param payload the data in the hash * @param data extra scanner data * @param name the name associated * @param name2 the second name associated * @param name3 the third name associated - * - * Callback when scanning data in a hash with the full scanner. */ typedef void (*xmlHashScannerFull)(void *payload, void *data, const xmlChar *name, const xmlChar *name2, diff --git a/include/libxml/list.h b/include/libxml/list.h index b7cdc0ba..2ccc0456 100644 --- a/include/libxml/list.h +++ b/include/libxml/list.h @@ -27,26 +27,24 @@ typedef struct _xmlList xmlList; typedef xmlList *xmlListPtr; /** - * @param lk the data to deallocate - * * Callback function used to free data from a list. + * + * @param lk the data to deallocate */ typedef void (*xmlListDeallocator) (xmlLinkPtr lk); /** - * @param data0 the first data - * @param data1 the second data - * * Callback function used to compare 2 data. * + * @param data0 the first data + * @param data1 the second data * @returns 0 is equality, -1 or 1 otherwise depending on the ordering. */ typedef int (*xmlListDataCompare) (const void *data0, const void *data1); /** - * @param data the data found in the list - * @param user extra user provided data to the walker - * * Callback function used when walking a list with xmlListWalk(). * + * @param data the data found in the list + * @param user extra user provided data to the walker * @returns 0 to stop walking the list, 1 otherwise. */ typedef int (*xmlListWalker) (const void *data, void *user); diff --git a/include/libxml/parser.h b/include/libxml/parser.h index 52f6b359..a3aae942 100644 --- a/include/libxml/parser.h +++ b/include/libxml/parser.h @@ -206,13 +206,6 @@ typedef struct _xmlParserNsData xmlParserNsData; typedef struct _xmlAttrHashBucket xmlAttrHashBucket; /** - * @param ctxt parser context - * @param url URL to load - * @param publicId publid ID from DTD (optional) - * @param type resource type - * @param flags flags - * @param out result pointer - * * Callback for custom resource loaders. * * `flags` can contain XML_INPUT_UNZIP and XML_INPUT_NETWORK. @@ -220,6 +213,12 @@ typedef struct _xmlAttrHashBucket xmlAttrHashBucket; * On success, `out` should be set to a new parser input object and * XML_ERR_OK should be returned. * + * @param ctxt parser context + * @param url URL to load + * @param publicId publid ID from DTD (optional) + * @param type resource type + * @param flags flags + * @param out result pointer * @returns an xmlParserErrors code. */ typedef xmlParserErrors @@ -489,10 +488,6 @@ struct _xmlSAXLocator { }; /** - * @param ctx the user data (XML parser context) - * @param publicId The public ID of the entity - * @param systemId The system ID of the entity - * * Callback: * The entity loader, to control the loading of external entities, * the application can either: @@ -500,64 +495,65 @@ struct _xmlSAXLocator { * - or better use the xmlSetExternalEntityLoader() function to * set up it's own entity resolution routine * + * @param ctx the user data (XML parser context) + * @param publicId The public ID of the entity + * @param systemId The system ID of the entity * @returns the xmlParserInputPtr if inlined or NULL for DOM behaviour. */ typedef xmlParserInputPtr (*resolveEntitySAXFunc) (void *ctx, const xmlChar *publicId, const xmlChar *systemId); /** + * Callback on internal subset declaration. + * * @param ctx the user data (XML parser context) * @param name the root element name * @param ExternalID the external ID * @param 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); /** + * Callback on external subset declaration. + * * @param ctx the user data (XML parser context) * @param name the root element name * @param ExternalID the external ID * @param 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); /** - * @param ctx the user data (XML parser context) - * @param name The entity name - * * Get an entity by name. * + * @param ctx the user data (XML parser context) + * @param name The entity name * @returns the xmlEntityPtr if found. */ typedef xmlEntityPtr (*getEntitySAXFunc) (void *ctx, const xmlChar *name); /** - * @param ctx the user data (XML parser context) - * @param name The entity name - * * Get a parameter entity by name. * + * @param ctx the user data (XML parser context) + * @param name The entity name * @returns the xmlEntityPtr if found. */ typedef xmlEntityPtr (*getParameterEntitySAXFunc) (void *ctx, const xmlChar *name); /** + * An entity definition has been parsed. + * * @param ctx the user data (XML parser context) * @param name the entity name * @param type the entity type * @param publicId The public ID of the entity * @param systemId The system ID of the entity * @param content the entity value (without processing). - * - * An entity definition has been parsed. */ typedef void (*entityDeclSAXFunc) (void *ctx, const xmlChar *name, @@ -566,18 +562,20 @@ typedef void (*entityDeclSAXFunc) (void *ctx, const xmlChar *systemId, xmlChar *content); /** + * What to do when a notation declaration has been parsed. + * * @param ctx the user data (XML parser context) * @param name The name of the notation * @param publicId The public ID of the entity * @param 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); /** + * An attribute definition has been parsed. + * * @param ctx the user data (XML parser context) * @param elem the name of the element * @param fullname the attribute name @@ -585,8 +583,6 @@ typedef void (*notationDeclSAXFunc)(void *ctx, * @param def the type of default value * @param defaultValue the attribute default value * @param tree the tree of enumerated value set - * - * An attribute definition has been parsed. */ typedef void (*attributeDeclSAXFunc)(void *ctx, const xmlChar *elem, @@ -596,25 +592,25 @@ typedef void (*attributeDeclSAXFunc)(void *ctx, const xmlChar *defaultValue, xmlEnumerationPtr tree); /** + * An element definition has been parsed. + * * @param ctx the user data (XML parser context) * @param name the element name * @param type the element type * @param content the element value tree - * - * An element definition has been parsed. */ typedef void (*elementDeclSAXFunc)(void *ctx, const xmlChar *name, int type, xmlElementContentPtr content); /** + * What to do when an unparsed entity declaration is parsed. + * * @param ctx the user data (XML parser context) * @param name The name of the entity * @param publicId The public ID of the entity * @param systemId The system ID of the entity * @param notationName the name of the notation - * - * What to do when an unparsed entity declaration is parsed. */ typedef void (*unparsedEntityDeclSAXFunc)(void *ctx, const xmlChar *name, @@ -622,166 +618,166 @@ typedef void (*unparsedEntityDeclSAXFunc)(void *ctx, const xmlChar *systemId, const xmlChar *notationName); /** - * @param ctx the user data (XML parser context) - * @param 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. + * + * @param ctx the user data (XML parser context) + * @param loc A SAX Locator */ typedef void (*setDocumentLocatorSAXFunc) (void *ctx, xmlSAXLocatorPtr loc); /** - * @param ctx the user data (XML parser context) - * * Called when the document start being processed. + * + * @param ctx the user data (XML parser context) */ typedef void (*startDocumentSAXFunc) (void *ctx); /** - * @param ctx the user data (XML parser context) - * * Called when the document end has been detected. + * + * @param ctx the user data (XML parser context) */ typedef void (*endDocumentSAXFunc) (void *ctx); /** + * Called when an opening tag has been processed. + * * @param ctx the user data (XML parser context) * @param name The element name, including namespace prefix * @param 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); /** + * Called when the end of an element has been detected. + * * @param ctx the user data (XML parser context) * @param name The element name - * - * Called when the end of an element has been detected. */ typedef void (*endElementSAXFunc) (void *ctx, const xmlChar *name); /** - * @param ctx the user data (XML parser context) - * @param name The attribute name, including namespace prefix - * @param 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. + * + * @param ctx the user data (XML parser context) + * @param name The attribute name, including namespace prefix + * @param value The attribute value */ typedef void (*attributeSAXFunc) (void *ctx, const xmlChar *name, const xmlChar *value); /** + * Called when an entity reference is detected. + * * @param ctx the user data (XML parser context) * @param name The entity name - * - * Called when an entity reference is detected. */ typedef void (*referenceSAXFunc) (void *ctx, const xmlChar *name); /** + * Receiving some chars from the parser. + * * @param ctx the user data (XML parser context) * @param ch a xmlChar string * @param len the number of xmlChar - * - * Receiving some chars from the parser. */ typedef void (*charactersSAXFunc) (void *ctx, const xmlChar *ch, int len); /** + * Receiving some ignorable whitespaces from the parser. + * UNUSED: by default the DOM building will use characters. + * * @param ctx the user data (XML parser context) * @param ch a xmlChar string * @param 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); /** + * A processing instruction has been parsed. + * * @param ctx the user data (XML parser context) * @param target the target name * @param data the PI data's - * - * A processing instruction has been parsed. */ typedef void (*processingInstructionSAXFunc) (void *ctx, const xmlChar *target, const xmlChar *data); /** + * A comment has been parsed. + * * @param ctx the user data (XML parser context) * @param value the comment content - * - * A comment has been parsed. */ typedef void (*commentSAXFunc) (void *ctx, const xmlChar *value); /** + * Called when a pcdata block has been parsed. + * * @param ctx the user data (XML parser context) * @param value The pcdata content * @param len the block length - * - * Called when a pcdata block has been parsed. */ typedef void (*cdataBlockSAXFunc) ( void *ctx, const xmlChar *value, int len); /** - * @param ctx an XML parser context - * @param msg the message to display/transmit + * Display and format a warning messages, callback. + * * @...: extra parameters for the message display * - * Display and format a warning messages, callback. + * @param ctx an XML parser context + * @param msg the message to display/transmit */ typedef void (*warningSAXFunc) (void *ctx, const char *msg, ...) LIBXML_ATTR_FORMAT(2,3); /** - * @param ctx an XML parser context - * @param msg the message to display/transmit + * Display and format an error messages, callback. + * * @...: extra parameters for the message display * - * Display and format an error messages, callback. + * @param ctx an XML parser context + * @param msg the message to display/transmit */ typedef void (*errorSAXFunc) (void *ctx, const char *msg, ...) LIBXML_ATTR_FORMAT(2,3); /** - * @param ctx an XML parser context - * @param msg the message to display/transmit - * @...: extra parameters for the message display - * * Display and format fatal error messages, callback. * Note: so far fatalError() SAX callbacks are not used, error() * get all the callbacks for errors. + * + * @...: extra parameters for the message display + * + * @param ctx an XML parser context + * @param msg the message to display/transmit */ typedef void (*fatalErrorSAXFunc) (void *ctx, const char *msg, ...) LIBXML_ATTR_FORMAT(2,3); /** - * @param ctx the user data (XML parser context) - * * Is this document tagged standalone? * + * @param ctx the user data (XML parser context) * @returns 1 if true */ typedef int (*isStandaloneSAXFunc) (void *ctx); /** - * @param ctx the user data (XML parser context) - * * Does this document has an internal subset. * + * @param ctx the user data (XML parser context) * @returns 1 if true */ typedef int (*hasInternalSubsetSAXFunc) (void *ctx); /** - * @param ctx the user data (XML parser context) - * * Does this document has an external subset? * + * @param ctx the user data (XML parser context) * @returns 1 if true */ typedef int (*hasExternalSubsetSAXFunc) (void *ctx); @@ -797,6 +793,10 @@ typedef int (*hasExternalSubsetSAXFunc) (void *ctx); #define XML_SAX2_MAGIC 0xDEEDBEAF /** + * SAX2 callback when an element start has been detected by the parser. + * It provides the namespace information for the element, as well as + * the new namespace declarations on the element. + * * @param ctx the user data (XML parser context) * @param localname the local name of the element * @param prefix the element namespace prefix if available @@ -808,10 +808,6 @@ typedef int (*hasExternalSubsetSAXFunc) (void *ctx); * ones are at the end of the array * @param attributes pointer to the array of (localname/prefix/URI/value/end) * attribute values. - * - * SAX2 callback when an element start has been detected by the parser. - * It provides the namespace information for the element, as well as - * the new namespace declarations on the element. */ typedef void (*startElementNsSAX2Func) (void *ctx, @@ -825,13 +821,13 @@ typedef void (*startElementNsSAX2Func) (void *ctx, const xmlChar **attributes); /** + * SAX2 callback when an element end has been detected by the parser. + * It provides the namespace information for the element. + * * @param ctx the user data (XML parser context) * @param localname the local name of the element * @param prefix the element namespace prefix if available * @param URI the element namespace name if available - * - * SAX2 callback when an element end has been detected by the parser. - * It provides the namespace information for the element. */ typedef void (*endElementNsSAX2Func) (void *ctx, @@ -985,12 +981,11 @@ struct _xmlSAXHandlerV1 { /** + * External entity loaders types. + * * @param URL The System ID of the resource requested * @param ID The Public ID of the resource requested * @param context the XML parser context - * - * External entity loaders types. - * * @returns the entity input parser. */ typedef xmlParserInputPtr (*xmlExternalEntityLoader) (const char *URL, diff --git a/include/libxml/parserInternals.h b/include/libxml/parserInternals.h index d528e319..10c9c00f 100644 --- a/include/libxml/parserInternals.h +++ b/include/libxml/parserInternals.h @@ -82,167 +82,154 @@ extern "C" { * * ************************************************************************/ /** - * @param c an byte value (int) - * * Macro to check the following production in the XML spec: * * [2] Char ::= #x9 | #xA | #xD | [#x20...] * * any byte character in the accepted range + * @param c an byte value (int) */ #define IS_BYTE_CHAR(c) xmlIsChar_ch(c) /** - * @param c an UNICODE value (int) - * * Macro to check the following production in the XML spec: * * [2] Char ::= #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] * | [#x10000-#x10FFFF] * * any Unicode character, excluding the surrogate blocks, FFFE, and FFFF. + * @param c an UNICODE value (int) */ #define IS_CHAR(c) xmlIsCharQ(c) /** - * @param c an xmlChar (usually an unsigned char) - * * Behaves like IS_CHAR on single-byte value + * + * @param c an xmlChar (usually an unsigned char) */ #define IS_CHAR_CH(c) xmlIsChar_ch(c) /** - * @param c an UNICODE value (int) - * * Macro to check the following production in the XML spec: * * [3] S ::= (#x20 | #x9 | #xD | #xA)+ + * @param c an UNICODE value (int) */ #define IS_BLANK(c) xmlIsBlankQ(c) /** - * @param c an xmlChar value (normally unsigned char) - * * Behaviour same as IS_BLANK + * + * @param c an xmlChar value (normally unsigned char) */ #define IS_BLANK_CH(c) xmlIsBlank_ch(c) /** - * @param c an UNICODE value (int) - * * Macro to check the following production in the XML spec: * * [85] BaseChar ::= ... long list see REC ... + * @param c an UNICODE value (int) */ #define IS_BASECHAR(c) xmlIsBaseCharQ(c) /** - * @param c an UNICODE value (int) - * * Macro to check the following production in the XML spec: * * [88] Digit ::= ... long list see REC ... + * @param c an UNICODE value (int) */ #define IS_DIGIT(c) xmlIsDigitQ(c) /** - * @param c an xmlChar value (usually an unsigned char) - * * Behaves like IS_DIGIT but with a single byte argument + * + * @param c an xmlChar value (usually an unsigned char) */ #define IS_DIGIT_CH(c) xmlIsDigit_ch(c) /** - * @param c an UNICODE value (int) - * * Macro to check the following production in the XML spec: * * [87] CombiningChar ::= ... long list see REC ... + * @param c an UNICODE value (int) */ #define IS_COMBINING(c) xmlIsCombiningQ(c) /** - * @param c an xmlChar (usually an unsigned char) - * * Always false (all combining chars > 0xff) + * + * @param c an xmlChar (usually an unsigned char) */ #define IS_COMBINING_CH(c) 0 /** - * @param c an UNICODE value (int) - * * Macro to check the following production in the XML spec: * * [89] Extender ::= #x00B7 | #x02D0 | #x02D1 | #x0387 | #x0640 | * #x0E46 | #x0EC6 | #x3005 | [#x3031-#x3035] | * [#x309D-#x309E] | [#x30FC-#x30FE] + * @param c an UNICODE value (int) */ #define IS_EXTENDER(c) xmlIsExtenderQ(c) /** - * @param c an xmlChar value (usually an unsigned char) - * * Behaves like IS_EXTENDER but with a single-byte argument + * + * @param c an xmlChar value (usually an unsigned char) */ #define IS_EXTENDER_CH(c) xmlIsExtender_ch(c) /** - * @param c an UNICODE value (int) - * * Macro to check the following production in the XML spec: * * [86] Ideographic ::= [#x4E00-#x9FA5] | #x3007 | [#x3021-#x3029] + * @param c an UNICODE value (int) */ #define IS_IDEOGRAPHIC(c) xmlIsIdeographicQ(c) /** - * @param c an UNICODE value (int) - * * Macro to check the following production in the XML spec: * * [84] Letter ::= BaseChar | Ideographic + * @param c an UNICODE value (int) */ #define IS_LETTER(c) (IS_BASECHAR(c) || IS_IDEOGRAPHIC(c)) /** - * @param c an xmlChar value (normally unsigned char) - * * Macro behaves like IS_LETTER, but only check base chars * + * @param c an xmlChar value (normally unsigned char) */ #define IS_LETTER_CH(c) xmlIsBaseChar_ch(c) /** - * @param c an xmlChar value - * * Macro to check [a-zA-Z] * + * @param c an xmlChar value */ #define IS_ASCII_LETTER(c) ((0x61 <= ((c) | 0x20)) && \ (((c) | 0x20) <= 0x7a)) /** - * @param c an xmlChar value - * * Macro to check [0-9] * + * @param c an xmlChar value */ #define IS_ASCII_DIGIT(c) ((0x30 <= (c)) && ((c) <= 0x39)) /** - * @param c an UNICODE value (int) - * * Macro to check the following production in the XML spec: * * [13] PubidChar ::= #x20 | #xD | #xA | [a-zA-Z0-9] | * [-'()+,./:=?;!*#@$_%] + * @param c an UNICODE value (int) */ #define IS_PUBIDCHAR(c) xmlIsPubidCharQ(c) /** - * @param c an xmlChar value (normally unsigned char) - * * Same as IS_PUBIDCHAR but for single-byte value + * + * @param c an xmlChar value (normally unsigned char) */ #define IS_PUBIDCHAR_CH(c) xmlIsPubidChar_ch(c) diff --git a/include/libxml/relaxng.h b/include/libxml/relaxng.h index 8c3f9768..654244aa 100644 --- a/include/libxml/relaxng.h +++ b/include/libxml/relaxng.h @@ -30,22 +30,24 @@ typedef xmlRelaxNG *xmlRelaxNGPtr; /** - * @param ctx the validation context - * @param msg the message + * Signature of an error callback from a Relax-NG validation + * * @...: extra arguments * - * Signature of an error callback from a Relax-NG validation + * @param ctx the validation context + * @param msg the message */ typedef void (*xmlRelaxNGValidityErrorFunc) (void *ctx, const char *msg, ...) LIBXML_ATTR_FORMAT(2,3); /** - * @param ctx the validation context - * @param msg the message + * Signature of a warning callback from a Relax-NG validation + * * @...: extra arguments * - * Signature of a warning callback from a Relax-NG validation + * @param ctx the validation context + * @param msg the message */ typedef void (*xmlRelaxNGValidityWarningFunc) (void *ctx, const char *msg, diff --git a/include/libxml/schematron.h b/include/libxml/schematron.h index a1dd90fc..9b30faf1 100644 --- a/include/libxml/schematron.h +++ b/include/libxml/schematron.h @@ -42,20 +42,22 @@ typedef struct _xmlSchematron xmlSchematron; typedef xmlSchematron *xmlSchematronPtr; /** - * @param ctx the validation context - * @param msg the message + * Signature of an error callback from a Schematron validation + * * @...: extra arguments * - * Signature of an error callback from a Schematron validation + * @param ctx the validation context + * @param msg the message */ typedef void (*xmlSchematronValidityErrorFunc) (void *ctx, const char *msg, ...); /** - * @param ctx the validation context - * @param msg the message + * Signature of a warning callback from a Schematron validation + * * @...: extra arguments * - * Signature of a warning callback from a Schematron validation + * @param ctx the validation context + * @param msg the message */ typedef void (*xmlSchematronValidityWarningFunc) (void *ctx, const char *msg, ...); diff --git a/include/libxml/tree.h b/include/libxml/tree.h index 9882ec89..07dcc126 100644 --- a/include/libxml/tree.h +++ b/include/libxml/tree.h @@ -675,13 +675,12 @@ typedef struct _xmlDOMWrapCtxt xmlDOMWrapCtxt; typedef xmlDOMWrapCtxt *xmlDOMWrapCtxtPtr; /** + * A function called to acquire namespaces (xmlNs) from the wrapper. + * * @param ctxt a DOM wrapper context * @param node the context node (element or attribute) * @param nsName the requested namespace name * @param nsPrefix the requested namespace prefix - * - * A function called to acquire namespaces (xmlNs) from the wrapper. - * * @returns an xmlNsPtr or NULL in case of an error. */ typedef xmlNsPtr (*xmlDOMWrapAcquireNsFunction) (xmlDOMWrapCtxtPtr ctxt, @@ -711,16 +710,16 @@ struct _xmlDOMWrapCtxt { }; /** - * @param node the current node - * * Signature for the registration callback of a created node + * + * @param node the current node */ typedef void (*xmlRegisterNodeFunc) (xmlNodePtr node); /** - * @param node the current node - * * Signature for the deregistration callback of a discarded node + * + * @param node the current node */ typedef void (*xmlDeregisterNodeFunc) (xmlNodePtr node); diff --git a/include/libxml/valid.h b/include/libxml/valid.h index 927496b4..b212c31d 100644 --- a/include/libxml/valid.h +++ b/include/libxml/valid.h @@ -35,22 +35,22 @@ typedef struct _xmlValidState xmlValidState; typedef xmlValidState *xmlValidStatePtr; /** + * Report a validity error. + * * @param ctx user data (usually an xmlValidCtxtPtr) * @param msg printf-like format string * @param ... arguments to format - * - * Report a validity error. */ typedef void (*xmlValidityErrorFunc) (void *ctx, const char *msg, ...) LIBXML_ATTR_FORMAT(2,3); /** + * Report a validity warning. + * * @param ctx user data (usually an xmlValidCtxtPtr) * @param msg printf-like format string * @param ... arguments to format - * - * Report a validity warning. */ typedef void (*xmlValidityWarningFunc) (void *ctx, const char *msg, diff --git a/include/libxml/xlink.h b/include/libxml/xlink.h index f862809f..050d38d4 100644 --- a/include/libxml/xlink.h +++ b/include/libxml/xlink.h @@ -57,11 +57,11 @@ typedef enum { } xlinkActuate; /** - * @param ctx user data pointer - * @param node the node to check - * * This is the prototype for the link detection routine. * It calls the default link detection callbacks upon link detection. + * + * @param ctx user data pointer + * @param node the node to check */ typedef void (*xlinkNodeDetectFunc) (void *ctx, xmlNodePtr node); @@ -71,13 +71,13 @@ typedef void (*xlinkNodeDetectFunc) (void *ctx, xmlNodePtr node); */ /** + * This is the prototype for a simple link detection callback. + * * @param ctx user data pointer * @param node the node carrying the link * @param href the target of the link * @param role the role string * @param title the link title - * - * This is the prototype for a simple link detection callback. */ typedef void (*xlinkSimpleLinkFunk) (void *ctx, @@ -87,6 +87,8 @@ typedef void const xlinkTitle title); /** + * This is the prototype for a extended link detection callback. + * * @param ctx user data pointer * @param node the node carrying the link * @param nbLocators the number of locators detected on the link @@ -100,8 +102,6 @@ typedef void * @param nbTitles the number of titles detected on the link * @param titles array of titles detected on the link * @param langs array of xml:lang values for the titles - * - * This is the prototype for a extended link detection callback. */ typedef void (*xlinkExtendedLinkFunk)(void *ctx, @@ -119,6 +119,8 @@ typedef void const xmlChar **langs); /** + * This is the prototype for a extended link set detection callback. + * * @param ctx user data pointer * @param node the node carrying the link * @param nbLocators the number of locators detected on the link @@ -127,8 +129,6 @@ typedef void * @param nbTitles the number of titles detected on the link * @param titles array of titles detected on the link * @param langs array of xml:lang values for the titles - * - * This is the prototype for a extended link set detection callback. */ typedef void (*xlinkExtendedLinkSetFunk) (void *ctx, diff --git a/include/libxml/xmlIO.h b/include/libxml/xmlIO.h index 7cfe680e..5c83a88e 100644 --- a/include/libxml/xmlIO.h +++ b/include/libxml/xmlIO.h @@ -25,87 +25,78 @@ extern "C" { #endif /** - * @param filename the filename or URI - * * Callback used in the I/O Input API to detect if the current handler * can provide input functionality for this resource. * + * @param filename the filename or URI * @returns 1 if yes and 0 if another Input module should be used */ typedef int (*xmlInputMatchCallback) (char const *filename); /** - * @param filename the filename or URI - * * Callback used in the I/O Input API to open the resource * + * @param filename the filename or URI * @returns an Input context or NULL in case or error */ typedef void * (*xmlInputOpenCallback) (char const *filename); /** + * Callback used in the I/O Input API to read the resource + * * @param context an Input context * @param buffer the buffer to store data read * @param len the length of the buffer in bytes - * - * Callback used in the I/O Input API to read the resource - * * @returns the number of bytes read or -1 in case of error */ typedef int (*xmlInputReadCallback) (void * context, char * buffer, int len); /** - * @param context an Input context - * * Callback used in the I/O Input API to close the resource * + * @param context an Input context * @returns 0 or -1 in case of error */ typedef int (*xmlInputCloseCallback) (void * context); #ifdef LIBXML_OUTPUT_ENABLED /** - * @param filename the filename or URI - * * Callback used in the I/O Output API to detect if the current handler * can provide output functionality for this resource. * + * @param filename the filename or URI * @returns 1 if yes and 0 if another Output module should be used */ typedef int (*xmlOutputMatchCallback) (char const *filename); /** - * @param filename the filename or URI - * * Callback used in the I/O Output API to open the resource * + * @param filename the filename or URI * @returns an Output context or NULL in case or error */ typedef void * (*xmlOutputOpenCallback) (char const *filename); /** + * Callback used in the I/O Output API to write to the resource + * * @param context an Output context * @param buffer the buffer of data to write * @param len the length of the buffer in bytes - * - * Callback used in the I/O Output API to write to the resource - * * @returns the number of bytes written or -1 in case of error */ typedef int (*xmlOutputWriteCallback) (void * context, const char * buffer, int len); /** - * @param context an Output context - * * Callback used in the I/O Output API to close the resource * + * @param context an Output context * @returns 0 or -1 in case of error */ typedef int (*xmlOutputCloseCallback) (void * context); #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param URI the URI to read from - * @param enc the requested source encoding - * * Signature for the function doing the lookup for a suitable input method * corresponding to an URI. * + * @param URI the URI to read from + * @param enc the requested source encoding * @returns the new xmlParserInputBufferPtr in case of success or NULL if no * method was found. */ @@ -113,13 +104,12 @@ typedef xmlParserInputBufferPtr (*xmlParserInputBufferCreateFilenameFunc)(const char *URI, xmlCharEncoding enc); /** - * @param URI the URI to write to - * @param encoder the requested target encoding - * @param compression compression level - * * Signature for the function doing the lookup for a suitable output method * corresponding to an URI. * + * @param URI the URI to write to + * @param encoder the requested target encoding + * @param compression compression level * @returns the new xmlOutputBufferPtr in case of success or NULL if no * method was found. */ diff --git a/include/libxml/xmlerror.h b/include/libxml/xmlerror.h index bf8d15be..7d307c8d 100644 --- a/include/libxml/xmlerror.h +++ b/include/libxml/xmlerror.h @@ -902,22 +902,21 @@ typedef enum { } xmlParserErrors; /** - * @param ctx user data - * @param msg printf-like format string - * @param ... arguments to format - * * Generic error callback. * * @deprecated in favor of structured errors. + * @param ctx user data + * @param msg printf-like format string + * @param ... arguments to format */ typedef void (*xmlGenericErrorFunc) (void *ctx, const char *msg, ...) LIBXML_ATTR_FORMAT(2,3); /** + * Structured error callback receiving an xmlError. + * * @param userData user provided data for the error callback * @param error the error being raised - * - * Structured error callback receiving an xmlError. */ typedef void (*xmlStructuredErrorFunc) (void *userData, const xmlError *error); diff --git a/include/libxml/xmlmemory.h b/include/libxml/xmlmemory.h index d9607ec1..2c029626 100644 --- a/include/libxml/xmlmemory.h +++ b/include/libxml/xmlmemory.h @@ -26,35 +26,32 @@ extern "C" { * The XML memory wrapper support 4 basic overloadable functions. */ /** - * @param mem an already allocated block of memory - * * Signature for a free() implementation. + * + * @param mem an already allocated block of memory */ typedef void (*xmlFreeFunc)(void *mem); /** - * @param size the size requested in bytes - * * Signature for a malloc() implementation. * + * @param size the size requested in bytes * @returns a pointer to the newly allocated block or NULL in case of error. */ typedef void *(*xmlMallocFunc)(size_t size) LIBXML_ATTR_ALLOC_SIZE(1); /** - * @param mem an already allocated block of memory - * @param size the new size requested in bytes - * * Signature for a 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. */ typedef void *(*xmlReallocFunc)(void *mem, size_t size); /** - * @param str a zero terminated string - * * Signature for an strdup() implementation. * + * @param str a zero terminated string * @returns the copy of the string or NULL in case of error. */ typedef char *(*xmlStrdupFunc)(const char *str); diff --git a/include/libxml/xmlreader.h b/include/libxml/xmlreader.h index 2cc67a3d..0ad3b5c4 100644 --- a/include/libxml/xmlreader.h +++ b/include/libxml/xmlreader.h @@ -413,12 +413,12 @@ XMLPUBFUN int typedef void * xmlTextReaderLocatorPtr; /** + * Signature of an error callback from a reader parser + * * @param arg the user argument * @param msg the message * @param severity the severity of the error * @param locator a locator indicating where the error occurred - * - * Signature of an error callback from a reader parser */ typedef void (*xmlTextReaderErrorFunc)(void *arg, const char *msg, diff --git a/include/libxml/xmlregexp.h b/include/libxml/xmlregexp.h index e204ff8f..02be1302 100644 --- a/include/libxml/xmlregexp.h +++ b/include/libxml/xmlregexp.h @@ -54,12 +54,12 @@ XMLPUBFUN int xmlRegexpIsDeterminist(xmlRegexpPtr comp); /** + * Callback function when doing a transition in the automata + * * @param exec the regular expression context * @param token the current token string * @param transdata transition data * @param inputdata input data - * - * Callback function when doing a transition in the automata */ typedef void (*xmlRegExecCallbacks) (xmlRegExecCtxtPtr exec, const xmlChar *token, diff --git a/include/libxml/xmlschemas.h b/include/libxml/xmlschemas.h index e12dfcb3..8766aaae 100644 --- a/include/libxml/xmlschemas.h +++ b/include/libxml/xmlschemas.h @@ -90,21 +90,23 @@ typedef struct _xmlSchema xmlSchema; typedef xmlSchema *xmlSchemaPtr; /** - * @param ctx the validation context - * @param msg the message + * Signature of an error callback from an XSD validation + * * @...: extra arguments * - * Signature of an error callback from an XSD validation + * @param ctx the validation context + * @param msg the message */ typedef void (*xmlSchemaValidityErrorFunc) (void *ctx, const char *msg, ...) LIBXML_ATTR_FORMAT(2,3); /** - * @param ctx the validation context - * @param msg the message + * Signature of a warning callback from an XSD validation + * * @...: extra arguments * - * Signature of a warning callback from an XSD validation + * @param ctx the validation context + * @param msg the message */ typedef void (*xmlSchemaValidityWarningFunc) (void *ctx, const char *msg, ...) LIBXML_ATTR_FORMAT(2,3); @@ -119,14 +121,13 @@ typedef struct _xmlSchemaValidCtxt xmlSchemaValidCtxt; typedef xmlSchemaValidCtxt *xmlSchemaValidCtxtPtr; /** - * @param ctx user provided context - * @param file returned file information - * @param line returned line information - * * A schemas validation locator, a callback called by the validator. * This is used when file or node information are not available * to find out what file and line number are affected * + * @param ctx user provided context + * @param file returned file information + * @param line returned line information * @returns 0 in case of success and -1 in case of error */ diff --git a/include/libxml/xpath.h b/include/libxml/xpath.h index 80a11035..90073dbb 100644 --- a/include/libxml/xpath.h +++ b/include/libxml/xpath.h @@ -183,12 +183,12 @@ struct _xmlXPathAxis { }; /** - * @param ctxt the XPath interprestation context - * @param nargs the number of arguments - * * An XPath function. * The arguments (if any) are popped out from the context stack * and the result is pushed on the stack. + * + * @param ctxt the XPath interprestation context + * @param nargs the number of arguments */ typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs); @@ -198,13 +198,12 @@ typedef void (*xmlXPathFunction) (xmlXPathParserContextPtr ctxt, int nargs); */ /** - * @param ctxt an XPath context - * @param name name of the variable - * @param ns_uri the namespace name hosting this variable - * * Prototype for callbacks used to plug variable lookup in the XPath * engine. * + * @param ctxt an XPath context + * @param name name of the variable + * @param ns_uri the namespace name hosting this variable * @returns the XPath object value or NULL if not found. */ typedef xmlXPathObjectPtr (*xmlXPathVariableLookupFunc) (void *ctxt, @@ -212,13 +211,12 @@ typedef xmlXPathObjectPtr (*xmlXPathVariableLookupFunc) (void *ctxt, const xmlChar *ns_uri); /** - * @param ctxt an XPath context - * @param name name of the function - * @param ns_uri the namespace name hosting this function - * * Prototype for callbacks used to plug function lookup in the XPath * engine. * + * @param ctxt an XPath context + * @param name name of the function + * @param ns_uri the namespace name hosting this function * @returns the XPath function or NULL if not found. */ typedef xmlXPathFunction (*xmlXPathFuncLookupFunc) (void *ctxt, @@ -414,19 +412,17 @@ XMLPUBVAR double xmlXPathNINF; /* These macros may later turn into functions */ /** - * @param ns a node-set - * * Implement a functionality similar to the DOM NodeList.length. * + * @param ns a node-set * @returns the number of nodes in the node-set. */ #define xmlXPathNodeSetGetLength(ns) ((ns) ? (ns)->nodeNr : 0) /** - * @param ns a node-set - * @param index index of a node in the set - * * Implements a functionality similar to the DOM NodeList.item(). * + * @param ns a node-set + * @param index index of a node in the set * @returns the xmlNodePtr at the given `index` in `ns` or NULL if * `index` is out of range (0 to length-1) */ @@ -436,10 +432,9 @@ XMLPUBVAR double xmlXPathNINF; (ns)->nodeTab[(index)] \ : NULL) /** - * @param ns a node-set - * * Checks whether `ns` is empty or not. * + * @param ns a node-set * @returns %TRUE if `ns` is an empty node-set. */ #define xmlXPathNodeSetIsEmpty(ns) \ diff --git a/include/libxml/xpathInternals.h b/include/libxml/xpathInternals.h index 8ed655ef..5ef78e70 100644 --- a/include/libxml/xpathInternals.h +++ b/include/libxml/xpathInternals.h @@ -42,63 +42,59 @@ extern "C" { * shouldn't be used in \#ifdef's preprocessor instructions. */ /** + * Raises an error. + * * @param ctxt an XPath parser context * @param err an xmlXPathError code - * - * Raises an error. */ #define xmlXPathSetError(ctxt, err) \ { xmlXPatherror((ctxt), __FILE__, __LINE__, (err)); \ if ((ctxt) != NULL) (ctxt)->error = (err); } /** - * @param ctxt an XPath parser context - * * Raises an XPATH_INVALID_ARITY error. + * + * @param ctxt an XPath parser context */ #define xmlXPathSetArityError(ctxt) \ xmlXPathSetError((ctxt), XPATH_INVALID_ARITY) /** - * @param ctxt an XPath parser context - * * Raises an XPATH_INVALID_TYPE error. + * + * @param ctxt an XPath parser context */ #define xmlXPathSetTypeError(ctxt) \ xmlXPathSetError((ctxt), XPATH_INVALID_TYPE) /** - * @param ctxt an XPath parser context - * * Get the error code of an XPath context. * + * @param ctxt an XPath parser context * @returns the context error. */ #define xmlXPathGetError(ctxt) ((ctxt)->error) /** - * @param ctxt an XPath parser context - * * Check if an XPath error was raised. * + * @param ctxt an XPath parser context * @returns true if an error has been raised, false otherwise. */ #define xmlXPathCheckError(ctxt) ((ctxt)->error != XPATH_EXPRESSION_OK) /** - * @param ctxt an XPath parser context - * * Get the document of an XPath context. * + * @param ctxt an XPath parser context * @returns the context document. */ #define xmlXPathGetDocument(ctxt) ((ctxt)->context->doc) /** - * @param ctxt an XPath parser context - * * Get the context node of an XPath context. * + * @param ctxt an XPath parser context * @returns the context node. */ #define xmlXPathGetContextNode(ctxt) ((ctxt)->context->node) @@ -115,86 +111,85 @@ XMLPUBFUN void * xmlXPathPopExternal (xmlXPathParserContextPtr ctxt); /** + * Pushes the boolean `val` on the context stack. + * * @param ctxt an XPath parser context * @param val a boolean - * - * Pushes the boolean `val` on the context stack. */ #define xmlXPathReturnBoolean(ctxt, val) \ valuePush((ctxt), xmlXPathNewBoolean(val)) /** - * @param ctxt an XPath parser context - * * Pushes true on the context stack. + * + * @param ctxt an XPath parser context */ #define xmlXPathReturnTrue(ctxt) xmlXPathReturnBoolean((ctxt), 1) /** - * @param ctxt an XPath parser context - * * Pushes false on the context stack. + * + * @param ctxt an XPath parser context */ #define xmlXPathReturnFalse(ctxt) xmlXPathReturnBoolean((ctxt), 0) /** + * Pushes the double `val` on the context stack. + * * @param ctxt an XPath parser context * @param val a double - * - * Pushes the double `val` on the context stack. */ #define xmlXPathReturnNumber(ctxt, val) \ valuePush((ctxt), xmlXPathNewFloat(val)) /** + * Pushes the string `str` on the context stack. + * * @param ctxt an XPath parser context * @param str a string - * - * Pushes the string `str` on the context stack. */ #define xmlXPathReturnString(ctxt, str) \ valuePush((ctxt), xmlXPathWrapString(str)) /** - * @param ctxt an XPath parser context - * * Pushes an empty string on the stack. + * + * @param ctxt an XPath parser context */ #define xmlXPathReturnEmptyString(ctxt) \ valuePush((ctxt), xmlXPathNewCString("")) /** + * Pushes the node-set `ns` on the context stack. + * * @param ctxt an XPath parser context * @param ns a node-set - * - * Pushes the node-set `ns` on the context stack. */ #define xmlXPathReturnNodeSet(ctxt, ns) \ valuePush((ctxt), xmlXPathWrapNodeSet(ns)) /** - * @param ctxt an XPath parser context - * * Pushes an empty node-set on the context stack. + * + * @param ctxt an XPath parser context */ #define xmlXPathReturnEmptyNodeSet(ctxt) \ valuePush((ctxt), xmlXPathNewNodeSet(NULL)) /** + * Pushes user data on the context stack. + * * @param ctxt an XPath parser context * @param val user data - * - * Pushes user data on the context stack. */ #define xmlXPathReturnExternal(ctxt, val) \ valuePush((ctxt), xmlXPathWrapExternal(val)) /** - * @param ctxt an XPath parser context - * * Check if the current value on the XPath stack is a node set or * an XSLT value tree. * + * @param ctxt an XPath parser context * @returns true if the current object on the stack is a node-set. */ #define xmlXPathStackIsNodeSet(ctxt) \ @@ -203,11 +198,10 @@ XMLPUBFUN void * || ((ctxt)->value->type == XPATH_XSLT_TREE))) /** - * @param ctxt an XPath parser context - * * Checks if the current value on the XPath stack is an external * object. * + * @param ctxt an XPath parser context * @returns true if the current object on the stack is an external * object. */ @@ -215,9 +209,9 @@ XMLPUBFUN void * ((ctxt->value != NULL) && (ctxt->value->type == XPATH_USERS)) /** - * @param ns a node-set - * * Empties a node-set. + * + * @param ns a node-set */ #define xmlXPathEmptyNodeSet(ns) \ { while ((ns)->nodeNr > 0) (ns)->nodeTab[--(ns)->nodeNr] = NULL; } @@ -235,45 +229,45 @@ XMLPUBFUN void * if (ctxt->error != XPATH_EXPRESSION_OK) return(0) /** - * @param X the error code - * * Macro to raise an XPath error and return. + * + * @param X the error code */ #define XP_ERROR(X) \ { xmlXPathErr(ctxt, X); return; } /** - * @param X the error code - * * Macro to raise an XPath error and return 0. + * + * @param X the error code */ #define XP_ERROR0(X) \ { xmlXPathErr(ctxt, X); return(0); } /** - * @param typeval the XPath type - * * Macro to check that the value on top of the XPath stack is of a given * type. + * + * @param typeval the XPath type */ #define CHECK_TYPE(typeval) \ if ((ctxt->value == NULL) || (ctxt->value->type != typeval)) \ XP_ERROR(XPATH_INVALID_TYPE) /** - * @param typeval the XPath type - * * Macro to check that the value on top of the XPath stack is of a given * type. Return(0) in case of failure + * + * @param typeval the XPath type */ #define CHECK_TYPE0(typeval) \ if ((ctxt->value == NULL) || (ctxt->value->type != typeval)) \ XP_ERROR0(XPATH_INVALID_TYPE) /** - * @param x the number of expected args - * * Macro to check that the number of args passed to an XPath function matches. + * + * @param x the number of expected args */ #define CHECK_ARITY(x) \ if (ctxt == NULL) return; \ diff --git a/list.c b/list.c index 67fdbcfb..c94c348a 100644 --- a/list.c +++ b/list.c @@ -49,10 +49,10 @@ struct _xmlList ************************************************************************/ /** + * Unlink and deallocate `lk` from list `l` + * * @param l a list * @param lk a link - * - * Unlink and deallocate `lk` from list `l` */ static void xmlLinkDeallocator(xmlListPtr l, xmlLinkPtr lk) @@ -65,11 +65,10 @@ xmlLinkDeallocator(xmlListPtr l, xmlLinkPtr lk) } /** - * @param data0 first data - * @param data1 second data - * * Compares two arbitrary data * + * @param data0 first data + * @param data1 second data * @returns -1, 0 or 1 depending on whether data1 is greater equal or smaller * than data0 */ @@ -84,11 +83,10 @@ xmlLinkCompare(const void *data0, const void *data1) } /** - * @param l a list - * @param data a data - * * Search data in the ordered list walking from the beginning * + * @param l a list + * @param data a data * @returns the link containing the data or NULL */ static xmlLinkPtr @@ -103,11 +101,10 @@ xmlListLowerSearch(xmlListPtr l, void *data) } /** - * @param l a list - * @param data a data - * * Search data in the ordered list walking backward from the end * + * @param l a list + * @param data a data * @returns the link containing the data or NULL */ static xmlLinkPtr @@ -122,11 +119,10 @@ xmlListHigherSearch(xmlListPtr l, void *data) } /** - * @param l a list - * @param data a data - * * Search data in the list * + * @param l a list + * @param data a data * @returns the link containing the data or NULL */ static xmlLinkPtr @@ -146,11 +142,10 @@ xmlListLinkSearch(xmlListPtr l, void *data) } /** - * @param l a list - * @param data a data - * * Search data in the list processing backward * + * @param l a list + * @param data a data * @returns the link containing the data or NULL */ static xmlLinkPtr @@ -170,11 +165,10 @@ xmlListLinkReverseSearch(xmlListPtr l, void *data) } /** - * @param deallocator an optional deallocator function - * @param compare an optional comparison function - * * Create a new list * + * @param deallocator an optional deallocator function + * @param compare an optional comparison function * @returns the new list or NULL in case of error */ xmlListPtr @@ -209,11 +203,10 @@ xmlListCreate(xmlListDeallocator deallocator, xmlListDataCompare compare) } /** - * @param l a list - * @param data a search value - * * Search the list for an existing value of `data` * + * @param l a list + * @param data a search value * @returns the value associated to `data` or NULL in case of error */ void * @@ -229,11 +222,10 @@ xmlListSearch(xmlListPtr l, void *data) } /** - * @param l a list - * @param data a search value - * * Search the list in reverse order for an existing value of `data` * + * @param l a list + * @param data a search value * @returns the value associated to `data` or NULL in case of error */ void * @@ -249,11 +241,10 @@ xmlListReverseSearch(xmlListPtr l, void *data) } /** - * @param l a list - * @param data the data - * * Insert data in the ordered list at the beginning for this value * + * @param l a list + * @param data the data * @returns 0 in case of success, 1 in case of failure */ int @@ -278,11 +269,10 @@ xmlListInsert(xmlListPtr l, void *data) } /** - * @param l a list - * @param data the data - * * Insert data in the ordered list at the end for this value * + * @param l a list + * @param data the data * @returns 0 in case of success, 1 in case of failure */ int xmlListAppend(xmlListPtr l, void *data) @@ -305,9 +295,9 @@ int xmlListAppend(xmlListPtr l, void *data) } /** - * @param l a list - * * Deletes the list and its associated data + * + * @param l a list */ void xmlListDelete(xmlListPtr l) { @@ -320,11 +310,10 @@ void xmlListDelete(xmlListPtr l) } /** - * @param l a list - * @param data list data - * * Remove the first instance associated to data in the list * + * @param l a list + * @param data list data * @returns 1 if a deallocation occurred, or 0 if not found */ int @@ -344,11 +333,10 @@ xmlListRemoveFirst(xmlListPtr l, void *data) } /** - * @param l a list - * @param data list data - * * Remove the last instance associated to data in the list * + * @param l a list + * @param data list data * @returns 1 if a deallocation occurred, or 0 if not found */ int @@ -368,11 +356,10 @@ xmlListRemoveLast(xmlListPtr l, void *data) } /** - * @param l a list - * @param data list data - * * Remove the all instance associated to data in the list * + * @param l a list + * @param data list data * @returns the number of deallocation, or 0 if not found */ int @@ -389,9 +376,9 @@ xmlListRemoveAll(xmlListPtr l, void *data) } /** - * @param l a list - * * Remove the all data in the list + * + * @param l a list */ void xmlListClear(xmlListPtr l) @@ -410,10 +397,9 @@ xmlListClear(xmlListPtr l) } /** - * @param l a list - * * Is the list empty ? * + * @param l a list * @returns 1 if the list is empty, 0 if not empty and -1 in case of error */ int @@ -425,10 +411,9 @@ xmlListEmpty(xmlListPtr l) } /** - * @param l a list - * * Get the first element in the list * + * @param l a list * @returns the first element in the list, or NULL */ xmlLinkPtr @@ -440,10 +425,9 @@ xmlListFront(xmlListPtr l) } /** - * @param l a list - * * Get the last element in the list * + * @param l a list * @returns the last element in the list, or NULL */ xmlLinkPtr @@ -455,10 +439,9 @@ xmlListEnd(xmlListPtr l) } /** - * @param l a list - * * Get the number of elements in the list * + * @param l a list * @returns the number of elements in the list or -1 in case of error */ int @@ -475,9 +458,9 @@ xmlListSize(xmlListPtr l) } /** - * @param l a list - * * Removes the first element in the list + * + * @param l a list */ void xmlListPopFront(xmlListPtr l) @@ -487,9 +470,9 @@ xmlListPopFront(xmlListPtr l) } /** - * @param l a list - * * Removes the last element in the list + * + * @param l a list */ void xmlListPopBack(xmlListPtr l) @@ -499,11 +482,10 @@ xmlListPopBack(xmlListPtr l) } /** - * @param l a list - * @param data new data - * * add the new data at the beginning of the list * + * @param l a list + * @param data new data * @returns 1 if successful, 0 otherwise */ int @@ -527,11 +509,10 @@ xmlListPushFront(xmlListPtr l, void *data) } /** - * @param l a list - * @param data new data - * * add the new data at the end of the list * + * @param l a list + * @param data new data * @returns 1 if successful, 0 otherwise */ int @@ -555,10 +536,9 @@ xmlListPushBack(xmlListPtr l, void *data) } /** - * @param lk a link - * * See Returns. * + * @param lk a link * @returns a pointer to the data referenced from this link */ void * @@ -570,9 +550,9 @@ xmlLinkGetData(xmlLinkPtr lk) } /** - * @param l a list - * * Reverse the order of the elements in the list + * + * @param l a list */ void xmlListReverse(xmlListPtr l) @@ -594,9 +574,9 @@ xmlListReverse(xmlListPtr l) } /** - * @param l a list - * * Sort all the elements in the list + * + * @param l a list */ void xmlListSort(xmlListPtr l) @@ -623,12 +603,12 @@ xmlListSort(xmlListPtr l) } /** + * Walk all the element of the first from first to last and + * apply the walker function to it + * * @param l a list * @param walker a processing function * @param user a user parameter passed to the walker function - * - * Walk all the element of the first from first to last and - * apply the walker function to it */ void xmlListWalk(xmlListPtr l, xmlListWalker walker, void *user) { @@ -643,12 +623,12 @@ xmlListWalk(xmlListPtr l, xmlListWalker walker, void *user) { } /** + * Walk all the element of the list in reverse order and + * apply the walker function to it + * * @param l a list * @param walker a processing function * @param user a user parameter passed to the walker function - * - * Walk all the element of the list in reverse order and - * apply the walker function to it */ void xmlListReverseWalk(xmlListPtr l, xmlListWalker walker, void *user) { @@ -663,11 +643,11 @@ xmlListReverseWalk(xmlListPtr l, xmlListWalker walker, void *user) { } /** - * @param l1 the original list - * @param l2 the new list - * * include all the elements of the second list in the first one and * clear the second list + * + * @param l1 the original list + * @param l2 the new list */ void xmlListMerge(xmlListPtr l1, xmlListPtr l2) @@ -677,10 +657,9 @@ xmlListMerge(xmlListPtr l1, xmlListPtr l2) } /** - * @param old the list - * * Duplicate the list * + * @param old the list * @returns a new copy of the list or NULL in case of error */ xmlListPtr @@ -705,11 +684,10 @@ xmlListDup(xmlListPtr old) } /** - * @param cur the new list - * @param old the old list - * * Move all the element from the old list in the new list * + * @param cur the new list + * @param old the old list * @returns 0 in case of success 1 in case of error */ int diff --git a/nanohttp.c b/nanohttp.c index d5eecedd..c87ce445 100644 --- a/nanohttp.c +++ b/nanohttp.c @@ -29,21 +29,19 @@ xmlNanoHTTPCleanup(void) { } /** - * @param URL The proxy URL used to initialize the proxy context - * * @deprecated HTTP support was removed in 2.15. + * @param URL The proxy URL used to initialize the proxy context */ void xmlNanoHTTPScanProxy(const char *URL ATTRIBUTE_UNUSED) { } /** + * @deprecated HTTP support was removed in 2.15. + * * @param URL The URL to load * @param contentType if available the Content-Type information will be * returned at that location - * - * @deprecated HTTP support was removed in 2.15. - * * @returns NULL. */ void* @@ -53,13 +51,12 @@ xmlNanoHTTPOpen(const char *URL ATTRIBUTE_UNUSED, char **contentType) { } /** + * @deprecated HTTP support was removed in 2.15. + * * @param URL The URL to load * @param contentType if available the Content-Type information will be * returned at that location * @param redir if available the redirected URL will be returned - * - * @deprecated HTTP support was removed in 2.15. - * * @returns NULL. */ void* @@ -71,12 +68,11 @@ xmlNanoHTTPOpenRedir(const char *URL ATTRIBUTE_UNUSED, char **contentType, } /** + * @deprecated HTTP support was removed in 2.15. + * * @param ctx the HTTP context * @param dest a buffer * @param len the buffer length - * - * @deprecated HTTP support was removed in 2.15. - * * @returns -1. */ int @@ -86,15 +82,16 @@ xmlNanoHTTPRead(void *ctx ATTRIBUTE_UNUSED, void *dest ATTRIBUTE_UNUSED, } /** - * @param ctx the HTTP context - * * @deprecated HTTP support was removed in 2.15. + * @param ctx the HTTP context */ void xmlNanoHTTPClose(void *ctx ATTRIBUTE_UNUSED) { } /** + * @deprecated HTTP support was removed in 2.15. + * * @param URL The URL to load * @param method the HTTP method to use * @param input the input string if any @@ -102,9 +99,6 @@ xmlNanoHTTPClose(void *ctx ATTRIBUTE_UNUSED) { * @param redir the redirected URL OUT * @param headers the extra headers * @param ilen input length - * - * @deprecated HTTP support was removed in 2.15. - * * @returns NULL. */ void* @@ -120,15 +114,14 @@ xmlNanoHTTPMethodRedir(const char *URL ATTRIBUTE_UNUSED, } /** + * @deprecated HTTP support was removed in 2.15. + * * @param URL The URL to load * @param method the HTTP method to use * @param input the input string if any * @param contentType the Content-Type information IN and OUT * @param headers the extra headers * @param ilen input length - * - * @deprecated HTTP support was removed in 2.15. - * * @returns NULL. */ void* @@ -142,13 +135,12 @@ xmlNanoHTTPMethod(const char *URL ATTRIBUTE_UNUSED, } /** + * @deprecated HTTP support was removed in 2.15. + * * @param URL The URL to load * @param filename the filename where the content should be saved * @param contentType if available the Content-Type information will be * returned at that location - * - * @deprecated HTTP support was removed in 2.15. - * * @returns -1. */ int @@ -160,11 +152,10 @@ xmlNanoHTTPFetch(const char *URL ATTRIBUTE_UNUSED, #ifdef LIBXML_OUTPUT_ENABLED /** - * @param ctxt the HTTP context - * @param filename the filename where the content should be saved - * * @deprecated HTTP support was removed in 2.15. * + * @param ctxt the HTTP context + * @param filename the filename where the content should be saved * @returns -1. */ int @@ -175,10 +166,9 @@ xmlNanoHTTPSave(void *ctxt ATTRIBUTE_UNUSED, #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param ctx the HTTP context - * * @deprecated HTTP support was removed in 2.15. * + * @param ctx the HTTP context * @returns -1. */ int @@ -187,10 +177,9 @@ xmlNanoHTTPReturnCode(void *ctx ATTRIBUTE_UNUSED) { } /** - * @param ctx the HTTP context - * * @deprecated HTTP support was removed in 2.15. * + * @param ctx the HTTP context * @returns NULL. */ const char * @@ -199,10 +188,9 @@ xmlNanoHTTPAuthHeader(void *ctx ATTRIBUTE_UNUSED) { } /** - * @param ctx the HTTP context - * * @deprecated HTTP support was removed in 2.15. * + * @param ctx the HTTP context * @returns -1. */ int @@ -211,10 +199,9 @@ xmlNanoHTTPContentLength(void *ctx ATTRIBUTE_UNUSED) { } /** - * @param ctx the HTTP context - * * @deprecated HTTP support was removed in 2.15. * + * @param ctx the HTTP context * @returns NULL. */ const char * @@ -223,10 +210,9 @@ xmlNanoHTTPRedir(void *ctx ATTRIBUTE_UNUSED) { } /** - * @param ctx the HTTP context - * * @deprecated HTTP support was removed in 2.15. * + * @param ctx the HTTP context * @returns NULL. */ const char * @@ -235,10 +221,9 @@ xmlNanoHTTPEncoding(void *ctx ATTRIBUTE_UNUSED) { } /** - * @param ctx the HTTP context - * * @deprecated HTTP support was removed in 2.15. * + * @param ctx the HTTP context * @returns NULL. */ const char * @@ -247,10 +232,9 @@ xmlNanoHTTPMimeType(void *ctx ATTRIBUTE_UNUSED) { } /** - * @param filename the URI for matching - * * @deprecated HTTP support was removed in 2.15. * + * @param filename the URI for matching * @returns 0. */ int @@ -259,10 +243,9 @@ xmlIOHTTPMatch(const char *filename ATTRIBUTE_UNUSED) { } /** - * @param filename the URI for matching - * * @deprecated HTTP support was removed in 2.15. * + * @param filename the URI for matching * @returns NULL. */ void * @@ -272,11 +255,10 @@ xmlIOHTTPOpen(const char *filename ATTRIBUTE_UNUSED) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param post_uri The destination URI for the document - * @param compression The compression desired for the document. - * * @deprecated HTTP support was removed in 2.15. * + * @param post_uri The destination URI for the document + * @param compression The compression desired for the document. * @returns NULL. */ void * @@ -288,12 +270,11 @@ xmlIOHTTPOpenW(const char *post_uri ATTRIBUTE_UNUSED, #endif /* LIBXML_OUTPUT_ENABLED */ /** + * @deprecated HTTP support was removed in 2.15. + * * @param context the I/O context * @param buffer where to drop data * @param len number of bytes to write - * - * @deprecated HTTP support was removed in 2.15. - * * @returns -1. */ int @@ -303,10 +284,9 @@ xmlIOHTTPRead(void *context ATTRIBUTE_UNUSED, char *buffer ATTRIBUTE_UNUSED, } /** - * @param context the I/O context - * * @deprecated Internal function, don't use. * + * @param context the I/O context * @returns 0 */ int diff --git a/parser.c b/parser.c index aec8a524..babcf01a 100644 --- a/parser.c +++ b/parser.c @@ -215,11 +215,11 @@ xmlErrMemory(xmlParserCtxtPtr ctxt) { } /** + * Handle a redefinition of attribute error + * * @param ctxt an XML parser context * @param prefix the attribute prefix * @param localname the attribute localname - * - * Handle a redefinition of attribute error */ static void xmlErrAttributeDup(xmlParserCtxtPtr ctxt, const xmlChar * prefix, @@ -236,11 +236,11 @@ xmlErrAttributeDup(xmlParserCtxtPtr ctxt, const xmlChar * prefix, } /** + * Handle a fatal parser error, i.e. violating Well-Formedness constraints + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message - * - * Handle a fatal parser error, i.e. violating Well-Formedness constraints */ static void LIBXML_ATTR_FORMAT(3,0) xmlFatalErrMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -251,13 +251,13 @@ xmlFatalErrMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a warning. + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param str1 extra data * @param str2 extra data - * - * Handle a warning. */ void LIBXML_ATTR_FORMAT(3,0) xmlWarningMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -268,13 +268,13 @@ xmlWarningMsg(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a validity error. + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param str1 extra data * @param str2 extra data - * - * Handle a validity error. */ static void LIBXML_ATTR_FORMAT(3,0) xmlValidityError(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -287,12 +287,12 @@ xmlValidityError(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a fatal parser error, i.e. violating Well-Formedness constraints + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param val an integer value - * - * Handle a fatal parser error, i.e. violating Well-Formedness constraints */ static void LIBXML_ATTR_FORMAT(3,0) xmlFatalErrMsgInt(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -303,14 +303,14 @@ xmlFatalErrMsgInt(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a fatal parser error, i.e. violating Well-Formedness constraints + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param str1 an string info * @param val an integer value * @param str2 an string info - * - * Handle a fatal parser error, i.e. violating Well-Formedness constraints */ static void LIBXML_ATTR_FORMAT(3,0) xmlFatalErrMsgStrIntStr(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -322,12 +322,12 @@ xmlFatalErrMsgStrIntStr(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a fatal parser error, i.e. violating Well-Formedness constraints + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param val a string value - * - * Handle a fatal parser error, i.e. violating Well-Formedness constraints */ static void LIBXML_ATTR_FORMAT(3,0) xmlFatalErrMsgStr(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -338,12 +338,12 @@ xmlFatalErrMsgStr(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a non fatal parser error + * * @param ctxt an XML parser context * @param error the error number * @param msg the error message * @param val a string value - * - * Handle a non fatal parser error */ static void LIBXML_ATTR_FORMAT(3,0) xmlErrMsgStr(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -354,14 +354,14 @@ xmlErrMsgStr(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a fatal parser error, i.e. violating Well-Formedness constraints + * * @param ctxt an XML parser context * @param error the error number * @param msg the message * @param info1 extra information string * @param info2 extra information string * @param info3 extra information string - * - * Handle a fatal parser error, i.e. violating Well-Formedness constraints */ static void LIBXML_ATTR_FORMAT(3,0) xmlNsErr(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -376,14 +376,14 @@ xmlNsErr(xmlParserCtxtPtr ctxt, xmlParserErrors error, } /** + * Handle a namespace warning error + * * @param ctxt an XML parser context * @param error the error number * @param msg the message * @param info1 extra information string * @param info2 extra information string * @param info3 extra information string - * - * Handle a namespace warning error */ static void LIBXML_ATTR_FORMAT(3,0) xmlNsWarn(xmlParserCtxtPtr ctxt, xmlParserErrors error, @@ -412,9 +412,6 @@ xmlSaturatedAddSizeT(unsigned long *dst, unsigned long val) { } /** - * @param ctxt parser context - * @param extra sum of unexpanded entity sizes - * * Check for non-linear entity expansion behaviour. * * In some cases like xmlExpandEntityInAttValue(), this function is called @@ -432,6 +429,8 @@ xmlSaturatedAddSizeT(unsigned long *dst, unsigned long val) { * adds some fixed cost XML_ENT_FIXED_COST to discourage attacks with * short entities. * + * @param ctxt parser context + * @param extra sum of unexpanded entity sizes * @returns 1 on error, 0 on success. */ static int @@ -489,10 +488,9 @@ xmlParserEntityCheck(xmlParserCtxtPtr ctxt, unsigned long extra) ************************************************************************/ /** - * @param feature the feature to be examined - * * Examines if the library has been compiled with a given feature. * + * @param feature the feature to be examined * @returns a non-zero value if the feature exist, otherwise zero. * @returns zero (0) if the feature does not exist or an unknown * unknown feature is requested, non-zero otherwise. @@ -900,12 +898,11 @@ encoding_error: ************************************************************************/ /** - * @param ctxt an XML parser context - * * Final initialization of the parser context before starting to parse. * * This accounts for users modifying struct members of parser context * directly. + * @param ctxt an XML parser context */ static void xmlCtxtInitializeLate(xmlParserCtxtPtr ctxt) { @@ -977,9 +974,6 @@ struct _xmlDefAttrs { }; /** - * @param src the source string - * @param dst the target string - * * Normalize the space in non CDATA attribute values: * If the attribute type is not CDATA, then the XML processor MUST further * process the normalized attribute value by discarding any leading and @@ -989,6 +983,8 @@ struct _xmlDefAttrs { * to preserve dst (and it doesn't come from a dictionary or read-only) then * passing src as dst is just fine. * + * @param src the source string + * @param dst the target string * @returns a pointer to the normalized value (dst) or NULL if no conversion * is needed. */ @@ -1015,12 +1011,12 @@ xmlAttrNormalizeSpace(const xmlChar *src, xmlChar *dst) } /** + * Add a defaulted attribute for an element + * * @param ctxt an XML parser context * @param fullname the element fullname * @param fullattr the attribute fullname * @param value the attribute value - * - * Add a defaulted attribute for an element */ static void xmlAddDefAttrs(xmlParserCtxtPtr ctxt, @@ -1146,12 +1142,12 @@ mem_error: } /** + * Register this attribute type + * * @param ctxt an XML parser context * @param fullname the element fullname * @param fullattr the attribute fullname * @param type the attribute type - * - * Register this attribute type */ static void xmlAddSpecialAttr(xmlParserCtxtPtr ctxt, @@ -1189,11 +1185,11 @@ xmlCleanSpecialAttrCallback(void *payload, void *data, } /** - * @param ctxt an XML parser context - * * Trim the list of attributes defined to remove all those of type * CDATA as they are not special. This call should be done when finishing * to parse the DTD and before starting to parse the document root. + * + * @param ctxt an XML parser context */ static void xmlCleanSpecialAttr(xmlParserCtxtPtr ctxt) @@ -1210,12 +1206,10 @@ xmlCleanSpecialAttr(xmlParserCtxtPtr ctxt) } /** - * @param lang pointer to the string value + * Checks that the value conforms to the LanguageID production: * * @deprecated Internal function, do not use. * - * Checks that the value conforms to the LanguageID production: - * * NOTE: this is somewhat deprecated, those productions were removed from * the XML Second edition. * @@ -1267,6 +1261,7 @@ xmlCleanSpecialAttr(xmlParserCtxtPtr ctxt) * The parser below doesn't try to cope with extension or privateuse * that could be added but that's not interoperable anyway * + * @param lang pointer to the string value * @returns 1 if correct 0 otherwise **/ int @@ -1432,9 +1427,9 @@ xmlParserNsCreate(void) { } /** - * @param nsdb namespace database - * * Free a namespace database. + * + * @param nsdb namespace database */ void xmlParserNsFree(xmlParserNsData *nsdb) { @@ -1447,9 +1442,9 @@ xmlParserNsFree(xmlParserNsData *nsdb) { } /** - * @param nsdb namespace database - * * Reset a namespace database. + * + * @param nsdb namespace database */ static void xmlParserNsReset(xmlParserNsData *nsdb) { @@ -1465,10 +1460,9 @@ xmlParserNsReset(xmlParserNsData *nsdb) { } /** - * @param nsdb namespace database - * * Signal that a new element has started. * + * @param nsdb namespace database * @returns 0 on success, -1 if the element counter overflowed. */ static int @@ -1481,14 +1475,13 @@ xmlParserNsStartElement(xmlParserNsData *nsdb) { } /** - * @param ctxt parser context - * @param prefix namespace prefix - * @param bucketPtr optional bucket (return value) - * * Lookup namespace with given prefix. If `bucketPtr` is non-NULL, it will * be set to the matching bucket, or the first empty bucket if no match * was found. * + * @param ctxt parser context + * @param prefix namespace prefix + * @param bucketPtr optional bucket (return value) * @returns the namespace index on success, INT_MAX if no namespace was * found. */ @@ -1535,11 +1528,10 @@ xmlParserNsLookup(xmlParserCtxtPtr ctxt, const xmlHashedString *prefix, } /** - * @param ctxt parser context - * @param prefix namespace prefix - * * Lookup namespace URI with given prefix. * + * @param ctxt parser context + * @param prefix namespace prefix * @returns the namespace URI on success, NULL if no namespace was found. */ static const xmlChar * @@ -1565,12 +1557,11 @@ xmlParserNsLookupUri(xmlParserCtxtPtr ctxt, const xmlHashedString *prefix) { } /** - * @param ctxt parser context - * @param prefix namespace prefix - * * Lookup extra data for the given prefix. This returns data stored * with xmlParserNsUdpateSax(). * + * @param ctxt parser context + * @param prefix namespace prefix * @returns the data on success, NULL if no namespace was found. */ void * @@ -1594,14 +1585,13 @@ xmlParserNsLookupSax(xmlParserCtxtPtr ctxt, const xmlChar *prefix) { } /** - * @param ctxt parser context - * @param prefix namespace prefix - * @param saxData extra data for SAX handler - * * Sets or updates extra data for the given prefix. This value will be * returned by xmlParserNsLookupSax() as long as the namespace with the * given prefix is in scope. * + * @param ctxt parser context + * @param prefix namespace prefix + * @param saxData extra data for SAX handler * @returns the data on success, NULL if no namespace was found. */ int @@ -1627,10 +1617,9 @@ xmlParserNsUpdateSax(xmlParserCtxtPtr ctxt, const xmlChar *prefix, } /** - * @param ctxt parser context - * * Grows the namespace tables. * + * @param ctxt parser context * @returns 0 on success, -1 if a memory allocation failed. */ static int @@ -1664,14 +1653,13 @@ error: } /** + * Push a new namespace on the table. + * * @param ctxt parser context * @param prefix prefix with hash value * @param uri uri with hash value * @param saxData extra data for SAX handler * @param defAttr whether the namespace comes from a default attribute - * - * Push a new namespace on the table. - * * @returns 1 if the namespace was pushed, 0 if the namespace was ignored, * -1 if a memory allocation failed. */ @@ -1824,11 +1812,10 @@ populate_entry: } /** - * @param ctxt an XML parser context - * @param nr the number to pop - * * Pops the top `nr` namespaces and restores the hash table. * + * @param ctxt an XML parser context + * @param nr the number to pop * @returns the number of namespaces popped. */ static int @@ -1896,11 +1883,10 @@ mem_error: } /** - * @param ctxt an XML parser context - * @param value the parser input - * * Pushes a new parser input on top of the input stack * + * @param ctxt an XML parser context + * @param value the parser input * @returns -1 in case of error, the index in the stack otherwise */ int @@ -1967,10 +1953,9 @@ xmlCtxtPushInput(xmlParserCtxtPtr ctxt, xmlParserInputPtr value) } /** - * @param ctxt an XML parser context - * * Pops the top parser input from the input stack * + * @param ctxt an XML parser context * @returns the input just removed */ xmlParserInputPtr @@ -1993,13 +1978,12 @@ xmlCtxtPopInput(xmlParserCtxtPtr ctxt) } /** - * @param ctxt an XML parser context - * @param value the element node + * Pushes a new element node on top of the node stack * * @deprecated Internal function, do not use. * - * Pushes a new element node on top of the node stack - * + * @param ctxt an XML parser context + * @param value the element node * @returns -1 in case of error, the index in the stack otherwise */ int @@ -2039,12 +2023,11 @@ nodePush(xmlParserCtxtPtr ctxt, xmlNodePtr value) } /** - * @param ctxt an XML parser context + * Pops the top element node from the node stack * * @deprecated Internal function, do not use. * - * Pops the top element node from the node stack - * + * @param ctxt an XML parser context * @returns the node just removed */ xmlNodePtr @@ -2066,15 +2049,14 @@ nodePop(xmlParserCtxtPtr ctxt) } /** + * Pushes a new element name/prefix/URL on top of the name stack + * * @param ctxt an XML parser context * @param value the element name * @param prefix the element prefix * @param URI the element namespace name * @param line the current line number for error messages * @param nsNr the number of namespaces pushed on the namespace table - * - * Pushes a new element name/prefix/URL on top of the name stack - * * @returns -1 in case of error, the index in the stack otherwise */ static int @@ -2124,10 +2106,9 @@ mem_error: } #ifdef LIBXML_PUSH_ENABLED /** - * @param ctxt an XML parser context - * * Pops the top element/prefix/URI name from the name stack * + * @param ctxt an XML parser context * @returns the name just removed */ static const xmlChar * @@ -2149,12 +2130,11 @@ nameNsPop(xmlParserCtxtPtr ctxt) #endif /* LIBXML_PUSH_ENABLED */ /** - * @param ctxt an XML parser context + * Pops the top element name from the name stack * * @deprecated Internal function, do not use. * - * Pops the top element name from the name stack - * + * @param ctxt an XML parser context * @returns the name just removed */ static const xmlChar * @@ -2334,12 +2314,11 @@ xmlCurrentCharRecover(xmlParserCtxtPtr ctxt, int *len) { } /** - * @param ctxt the XML parser context + * Skip whitespace in the input stream. * * @deprecated Internal function, do not use. * - * Skip whitespace in the input stream. - * + * @param ctxt the XML parser context * @returns the number of space chars skipped */ int @@ -2418,11 +2397,10 @@ xmlPopPE(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt the XML parser context - * * Skip whitespace in the input stream, also handling parameter * entities. * + * @param ctxt the XML parser context * @returns the number of space chars skipped */ static int @@ -2492,10 +2470,9 @@ xmlSkipBlankCharsPE(xmlParserCtxtPtr ctxt) { ************************************************************************/ /** - * @param ctxt an XML parser context - * * @deprecated Internal function, don't use. * + * @param ctxt an XML parser context * @returns the current xmlChar in the parser context */ xmlChar @@ -2511,13 +2488,12 @@ xmlPopInput(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * @param input an XML parser input fragment (entity, XML fragment ...). + * Push an input stream onto the stack. * * @deprecated Internal function, don't use. * - * Push an input stream onto the stack. - * + * @param ctxt an XML parser context + * @param input an XML parser input fragment (entity, XML fragment ...). * @returns -1 in case of error or the index in the input stack */ int @@ -2534,12 +2510,10 @@ xmlPushInput(xmlParserCtxtPtr ctxt, xmlParserInputPtr input) { } /** - * @param ctxt an XML parser context + * Parse a numeric character reference. Always consumes '&'. * * @deprecated Internal function, don't use. * - * Parse a numeric character reference. Always consumes '&'. - * * [66] CharRef ::= '&#' [0-9]+ ';' | * '&#x' [0-9a-fA-F]+ ';' * @@ -2547,6 +2521,7 @@ xmlPushInput(xmlParserCtxtPtr ctxt, xmlParserInputPtr input) { * Characters referred to using character references must match the * production for Char. * + * @param ctxt an XML parser context * @returns the value parsed (as an int), 0 in case of error */ int @@ -2640,9 +2615,6 @@ xmlParseCharRef(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * @param str a pointer to an index in the string - * * parse Reference declarations, variant parsing from a string rather * than an an input flow. * @@ -2653,6 +2625,8 @@ xmlParseCharRef(xmlParserCtxtPtr ctxt) { * Characters referred to using character references must match the * production for Char. * + * @param ctxt an XML parser context + * @param str a pointer to an index in the string * @returns the value parsed (as an int), 0 in case of error, str will be * updated to the current value of the index */ @@ -2733,12 +2707,10 @@ xmlParseStringCharRef(xmlParserCtxtPtr ctxt, const xmlChar **str) { } /** - * @param ctxt the parser context + * [69] PEReference ::= '%' Name ';' * * @deprecated Internal function, do not use. * - * [69] PEReference ::= '%' Name ';' - * * [ WFC: No Recursion ] * A parsed entity must not contain a recursive * reference to itself, either directly or indirectly. @@ -2764,6 +2736,7 @@ xmlParseStringCharRef(xmlParserCtxtPtr ctxt, const xmlChar **str) { * i.e. * - Included in literal in entity values * - Included as Parameter Entity reference within DTDs + * @param ctxt the parser context */ void xmlParserHandlePEReference(xmlParserCtxtPtr ctxt) { @@ -2771,6 +2744,8 @@ xmlParserHandlePEReference(xmlParserCtxtPtr ctxt) { } /** + * @deprecated Internal function, don't use. + * * @param ctxt the parser context * @param str the input string * @param len the string length @@ -2778,9 +2753,6 @@ xmlParserHandlePEReference(xmlParserCtxtPtr ctxt) { * @param end an end marker xmlChar, 0 if none * @param end2 an end marker xmlChar, 0 if none * @param end3 an end marker xmlChar, 0 if none - * - * @deprecated Internal function, don't use. - * * @returns A newly allocated string with the substitution done. The caller * must deallocate it ! */ @@ -2799,15 +2771,14 @@ xmlStringLenDecodeEntities(xmlParserCtxtPtr ctxt, const xmlChar *str, int len, } /** + * @deprecated Internal function, don't use. + * * @param ctxt the parser context * @param str the input string * @param what combination of XML_SUBSTITUTE_REF and XML_SUBSTITUTE_PEREF * @param end an end marker xmlChar, 0 if none * @param end2 an end marker xmlChar, 0 if none * @param end3 an end marker xmlChar, 0 if none - * - * @deprecated Internal function, don't use. - * * @returns A newly allocated string with the substitution done. The caller * must deallocate it ! */ @@ -2831,13 +2802,12 @@ xmlStringDecodeEntities(xmlParserCtxtPtr ctxt, const xmlChar *str, ************************************************************************/ /** + * Is this a sequence of blank chars that one can ignore ? + * * @param ctxt an XML parser context * @param str a xmlChar * * @param len the size of `str` * @param blank_chars we know the chars are blanks - * - * Is this a sequence of blank chars that one can ignore ? - * * @returns 1 if ignorable 0 otherwise. */ @@ -2918,20 +2888,19 @@ static int areBlanks(xmlParserCtxtPtr ctxt, const xmlChar *str, int len, ************************************************************************/ /** - * @param ctxt an XML parser context - * @param name an XML parser context - * @param prefixOut a xmlChar ** + * parse an UTF8 encoded XML qualified name string * * @deprecated Don't use. * - * parse an UTF8 encoded XML qualified name string - * * [NS 5] QName ::= (Prefix ':')? LocalPart * * [NS 6] Prefix ::= NCName * * [NS 7] LocalPart ::= NCName * + * @param ctxt an XML parser context + * @param name an XML parser context + * @param prefixOut a xmlChar ** * @returns the local part, and prefix is updated * to get the Prefix if any. */ @@ -3316,12 +3285,10 @@ xmlParseNameComplex(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context + * parse an XML name. * * @deprecated Internal function, don't use. * - * parse an XML name. - * * [4] NameChar ::= Letter | Digit | '.' | '-' | '_' | ':' | * CombiningChar | Extender * @@ -3329,6 +3296,7 @@ xmlParseNameComplex(xmlParserCtxtPtr ctxt) { * * [6] Names ::= Name (#x20 Name)* * + * @param ctxt an XML parser context * @returns the Name parsed or NULL */ @@ -3416,8 +3384,6 @@ xmlParseNCNameComplex(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * * parse an XML name. * * [4NS] NCNameChar ::= Letter | Digit | '.' | '-' | '_' | @@ -3425,6 +3391,7 @@ xmlParseNCNameComplex(xmlParserCtxtPtr ctxt) { * * [5NS] NCName ::= (Letter | '_') (NCNameChar)* * + * @param ctxt an XML parser context * @returns the Name parsed or NULL */ @@ -3476,12 +3443,11 @@ complex: } /** - * @param ctxt an XML parser context - * @param other the name to compare with - * * parse an XML name and compares for match * (specialized for endtag parsing) * + * @param ctxt an XML parser context + * @param other the name to compare with * @returns NULL for an illegal name, (xmlChar*) 1 for success * and the name for mismatch */ @@ -3515,9 +3481,6 @@ xmlParseNameAndCompare(xmlParserCtxtPtr ctxt, xmlChar const *other) { } /** - * @param ctxt an XML parser context - * @param str a pointer to the string pointer (IN/OUT) - * * parse an XML name. * * [4] NameChar ::= Letter | Digit | '.' | '-' | '_' | ':' | @@ -3527,6 +3490,8 @@ xmlParseNameAndCompare(xmlParserCtxtPtr ctxt, xmlChar const *other) { * * [6] Names ::= Name (#x20 Name)* * + * @param ctxt an XML parser context + * @param str a pointer to the string pointer (IN/OUT) * @returns the Name parsed or NULL. The `str` pointer * is updated to the current location in the string. */ @@ -3609,16 +3574,15 @@ xmlParseStringName(xmlParserCtxtPtr ctxt, const xmlChar** str) { } /** - * @param ctxt an XML parser context + * parse an XML Nmtoken. * * @deprecated Internal function, don't use. * - * parse an XML Nmtoken. - * * [7] Nmtoken ::= (NameChar)+ * * [8] Nmtokens ::= Nmtoken (#x20 Nmtoken)* * + * @param ctxt an XML parser context * @returns the Nmtoken parsed or NULL */ @@ -3693,13 +3657,13 @@ xmlParseNmtoken(xmlParserCtxtPtr ctxt) { } /** + * Validate an entity value and expand parameter entities. + * * @param ctxt parser context * @param buf string buffer * @param str entity value * @param length size of entity value * @param depth nesting depth - * - * Validate an entity value and expand parameter entities. */ static void xmlExpandPEsInEntityValue(xmlParserCtxtPtr ctxt, xmlSBuf *buf, @@ -3841,16 +3805,15 @@ xmlExpandPEsInEntityValue(xmlParserCtxtPtr ctxt, xmlSBuf *buf, } /** - * @param ctxt an XML parser context - * @param orig if non-NULL store a copy of the original entity value + * parse a value for ENTITY declarations * * @deprecated Internal function, don't use. * - * parse a value for ENTITY declarations - * * [9] EntityValue ::= '"' ([^%&"] | PEReference | Reference)* '"' | * "'" ([^%&'] | PEReference | Reference)* "'" * + * @param ctxt an XML parser context + * @param orig if non-NULL store a copy of the original entity value * @returns the EntityValue parsed with reference substituted or NULL */ xmlChar * @@ -3928,12 +3891,12 @@ error: } /** + * Check an entity reference in an attribute value for validity + * without expanding it. + * * @param ctxt parser context * @param pent entity * @param depth nesting depth - * - * Check an entity reference in an attribute value for validity - * without expanding it. */ static void xmlCheckEntityInAttValue(xmlParserCtxtPtr ctxt, xmlEntityPtr pent, int depth) { @@ -4031,6 +3994,9 @@ done: } /** + * Expand general entity references in an entity or attribute value. + * Perform attribute value normalization. + * * @param ctxt parser context * @param buf string buffer * @param str entity or attribute value @@ -4039,9 +4005,6 @@ done: * @param inSpace whitespace state * @param depth nesting depth * @param check whether to check for amplification - * - * Expand general entity references in an entity or attribute value. - * Perform attribute value normalization. */ static void xmlExpandEntityInAttValue(xmlParserCtxtPtr ctxt, xmlSBuf *buf, @@ -4192,13 +4155,12 @@ xmlExpandEntityInAttValue(xmlParserCtxtPtr ctxt, xmlSBuf *buf, } /** - * @param ctxt parser context - * @param str entity or attribute value - * @param normalize whether to collapse whitespace - * * Expand general entity references in an entity or attribute value. * Perform attribute value normalization. * + * @param ctxt parser context + * @param str entity or attribute value + * @param normalize whether to collapse whitespace * @returns the expanded attribtue value. */ xmlChar * @@ -4222,12 +4184,6 @@ xmlExpandEntitiesInAttValue(xmlParserCtxtPtr ctxt, const xmlChar *str, } /** - * @param ctxt an XML parser context - * @param attlen attribute len result - * @param alloc whether the attribute was reallocated as a new string - * @param normalize if 1 then further non-CDATA normalization must be done - * @param isNamespace whether this is a namespace declaration - * * parse a value for an attribute. * * NOTE: if no normalization is needed, the routine will return pointers @@ -4255,6 +4211,11 @@ xmlExpandEntitiesInAttValue(xmlParserCtxtPtr ctxt, const xmlChar *str, * All attributes for which no declaration has been read should be treated * by a non-validating parser as if declared CDATA. * + * @param ctxt an XML parser context + * @param attlen attribute len result + * @param alloc whether the attribute was reallocated as a new string + * @param normalize if 1 then further non-CDATA normalization must be done + * @param isNamespace whether this is a namespace declaration * @returns the AttValue parsed or NULL. The value has to be freed by the * caller if it was copied, this can be detected by val[*len] == 0. */ @@ -4490,14 +4451,12 @@ error: } /** - * @param ctxt an XML parser context - * - * @deprecated Internal function, don't use. - * * parse a value for an attribute * Note: the parser won't do substitution of entities here, this * will be handled later in xmlStringGetNodeList() * + * @deprecated Internal function, don't use. + * * [10] AttValue ::= '"' ([^<&"] | Reference)* '"' | * "'" ([^<&'] | Reference)* "'" * @@ -4523,6 +4482,7 @@ error: * All attributes for which no declaration has been read should be treated * by a non-validating parser as if declared CDATA. * + * @param ctxt an XML parser context * @returns the AttValue parsed or NULL. The value has to be freed by the * caller. */ @@ -4533,14 +4493,13 @@ xmlParseAttValue(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context + * parse an XML Literal * * @deprecated Internal function, don't use. * - * parse an XML Literal - * * [11] SystemLiteral ::= ('"' [^"]* '"') | ("'" [^']* "'") * + * @param ctxt an XML parser context * @returns the SystemLiteral parsed or NULL */ @@ -4606,14 +4565,13 @@ xmlParseSystemLiteral(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context + * parse an XML public literal * * @deprecated Internal function, don't use. * - * parse an XML public literal - * * [12] PubidLiteral ::= '"' PubidChar* '"' | "'" (PubidChar - "'")* "'" * + * @param ctxt an XML parser context * @returns the PubidLiteral parsed or NULL. */ @@ -4753,9 +4711,6 @@ xmlCharacters(xmlParserCtxtPtr ctxt, const xmlChar *buf, int size, } /** - * @param ctxt an XML parser context - * @param partial buffer may contain partial UTF-8 sequences - * * Parse character data. Always makes progress if the first char isn't * '<' or '&'. * @@ -4765,6 +4720,8 @@ xmlCharacters(xmlParserCtxtPtr ctxt, const xmlChar *buf, int size, * string is not marking the end of a CDATA section. * * [14] CharData ::= [^<&]* - ([^<&]* ']]>' [^<&]*) + * @param ctxt an XML parser context + * @param partial buffer may contain partial UTF-8 sequences */ static void xmlParseCharDataInternal(xmlParserCtxtPtr ctxt, int partial) { @@ -4868,14 +4825,13 @@ get_more: } /** - * @param ctxt an XML parser context - * @param partial whether the input can end with truncated UTF-8 - * * Always makes progress if the first char isn't '<' or '&'. * * parse a CharData section.this is the fallback function * of xmlParseCharData() when the parsing requires handling * of non-ASCII characters. + * @param ctxt an XML parser context + * @param partial whether the input can end with truncated UTF-8 */ static void xmlParseCharDataComplex(xmlParserCtxtPtr ctxt, int partial) { @@ -4933,10 +4889,9 @@ xmlParseCharDataComplex(xmlParserCtxtPtr ctxt, int partial) { } /** + * @deprecated Internal function, don't use. * @param ctxt an XML parser context * @param cdata unused - * - * @deprecated Internal function, don't use. */ void xmlParseCharData(xmlParserCtxtPtr ctxt, ATTRIBUTE_UNUSED int cdata) { @@ -4944,15 +4899,10 @@ xmlParseCharData(xmlParserCtxtPtr ctxt, ATTRIBUTE_UNUSED int cdata) { } /** - * @param ctxt an XML parser context - * @param publicID a xmlChar** receiving PubidLiteral - * @param strict indicate whether we should restrict parsing to only - * production [75], see NOTE below + * Parse an External ID or a Public ID * * @deprecated Internal function, don't use. * - * Parse an External ID or a Public ID - * * NOTE: Productions [75] and [83] interact badly since [75] can generate * `'PUBLIC' S PubidLiteral S SystemLiteral` * @@ -4961,6 +4911,10 @@ xmlParseCharData(xmlParserCtxtPtr ctxt, ATTRIBUTE_UNUSED int cdata) { * * [83] PublicID ::= 'PUBLIC' S PubidLiteral * + * @param ctxt an XML parser context + * @param publicID a xmlChar** receiving PubidLiteral + * @param strict indicate whether we should restrict parsing to only + * production [75], see NOTE below * @returns the function returns SystemLiteral and in the second * case publicID receives PubidLiteral, is strict is off * it is possible to return NULL and have publicID set. @@ -5018,17 +4972,16 @@ xmlParseExternalID(xmlParserCtxtPtr ctxt, xmlChar **publicID, int strict) { } /** - * @param ctxt an XML parser context - * @param buf the already parsed part of the buffer - * @param len number of bytes in the buffer - * @param size allocated size of the buffer - * * Skip an XML (SGML) comment * The spec says that "For compatibility, the string "--" (double-hyphen) * must not occur within comments. " * This is the slow routine in case the accelerator for ascii didn't work * * [15] Comment ::= '' + * @param ctxt an XML parser context + * @param buf the already parsed part of the buffer + * @param len number of bytes in the buffer + * @param size allocated size of the buffer */ static void xmlParseCommentComplex(xmlParserCtxtPtr ctxt, xmlChar *buf, @@ -5134,16 +5087,15 @@ not_terminated: } /** - * @param ctxt an XML parser context + * Parse an XML (SGML) comment. Always consumes '' + * @param ctxt an XML parser context */ void xmlParseComment(xmlParserCtxtPtr ctxt) { @@ -5287,14 +5239,13 @@ get_more: /** - * @param ctxt an XML parser context + * parse the name of a PI * * @deprecated Internal function, don't use. * - * parse the name of a PI - * * [17] PITarget ::= Name - (('X' | 'x') ('M' | 'm') ('L' | 'l')) * + * @param ctxt an XML parser context * @returns the PITarget name or NULL */ @@ -5335,9 +5286,6 @@ xmlParsePITarget(xmlParserCtxtPtr ctxt) { #ifdef LIBXML_CATALOG_ENABLED /** - * @param ctxt an XML parser context - * @param catalog the PI value string - * * parse an XML Catalog Processing Instruction. * * @@ -5346,6 +5294,8 @@ xmlParsePITarget(xmlParserCtxtPtr ctxt) { * part of the document before any doctype information * This will add the given catalog to the parsing context in order * to be used if there is a resolution need further down in the document + * @param ctxt an XML parser context + * @param catalog the PI value string */ static void @@ -5401,15 +5351,14 @@ error: #endif /** - * @param ctxt an XML parser context + * parse an XML Processing Instruction. * * @deprecated Internal function, don't use. * - * parse an XML Processing Instruction. - * * [16] PI ::= '' Char*)))? '?>' * * The processing is transferred to SAX once parsed. + * @param ctxt an XML parser context */ void @@ -5518,12 +5467,10 @@ xmlParsePI(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context + * Parse a notation declaration. Always consumes '' * @@ -5534,6 +5481,7 @@ xmlParsePI(xmlParserCtxtPtr ctxt) { * 'SYSTEM' S SystemLiteral * * See the NOTE on xmlParseExternalID(). + * @param ctxt an XML parser context */ void @@ -5596,12 +5544,10 @@ xmlParseNotationDecl(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context + * Parse an entity declaration. Always consumes '' @@ -5616,6 +5562,7 @@ xmlParseNotationDecl(xmlParserCtxtPtr ctxt) { * * [ VC: Notation Declared ] * The Name must match the declared name of a notation. + * @param ctxt an XML parser context */ void @@ -5837,13 +5784,10 @@ done: } /** - * @param ctxt an XML parser context - * @param value Receive a possible fixed default value for the attribute + * Parse an attribute default declaration * * @deprecated Internal function, don't use. * - * Parse an attribute default declaration - * * [60] DefaultDecl ::= '#REQUIRED' | '#IMPLIED' | (('#FIXED' S)? AttValue) * * [ VC: Required Attribute ] @@ -5862,6 +5806,8 @@ done: * [ WFC: No < in Attribute Values ] * handled in xmlParseAttValue() * + * @param ctxt an XML parser context + * @param value Receive a possible fixed default value for the attribute * @returns XML_ATTRIBUTE_NONE, XML_ATTRIBUTE_REQUIRED, XML_ATTRIBUTE_IMPLIED * or XML_ATTRIBUTE_FIXED. */ @@ -5899,12 +5845,10 @@ xmlParseDefaultDecl(xmlParserCtxtPtr ctxt, xmlChar **value) { } /** - * @param ctxt an XML parser context + * parse an Notation attribute type. * * @deprecated Internal function, don't use. * - * parse an Notation attribute type. - * * Note: the leading 'NOTATION' S part has already being parsed... * * [58] NotationType ::= 'NOTATION' S '(' S? Name (S? '|' S? Name)* S? ')' @@ -5913,6 +5857,7 @@ xmlParseDefaultDecl(xmlParserCtxtPtr ctxt, xmlChar **value) { * Values of this type must match one of the notation names included * in the declaration; all notation names in the declaration must be declared. * + * @param ctxt an XML parser context * @returns the notation attribute tree built while parsing */ @@ -5972,18 +5917,17 @@ xmlParseNotationType(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context + * parse an Enumeration attribute type. * * @deprecated Internal function, don't use. * - * parse an Enumeration attribute type. - * * [59] Enumeration ::= '(' S? Nmtoken (S? '|' S? Nmtoken)* S? ')' * * [ VC: Enumeration ] * Values of this type must match one of the Nmtoken tokens in * the declaration * + * @param ctxt an XML parser context * @returns the enumeration attribute tree built while parsing */ @@ -6042,17 +5986,16 @@ xmlParseEnumerationType(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * @param tree the enumeration tree built while parsing + * parse an Enumerated attribute type. * * @deprecated Internal function, don't use. * - * parse an Enumerated attribute type. - * * [57] EnumeratedType ::= NotationType | Enumeration * * [58] NotationType ::= 'NOTATION' S '(' S? Name (S? '|' S? Name)* S? ')' * + * @param ctxt an XML parser context + * @param tree the enumeration tree built while parsing * @returns XML_ATTRIBUTE_ENUMERATION or XML_ATTRIBUTE_NOTATION */ @@ -6075,13 +6018,10 @@ xmlParseEnumeratedType(xmlParserCtxtPtr ctxt, xmlEnumerationPtr *tree) { } /** - * @param ctxt an XML parser context - * @param tree the enumeration tree built while parsing + * parse the Attribute list def for an element * * @deprecated Internal function, don't use. * - * parse the Attribute list def for an element - * * [54] AttType ::= StringType | TokenizedType | EnumeratedType * * [55] StringType ::= 'CDATA' @@ -6118,6 +6058,8 @@ xmlParseEnumeratedType(xmlParserCtxtPtr ctxt, xmlEnumerationPtr *tree) { * Values of type NMTOKEN must match the Nmtoken production; values * of type NMTOKENS must match Nmtokens. * + * @param ctxt an XML parser context + * @param tree the enumeration tree built while parsing * @returns the attribute type */ int @@ -6151,15 +6093,14 @@ xmlParseAttributeType(xmlParserCtxtPtr ctxt, xmlEnumerationPtr *tree) { } /** - * @param ctxt an XML parser context + * Parse an attribute list declaration for an element. Always consumes '' * * [53] AttDef ::= S Name S AttType S DefaultDecl + * @param ctxt an XML parser context */ void xmlParseAttributeListDecl(xmlParserCtxtPtr ctxt) { @@ -6275,14 +6216,11 @@ xmlParseAttributeListDecl(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * @param inputchk the input used for the current entity, needed for boundary checks - * - * @deprecated Internal function, don't use. - * * parse the declaration for a Mixed Element content * The leading '(' and spaces have been skipped in xmlParseElementContentDecl() * + * @deprecated Internal function, don't use. + * * [51] Mixed ::= '(' S? '#PCDATA' (S? '|' S? Name)* S? ')*' | * '(' S? '#PCDATA' S? ')' * @@ -6292,6 +6230,8 @@ xmlParseAttributeListDecl(xmlParserCtxtPtr ctxt) { * The same name must not appear more than once in a single * mixed-content declaration. * + * @param ctxt an XML parser context + * @param inputchk the input used for the current entity, needed for boundary checks * @returns the list of the xmlElementContentPtr describing the element choices */ xmlElementContentPtr @@ -6388,10 +6328,6 @@ mem_error: } /** - * @param ctxt an XML parser context - * @param inputchk the input used for the current entity, needed for boundary checks - * @param depth the level of recursion - * * parse the declaration for a Mixed Element content * The leading '(' and spaces have been skipped in xmlParseElementContentDecl() * @@ -6414,6 +6350,9 @@ mem_error: * be empty, and neither the first nor last non-blank character of * the replacement text should be a connector (| or ,). * + * @param ctxt an XML parser context + * @param inputchk the input used for the current entity, needed for boundary checks + * @param depth the level of recursion * @returns the tree of xmlElementContentPtr describing the element * hierarchy. */ @@ -6693,14 +6632,11 @@ xmlParseElementChildrenContentDeclPriv(xmlParserCtxtPtr ctxt, int inputchk, } /** - * @param ctxt an XML parser context - * @param inputchk the input used for the current entity, needed for boundary checks - * - * @deprecated Internal function, don't use. - * * parse the declaration for a Mixed Element content * The leading '(' and spaces have been skipped in xmlParseElementContentDecl() * + * @deprecated Internal function, don't use. + * * [47] children ::= (choice | seq) ('?' | '*' | '+')? * * [48] cp ::= (Name | choice | seq) ('?' | '*' | '+')? @@ -6720,6 +6656,8 @@ xmlParseElementChildrenContentDeclPriv(xmlParserCtxtPtr ctxt, int inputchk, * be empty, and neither the first nor last non-blank character of * the replacement text should be a connector (| or ,). * + * @param ctxt an XML parser context + * @param inputchk the input used for the current entity, needed for boundary checks * @returns the tree of xmlElementContentPtr describing the element * hierarchy. */ @@ -6730,17 +6668,16 @@ xmlParseElementChildrenContentDecl(xmlParserCtxtPtr ctxt, int inputchk) { } /** - * @param ctxt an XML parser context - * @param name the name of the element being defined. - * @param result the Element Content pointer will be stored here if any - * - * @deprecated Internal function, don't use. - * * parse the declaration for an Element content either Mixed or Children, * the cases EMPTY and ANY are handled directly in xmlParseElementDecl() * + * @deprecated Internal function, don't use. + * * [46] contentspec ::= 'EMPTY' | 'ANY' | Mixed | children * + * @param ctxt an XML parser context + * @param name the name of the element being defined. + * @param result the Element Content pointer will be stored here if any * @returns the type of element content XML_ELEMENT_TYPE_xxx */ @@ -6775,17 +6712,16 @@ xmlParseElementContentDecl(xmlParserCtxtPtr ctxt, const xmlChar *name, } /** - * @param ctxt an XML parser context + * Parse an element declaration. Always consumes '' * * [ VC: Unique Element Type Declaration ] * No element type may be declared more than once * + * @param ctxt an XML parser context * @returns the type of the element, or -1 in case of error */ int @@ -6881,8 +6817,6 @@ xmlParseElementDecl(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * * Parse a conditional section. Always consumes '' * Ignore)* * [65] Ignore ::= Char* - (Char* ('') Char*) + * @param ctxt an XML parser context */ static void @@ -7024,12 +6959,10 @@ error: } /** - * @param ctxt an XML parser context + * Parse markup declarations. Always consumes '' + * @param ctxt an XML parser context */ void @@ -7156,18 +7089,17 @@ xmlParseTextDecl(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * @param ExternalID the external identifier - * @param SystemID the system identifier (or URL) + * parse Markup declarations from an external subset * * @deprecated Internal function, don't use. * - * parse Markup declarations from an external subset - * * [30] extSubset ::= textDecl? extSubsetDecl * * [31] extSubsetDecl ::= (markupdecl | conditionalSect | * PEReference | S) * + * @param ctxt an XML parser context + * @param ExternalID the external identifier + * @param SystemID the system identifier (or URL) */ void xmlParseExternalSubset(xmlParserCtxtPtr ctxt, const xmlChar *ExternalID, @@ -7221,18 +7153,17 @@ xmlParseExternalSubset(xmlParserCtxtPtr ctxt, const xmlChar *ExternalID, } /** - * @param ctxt an XML parser context - * - * @deprecated Internal function, don't use. - * * parse and handle entity references in content, depending on the SAX * interface, this may end-up in a call to character() if this is a * CharRef, a predefined entity, if there is no reference() callback. * or if the parser was asked to switch to that mode. * + * @deprecated Internal function, don't use. + * * Always consumes '&'. * * [67] Reference ::= EntityRef | CharRef + * @param ctxt an XML parser context */ void xmlParseReference(xmlParserCtxtPtr ctxt) { @@ -7590,12 +7521,11 @@ xmlLookupGeneralEntity(xmlParserCtxtPtr ctxt, const xmlChar *name, int inAttr) { } /** - * @param ctxt an XML parser context - * * Parse an entity reference. Always consumes '&'. * * [68] EntityRef ::= '&' Name ';' * + * @param ctxt an XML parser context * @returns the name, or NULL in case of error. */ static const xmlChar * @@ -7623,10 +7553,9 @@ xmlParseEntityRefInternal(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * * @deprecated Internal function, don't use. * + * @param ctxt an XML parser context * @returns the xmlEntityPtr if found, or NULL otherwise. */ xmlEntityPtr @@ -7644,9 +7573,6 @@ xmlParseEntityRef(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * @param str a pointer to an index in the string - * * parse ENTITY references declarations, but this version parses it from * a string value. * @@ -7670,6 +7596,8 @@ xmlParseEntityRef(xmlParserCtxtPtr ctxt) { * [ WFC: Parsed Entity ] * An entity reference must not contain the name of an unparsed entity * + * @param ctxt an XML parser context + * @param str a pointer to an index in the string * @returns the xmlEntityPtr if found, or NULL otherwise. The str pointer * is updated to the current location in the string. */ @@ -7707,12 +7635,10 @@ xmlParseStringEntityRef(xmlParserCtxtPtr ctxt, const xmlChar ** str) { } /** - * @param ctxt an XML parser context + * Parse a parameter entity reference. Always consumes '%'. * * @deprecated Internal function, don't use. * - * Parse a parameter entity reference. Always consumes '%'. - * * The entity content is handled directly by pushing it's content as * a new input stream. * @@ -7736,6 +7662,7 @@ xmlParseStringEntityRef(xmlParserCtxtPtr ctxt, const xmlChar ** str) { * [ WFC: In DTD ] * Parameter-entity references may only appear in the DTD. * NOTE: misleading but this is handled. + * @param ctxt an XML parser context */ void xmlParsePEReference(xmlParserCtxtPtr ctxt) @@ -7817,11 +7744,10 @@ xmlParsePEReference(xmlParserCtxtPtr ctxt) } /** - * @param ctxt an XML parser context - * @param entity an unloaded system entity - * * Load the content of an entity. * + * @param ctxt an XML parser context + * @param entity an unloaded system entity * @returns 0 in case of success and -1 in case of failure */ static int @@ -7959,9 +7885,6 @@ error: } /** - * @param ctxt an XML parser context - * @param str a pointer to an index in the string - * * parse PEReference declarations * * [69] PEReference ::= '%' Name ';' @@ -7985,6 +7908,8 @@ error: * Parameter-entity references may only appear in the DTD. * NOTE: misleading but this is handled. * + * @param ctxt an XML parser context + * @param str a pointer to an index in the string * @returns the string of the entity content. * str is updated to the current value of the index */ @@ -8047,18 +7972,17 @@ xmlParseStringPEReference(xmlParserCtxtPtr ctxt, const xmlChar **str) { } /** - * @param ctxt an XML parser context + * parse a DOCTYPE declaration * * @deprecated Internal function, don't use. * - * parse a DOCTYPE declaration - * * [28] doctypedecl ::= '' * * [ VC: Root Element Type ] * The Name in the document type declaration must match the element * type of the root element. + * @param ctxt an XML parser context */ void @@ -8115,11 +8039,10 @@ xmlParseDocTypeDecl(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * * parse the internal subset declaration * * [28 end] ('[' (markupdecl | PEReference | S)* ']' S?)? '>' + * @param ctxt an XML parser context */ static void @@ -8181,13 +8104,10 @@ xmlParseInternalSubset(xmlParserCtxtPtr ctxt) { #ifdef LIBXML_SAX1_ENABLED /** - * @param ctxt an XML parser context - * @param value a xmlChar ** used to store the value of the attribute + * parse an attribute * * @deprecated Internal function, don't use. * - * parse an attribute - * * [41] Attribute ::= Name Eq AttValue * * [ WFC: No External Entity References ] @@ -8211,6 +8131,8 @@ xmlParseInternalSubset(xmlParserCtxtPtr ctxt) { * Also the case QName == xmlns:??? is handled independently as a namespace * definition. * + * @param ctxt an XML parser context + * @param value a xmlChar ** used to store the value of the attribute * @returns the attribute name, and the value in *value. */ @@ -8275,12 +8197,10 @@ xmlParseAttribute(xmlParserCtxtPtr ctxt, xmlChar **value) { } /** - * @param ctxt an XML parser context + * Parse a start tag. Always consumes '<'. * * @deprecated Internal function, don't use. * - * Parse a start tag. Always consumes '<'. - * * [40] STag ::= '<' Name (S Attribute)* S? '>' * * [ WFC: Unique Att Spec ] @@ -8299,6 +8219,7 @@ xmlParseAttribute(xmlParserCtxtPtr ctxt, xmlChar **value) { * * [NS 10] EmptyElement ::= '<' QName (S Attribute)* S? '/>' * + * @param ctxt an XML parser context * @returns the element name parsed */ @@ -8421,9 +8342,6 @@ failed: } /** - * @param ctxt an XML parser context - * @param line line of the start tag - * * Parse an end tag. Always consumes '' @@ -8431,6 +8349,8 @@ failed: * With namespace * * [NS 9] ETag ::= '' + * @param ctxt an XML parser context + * @param line line of the start tag */ static void @@ -8482,17 +8402,16 @@ xmlParseEndTag1(xmlParserCtxtPtr ctxt, int line) { } /** - * @param ctxt an XML parser context + * parse an end of tag * * @deprecated Internal function, don't use. * - * parse an end of tag - * * [42] ETag ::= '' * * With namespace * * [NS 9] ETag ::= '' + * @param ctxt an XML parser context */ void @@ -8508,15 +8427,14 @@ xmlParseEndTag(xmlParserCtxtPtr ctxt) { ************************************************************************/ /** - * @param ctxt an XML parser context - * @param prefix pointer to store the prefix part - * * parse an XML Namespace QName * * [6] QName ::= (Prefix ':')? LocalPart * [7] Prefix ::= NCName * [8] LocalPart ::= NCName * + * @param ctxt an XML parser context + * @param prefix pointer to store the prefix part * @returns the Name parsed or NULL */ @@ -8565,15 +8483,14 @@ xmlParseQNameHashed(xmlParserCtxtPtr ctxt, xmlHashedString *prefix) { } /** - * @param ctxt an XML parser context - * @param prefix pointer to store the prefix part - * * parse an XML Namespace QName * * [6] QName ::= (Prefix ':')? LocalPart * [7] Prefix ::= NCName * [8] LocalPart ::= NCName * + * @param ctxt an XML parser context + * @param prefix pointer to store the prefix part * @returns the Name parsed or NULL */ @@ -8589,13 +8506,12 @@ xmlParseQName(xmlParserCtxtPtr ctxt, const xmlChar **prefix) { } /** - * @param ctxt an XML parser context - * @param name the localname - * @param prefix the prefix, if any. - * * parse an XML name and compares for match * (specialized for endtag parsing) * + * @param ctxt an XML parser context + * @param name the localname + * @param prefix the prefix, if any. * @returns NULL for an illegal name, (xmlChar*) 1 for success * and the name for mismatch */ @@ -8644,6 +8560,8 @@ xmlParseQNameAndCompare(xmlParserCtxtPtr ctxt, xmlChar const *name, } /** + * parse an attribute in the new SAX2 framework. + * * @param ctxt an XML parser context * @param pref the element prefix * @param elem the element name @@ -8651,9 +8569,6 @@ xmlParseQNameAndCompare(xmlParserCtxtPtr ctxt, xmlChar const *name, * @param value resulting value of the attribute * @param len resulting length of the attribute * @param alloc resulting indicator if the attribute was allocated - * - * parse an attribute in the new SAX2 framework. - * * @returns the attribute name, and the value in *value, . */ @@ -8763,15 +8678,14 @@ error: } /** + * Inserts a new attribute into the hash table. + * * @param ctxt parser context * @param size size of the hash table * @param name attribute name * @param uri namespace uri * @param hashValue combined hash value of name and uri * @param aindex attribute index (this is a multiple of 5) - * - * Inserts a new attribute into the hash table. - * * @returns INT_MAX if no existing attribute was found, the attribute * index if an attribute was found, -1 if a memory allocation failed. */ @@ -8840,11 +8754,6 @@ xmlAttrHashInsertQName(xmlParserCtxtPtr ctxt, unsigned size, return(INT_MAX); } /** - * @param ctxt an XML parser context - * @param pref resulting namespace prefix - * @param URI resulting namespace URI - * @param nbNsPtr resulting number of namespace declarations - * * Parse a start tag. Always consumes '<'. * * This routine is called when running SAX2 parsing @@ -8867,6 +8776,10 @@ xmlAttrHashInsertQName(xmlParserCtxtPtr ctxt, unsigned size, * * [NS 10] EmptyElement ::= '<' QName (S Attribute)* S? '/>' * + * @param ctxt an XML parser context + * @param pref resulting namespace prefix + * @param URI resulting namespace URI + * @param nbNsPtr resulting number of namespace declarations * @returns the element name parsed */ @@ -9477,9 +9390,6 @@ done: } /** - * @param ctxt an XML parser context - * @param tag the corresponding start tag - * * Parse an end tag. Always consumes '' @@ -9487,6 +9397,8 @@ done: * With namespace * * [NS 9] ETag ::= '' + * @param ctxt an XML parser context + * @param tag the corresponding start tag */ static void @@ -9542,12 +9454,10 @@ xmlParseEndTag2(xmlParserCtxtPtr ctxt, const xmlStartTag *tag) { } /** - * @param ctxt an XML parser context + * Parse escaped pure raw content. Always consumes '' Char*)) * * [21] CDEnd ::= ']]>' + * @param ctxt an XML parser context */ void xmlParseCDSect(xmlParserCtxtPtr ctxt) { @@ -9648,10 +9559,10 @@ out: } /** - * @param ctxt an XML parser context - * * Parse a content sequence. Stops at EOF or '' + * @param ctxt an XML parser context */ void @@ -10422,10 +10325,9 @@ xmlParseXMLDecl(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns the version from the XML declaration. */ const xmlChar * @@ -10437,10 +10339,9 @@ xmlCtxtGetVersion(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns the value from the standalone document declaration. */ int @@ -10452,13 +10353,12 @@ xmlCtxtGetStandalone(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context + * parse an XML Misc* optional field. * * @deprecated Internal function, don't use. * - * parse an XML Misc* optional field. - * * [27] Misc ::= Comment | PI | S + * @param ctxt an XML parser context */ void @@ -10510,12 +10410,11 @@ xmlFinishDocument(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * * Parse an XML document and invoke the SAX handlers. This is useful * if you're only interested in custom SAX callbacks. If you want a * document tree, use xmlCtxtParseDocument(). * + * @param ctxt an XML parser context * @returns 0, -1 in case of error. */ @@ -10631,16 +10530,15 @@ xmlParseDocument(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * - * @deprecated Internal function, don't use. - * * parse a general parsed entity * An external general parsed entity is well-formed if it matches the * production labeled extParsedEnt. * + * @deprecated Internal function, don't use. + * * [78] extParsedEnt ::= TextDecl? content * + * @param ctxt an XML parser context * @returns 0, -1 in case of error. the parser context is augmented * as a result of the parsing. */ @@ -10710,10 +10608,10 @@ xmlParseExtParsedEnt(xmlParserCtxtPtr ctxt) { ************************************************************************/ /** + * Check whether the input buffer contains a character. + * * @param ctxt an XML parser context * @param c character - * - * Check whether the input buffer contains a character. */ static int xmlParseLookupChar(xmlParserCtxtPtr ctxt, int c) { @@ -10741,12 +10639,12 @@ xmlParseLookupChar(xmlParserCtxtPtr ctxt, int c) { } /** + * Check whether the input buffer contains a string. + * * @param ctxt an XML parser context * @param startDelta delta to apply at the start * @param str string * @param strLen length of string - * - * Check whether the input buffer contains a string. */ static const xmlChar * xmlParseLookupString(xmlParserCtxtPtr ctxt, size_t startDelta, @@ -10783,9 +10681,9 @@ xmlParseLookupString(xmlParserCtxtPtr ctxt, size_t startDelta, } /** - * @param ctxt an XML parser context - * * Check whether the input buffer contains terminated char data. + * + * @param ctxt an XML parser context */ static int xmlParseLookupCharData(xmlParserCtxtPtr ctxt) { @@ -10811,10 +10709,10 @@ xmlParseLookupCharData(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * * Check whether there's enough data in the input buffer to finish parsing * a start tag. This has to take quotes into account. + * + * @param ctxt an XML parser context */ static int xmlParseLookupGt(xmlParserCtxtPtr ctxt) { @@ -10854,10 +10752,10 @@ xmlParseLookupGt(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * * Check whether there's enough data in the input buffer to finish parsing * the internal subset. + * + * @param ctxt an XML parser context */ static int xmlParseLookupInternalSubset(xmlParserCtxtPtr ctxt) { @@ -10963,11 +10861,10 @@ xmlParseLookupInternalSubset(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt an XML parser context - * @param terminate last chunk indicator - * * Try to progress on parsing * + * @param ctxt an XML parser context + * @param terminate last chunk indicator * @returns zero if no parsing was possible */ static int @@ -11352,11 +11249,6 @@ done: } /** - * @param ctxt an XML parser context - * @param chunk chunk of memory - * @param size size of chunk in bytes - * @param terminate last chunk indicator - * * Parse a chunk of memory in push parser mode. * * Assumes that the parser context was initialized with @@ -11373,6 +11265,10 @@ done: * ctxt->myDoc. So ctxt->myDoc should be set to NULL after extracting * the document. * + * @param ctxt an XML parser context + * @param chunk chunk of memory + * @param size size of chunk in bytes + * @param terminate last chunk indicator * @returns an xmlParserErrors code (0 on success). */ int @@ -11479,12 +11375,6 @@ xmlParseChunk(xmlParserCtxtPtr ctxt, const char *chunk, int size, ************************************************************************/ /** - * @param sax a SAX handler (optional) - * @param user_data user data for SAX callbacks (optional) - * @param chunk initial chunk (optional, deprecated) - * @param size size of initial chunk in bytes - * @param filename file name or URI (optional) - * * Create a parser context for using the XML parser in push mode. * See xmlParseChunk(). * @@ -11496,6 +11386,11 @@ xmlParseChunk(xmlParserCtxtPtr ctxt, const char *chunk, int size, * `filename` is used as base URI to fetch external entities and for * error reports. * + * @param sax a SAX handler (optional) + * @param user_data user data for SAX callbacks (optional) + * @param chunk initial chunk (optional, deprecated) + * @param size size of initial chunk in bytes + * @param filename file name or URI (optional) * @returns the new parser context or NULL if a memory allocation * failed. */ @@ -11529,9 +11424,9 @@ xmlCreatePushParserCtxt(xmlSAXHandlerPtr sax, void *user_data, #endif /* LIBXML_PUSH_ENABLED */ /** - * @param ctxt an XML parser context - * * Blocks further parser processing + * + * @param ctxt an XML parser context */ void xmlStopParser(xmlParserCtxtPtr ctxt) { @@ -11543,16 +11438,15 @@ xmlStopParser(xmlParserCtxtPtr ctxt) { } /** + * Create a parser context for using the XML parser with an existing + * I/O stream + * * @param sax a SAX handler (optional) * @param user_data user data for SAX callbacks (optional) * @param ioread an I/O read function * @param ioclose an I/O close function (optional) * @param ioctx an I/O handler * @param enc the charset encoding if known (deprecated) - * - * Create a parser context for using the XML parser with an existing - * I/O stream - * * @returns the new parser context or NULL */ xmlParserCtxtPtr @@ -11592,11 +11486,6 @@ xmlCreateIOParserCtxt(xmlSAXHandlerPtr sax, void *user_data, ************************************************************************/ /** - * @param ctxt a parser context - * @param input a parser input - * @param publicId public ID of the DTD (optional) - * @param systemId system ID of the DTD (optional) - * * Parse a DTD. * * Option XML_PARSE_DTDLOAD should be enabled in the parser context @@ -11604,6 +11493,10 @@ xmlCreateIOParserCtxt(xmlSAXHandlerPtr sax, void *user_data, * * @since 2.14.0 * + * @param ctxt a parser context + * @param input a parser input + * @param publicId public ID of the DTD (optional) + * @param systemId system ID of the DTD (optional) * @returns the resulting xmlDtdPtr or NULL in case of error. * `input` will be freed by the function in any case. */ @@ -11670,14 +11563,13 @@ error: } /** - * @param sax the SAX handler block or NULL - * @param input an Input Buffer - * @param enc the charset encoding if known + * Load and parse a DTD * * @deprecated Use xmlCtxtParseDtd(). * - * Load and parse a DTD - * + * @param sax the SAX handler block or NULL + * @param input an Input Buffer + * @param enc the charset encoding if known * @returns the resulting xmlDtdPtr or NULL in case of error. * `input` will be freed by the function in any case. */ @@ -11721,14 +11613,13 @@ xmlIOParseDTD(xmlSAXHandlerPtr sax, xmlParserInputBufferPtr input, } /** - * @param sax the SAX handler block - * @param ExternalID a NAME* containing the External ID of the DTD - * @param SystemID a NAME* containing the URL to the DTD + * Load and parse an external subset. * * @deprecated Use xmlCtxtParseDtd(). * - * Load and parse an external subset. - * + * @param sax the SAX handler block + * @param ExternalID a NAME* containing the External ID of the DTD + * @param SystemID a NAME* containing the URL to the DTD * @returns the resulting xmlDtdPtr or NULL in case of error. */ @@ -11784,11 +11675,10 @@ xmlSAXParseDTD(xmlSAXHandlerPtr sax, const xmlChar *ExternalID, /** - * @param ExternalID a NAME* containing the External ID of the DTD - * @param SystemID a NAME* containing the URL to the DTD - * * Load and parse an external subset. * + * @param ExternalID a NAME* containing the External ID of the DTD + * @param SystemID a NAME* containing the URL to the DTD * @returns the resulting xmlDtdPtr or NULL in case of error. */ @@ -12006,17 +11896,16 @@ error: } /** - * @param ctxt the existing parsing context - * @param URL the URL for the entity to load - * @param ID the System ID for the entity to load - * @param listOut the return value for the set of parsed nodes - * * Parse an external general entity within an existing parsing context * An external general parsed entity is well-formed if it matches the * production labeled extParsedEnt. * * [78] extParsedEnt ::= TextDecl? content * + * @param ctxt the existing parsing context + * @param URL the URL for the entity to load + * @param ID the System ID for the entity to load + * @param listOut the return value for the set of parsed nodes * @returns 0 if the entity is well formed, -1 in case of args problem and * the parser error code otherwise */ @@ -12052,6 +11941,14 @@ xmlParseCtxtExternalEntity(xmlParserCtxtPtr ctxt, const xmlChar *URL, #ifdef LIBXML_SAX1_ENABLED /** + * Parse an external general entity + * An external general parsed entity is well-formed if it matches the + * production labeled extParsedEnt. + * + * @deprecated Use xmlParseCtxtExternalEntity(). + * + * [78] extParsedEnt ::= TextDecl? content + * * @param doc the document the chunk pertains to * @param sax the SAX handler block (possibly NULL) * @param user_data The user data returned on SAX callbacks (possibly NULL) @@ -12059,15 +11956,6 @@ xmlParseCtxtExternalEntity(xmlParserCtxtPtr ctxt, const xmlChar *URL, * @param URL the URL for the entity to load * @param ID the System ID for the entity to load * @param list the return value for the set of parsed nodes - * - * @deprecated Use xmlParseCtxtExternalEntity(). - * - * Parse an external general entity - * An external general parsed entity is well-formed if it matches the - * production labeled extParsedEnt. - * - * [78] extParsedEnt ::= TextDecl? content - * * @returns 0 if the entity is well formed, -1 in case of args problem and * the parser error code otherwise */ @@ -12097,13 +11985,6 @@ xmlParseExternalEntity(xmlDocPtr doc, xmlSAXHandlerPtr sax, void *user_data, } /** - * @param doc the document the chunk pertains to (must not be NULL) - * @param sax the SAX handler block (possibly NULL) - * @param user_data The user data returned on SAX callbacks (possibly NULL) - * @param depth Used for loop detection, use 0 - * @param string the input string in UTF8 or ISO-Latin (zero terminated) - * @param lst the return value for the set of parsed nodes - * * Parse a well-balanced chunk of an XML document * called by the parser * The allowed sequence for the Well Balanced Chunk is the one defined by @@ -12112,6 +11993,12 @@ xmlParseExternalEntity(xmlDocPtr doc, xmlSAXHandlerPtr sax, void *user_data, * [43] content ::= (element | CharData | Reference | CDSect | PI | * Comment)* * + * @param doc the document the chunk pertains to (must not be NULL) + * @param sax the SAX handler block (possibly NULL) + * @param user_data The user data returned on SAX callbacks (possibly NULL) + * @param depth Used for loop detection, use 0 + * @param string the input string in UTF8 or ISO-Latin (zero terminated) + * @param lst the return value for the set of parsed nodes * @returns 0 if the chunk is well balanced, -1 in case of args problem and * the parser error code otherwise */ @@ -12125,11 +12012,6 @@ xmlParseBalancedChunkMemory(xmlDocPtr doc, xmlSAXHandlerPtr sax, #endif /* LIBXML_SAX1_ENABLED */ /** - * @param ctxt parser context - * @param input parser input - * @param node target node or document - * @param hasTextDecl whether to parse text declaration - * * Parse a well-balanced chunk of XML matching the 'content' production. * * Namespaces in scope of `node` and entities of `node`'s document are @@ -12139,6 +12021,10 @@ xmlParseBalancedChunkMemory(xmlDocPtr doc, xmlSAXHandlerPtr sax, * * @since 2.14.0 * + * @param ctxt parser context + * @param input parser input + * @param node target node or document + * @param hasTextDecl whether to parse text declaration * @returns a node list or NULL in case of error. */ xmlNodePtr @@ -12268,12 +12154,6 @@ exit: } /** - * @param node the context node - * @param data the input string - * @param datalen the input string length in bytes - * @param options a combination of xmlParserOption - * @param listOut the return value for the set of parsed nodes - * * Parse a well-balanced chunk of an XML document * within the context (DTD, namespaces, etc ...) of the given node. * @@ -12287,6 +12167,11 @@ exit: * typically not what you want. A better alternative is * xmlCtxtParseContent(). * + * @param node the context node + * @param data the input string + * @param datalen the input string length in bytes + * @param options a combination of xmlParserOption + * @param listOut the return value for the set of parsed nodes * @returns XML_ERR_OK if the chunk is well balanced, and the parser * error code otherwise */ @@ -12349,14 +12234,6 @@ xmlParseInNodeContext(xmlNodePtr node, const char *data, int datalen, #ifdef LIBXML_SAX1_ENABLED /** - * @param doc the document the chunk pertains to (must not be NULL) - * @param sax the SAX handler block (possibly NULL) - * @param user_data The user data returned on SAX callbacks (possibly NULL) - * @param depth Used for loop detection, use 0 - * @param string the input string in UTF8 or ISO-Latin (zero terminated) - * @param listOut the return value for the set of parsed nodes - * @param recover return nodes even if the data is broken (use 0) - * * Parse a well-balanced chunk of an XML document * * The allowed sequence for the Well Balanced Chunk is the one defined by @@ -12365,12 +12242,18 @@ xmlParseInNodeContext(xmlNodePtr node, const char *data, int datalen, * [43] content ::= (element | CharData | Reference | CDSect | PI | * Comment)* * - * @returns 0 if the chunk is well balanced, or thehe parser error code - * otherwise. - * * In case recover is set to 1, the nodelist will not be empty even if * the parsed chunk is not well balanced, assuming the parsing succeeded to * some extent. + * @param doc the document the chunk pertains to (must not be NULL) + * @param sax the SAX handler block (possibly NULL) + * @param user_data The user data returned on SAX callbacks (possibly NULL) + * @param depth Used for loop detection, use 0 + * @param string the input string in UTF8 or ISO-Latin (zero terminated) + * @param listOut the return value for the set of parsed nodes + * @param recover return nodes even if the data is broken (use 0) + * @returns 0 if the chunk is well balanced, or thehe parser error code + * otherwise. */ int xmlParseBalancedChunkMemoryRecover(xmlDocPtr doc, xmlSAXHandlerPtr sax, @@ -12424,19 +12307,18 @@ error: } /** - * @param sax the SAX handler block - * @param filename the filename - * - * @deprecated Don't use. - * * parse an XML external entity out of context and build a tree. * It use the given SAX function block to handle the parsing callback. * If sax is NULL, fallback to the default DOM tree building routines. * + * @deprecated Don't use. + * * [78] extParsedEnt ::= TextDecl? content * * This correspond to a "Well Balanced" chunk * + * @param sax the SAX handler block + * @param filename the filename * @returns the resulting document tree */ @@ -12474,14 +12356,13 @@ xmlSAXParseEntity(xmlSAXHandlerPtr sax, const char *filename) { } /** - * @param filename the filename - * * parse an XML external entity out of context and build a tree. * * [78] extParsedEnt ::= TextDecl? content * * This correspond to a "Well Balanced" chunk * + * @param filename the filename * @returns the resulting document tree */ @@ -12492,16 +12373,15 @@ xmlParseEntity(const char *filename) { #endif /* LIBXML_SAX1_ENABLED */ /** - * @param URL the entity URL - * @param ID the entity PUBLIC ID - * @param base a possible base for the target URI - * - * @deprecated Don't use. - * * Create a parser context for an external entity * Automatic support for ZLIB/Compress compressed document is provided * by default if found at compile-time. * + * @deprecated Don't use. + * + * @param URL the entity URL + * @param ID the entity PUBLIC ID + * @param base a possible base for the target URI * @returns the new parser context or NULL */ xmlParserCtxtPtr @@ -12548,15 +12428,14 @@ error: ************************************************************************/ /** - * @param filename the filename or URL - * @param options a combination of xmlParserOption - * - * @deprecated Use xmlNewParserCtxt() and xmlCtxtReadFile(). - * * Create a parser context for a file or URL content. * Automatic support for ZLIB/Compress compressed document is provided * by default if found at compile-time and for file accesses * + * @deprecated Use xmlNewParserCtxt() and xmlCtxtReadFile(). + * + * @param filename the filename or URL + * @param options a combination of xmlParserOption * @returns the new parser context or NULL */ xmlParserCtxtPtr @@ -12589,14 +12468,13 @@ xmlCreateURLParserCtxt(const char *filename, int options) } /** - * @param filename the filename - * - * @deprecated Use xmlNewParserCtxt() and xmlCtxtReadFile(). - * * Create a parser context for a file content. * Automatic support for ZLIB/Compress compressed document is provided * by default if found at compile-time. * + * @deprecated Use xmlNewParserCtxt() and xmlCtxtReadFile(). + * + * @param filename the filename * @returns the new parser context or NULL */ xmlParserCtxtPtr @@ -12607,22 +12485,21 @@ xmlCreateFileParserCtxt(const char *filename) #ifdef LIBXML_SAX1_ENABLED /** - * @param sax the SAX handler block - * @param filename the filename - * @param recovery work in recovery mode, i.e. tries to read no Well Formed - * documents - * @param data the userdata - * - * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadFile(). - * * parse an XML file and build a tree. Automatic support for ZLIB/Compress * compressed document is provided by default if found at compile-time. * It use the given SAX function block to handle the parsing callback. * If sax is NULL, fallback to the default DOM tree building routines. * + * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadFile(). + * * User data (void *) is stored within the parser context in the * context's _private member, so it is available nearly everywhere in libxml * + * @param sax the SAX handler block + * @param filename the filename + * @param recovery work in recovery mode, i.e. tries to read no Well Formed + * documents + * @param data the userdata * @returns the resulting document tree */ @@ -12658,18 +12535,17 @@ xmlSAXParseFileWithData(xmlSAXHandlerPtr sax, const char *filename, } /** - * @param sax the SAX handler block - * @param filename the filename - * @param recovery work in recovery mode, i.e. tries to read no Well Formed - * documents - * - * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadFile(). - * * parse an XML file and build a tree. Automatic support for ZLIB/Compress * compressed document is provided by default if found at compile-time. * It use the given SAX function block to handle the parsing callback. * If sax is NULL, fallback to the default DOM tree building routines. * + * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadFile(). + * + * @param sax the SAX handler block + * @param filename the filename + * @param recovery work in recovery mode, i.e. tries to read no Well Formed + * documents * @returns the resulting document tree */ @@ -12680,14 +12556,13 @@ xmlSAXParseFile(xmlSAXHandlerPtr sax, const char *filename, } /** - * @param cur a pointer to an array of xmlChar - * - * @deprecated Use xmlReadDoc() with XML_PARSE_RECOVER. - * * parse an XML in-memory document and build a tree. * In the case the document is not Well Formed, a attempt to build a * tree is tried anyway * + * @deprecated Use xmlReadDoc() with XML_PARSE_RECOVER. + * + * @param cur a pointer to an array of xmlChar * @returns the resulting document tree or NULL in case of failure */ @@ -12697,13 +12572,12 @@ xmlRecoverDoc(const xmlChar *cur) { } /** - * @param filename the filename - * - * @deprecated Use xmlReadFile(). - * * parse an XML file and build a tree. Automatic support for ZLIB/Compress * compressed document is provided by default if found at compile-time. * + * @deprecated Use xmlReadFile(). + * + * @param filename the filename * @returns the resulting document tree if the file was wellformed, * NULL otherwise. */ @@ -12714,15 +12588,14 @@ xmlParseFile(const char *filename) { } /** - * @param filename the filename - * - * @deprecated Use xmlReadFile() with XML_PARSE_RECOVER. - * * parse an XML file and build a tree. Automatic support for ZLIB/Compress * compressed document is provided by default if found at compile-time. * In the case the document is not Well Formed, it attempts to build * a tree anyway * + * @deprecated Use xmlReadFile() with XML_PARSE_RECOVER. + * + * @param filename the filename * @returns the resulting document tree or NULL in case of failure */ @@ -12733,15 +12606,15 @@ xmlRecoverFile(const char *filename) { /** - * @param ctxt an XML parser context - * @param buffer a xmlChar * buffer - * @param filename a file name - * - * @deprecated Don't use. - * * Setup the parser context to parse a new buffer; Clears any prior * contents from the parser context. The buffer parameter must not be * NULL, but the filename parameter can be + * + * @deprecated Don't use. + * + * @param ctxt an XML parser context + * @param buffer a xmlChar * buffer + * @param filename a file name */ void xmlSetupParserForBuffer(xmlParserCtxtPtr ctxt, const xmlChar* buffer, @@ -12763,15 +12636,14 @@ xmlSetupParserForBuffer(xmlParserCtxtPtr ctxt, const xmlChar* buffer, } /** - * @param sax a SAX handler - * @param user_data The user data returned on SAX callbacks - * @param filename a file name - * - * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadFile(). - * * parse an XML file and call the given SAX handler routines. * Automatic support for ZLIB/Compress compressed document is provided * + * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadFile(). + * + * @param sax a SAX handler + * @param user_data The user data returned on SAX callbacks + * @param filename a file name * @returns 0 in case of success or a error number otherwise */ int @@ -12819,12 +12691,11 @@ xmlSAXUserParseFile(xmlSAXHandlerPtr sax, void *user_data, ************************************************************************/ /** - * @param buffer a pointer to a char array - * @param size the size of the array - * * Create a parser context for an XML in-memory document. The input buffer * must not contain a terminating null byte. * + * @param buffer a pointer to a char array + * @param size the size of the array * @returns the new parser context or NULL */ xmlParserCtxtPtr @@ -12855,22 +12726,21 @@ xmlCreateMemoryParserCtxt(const char *buffer, int size) { #ifdef LIBXML_SAX1_ENABLED /** + * parse an XML in-memory block and use the given SAX function block + * to handle the parsing callback. If sax is NULL, fallback to the default + * DOM tree building routines. + * + * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadMemory(). + * + * User data (void *) is stored within the parser context in the + * context's _private member, so it is available nearly everywhere in libxml + * * @param sax the SAX handler block * @param buffer an pointer to a char array * @param size the size of the array * @param recovery work in recovery mode, i.e. tries to read no Well Formed * documents * @param data the userdata - * - * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadMemory(). - * - * parse an XML in-memory block and use the given SAX function block - * to handle the parsing callback. If sax is NULL, fallback to the default - * DOM tree building routines. - * - * User data (void *) is stored within the parser context in the - * context's _private member, so it is available nearly everywhere in libxml - * * @returns the resulting document tree */ @@ -12907,18 +12777,17 @@ xmlSAXParseMemoryWithData(xmlSAXHandlerPtr sax, const char *buffer, } /** + * parse an XML in-memory block and use the given SAX function block + * to handle the parsing callback. If sax is NULL, fallback to the default + * DOM tree building routines. + * + * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadMemory(). + * * @param sax the SAX handler block * @param buffer an pointer to a char array * @param size the size of the array * @param recovery work in recovery mode, i.e. tries to read not Well Formed * documents - * - * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadMemory(). - * - * parse an XML in-memory block and use the given SAX function block - * to handle the parsing callback. If sax is NULL, fallback to the default - * DOM tree building routines. - * * @returns the resulting document tree */ xmlDocPtr @@ -12928,13 +12797,12 @@ xmlSAXParseMemory(xmlSAXHandlerPtr sax, const char *buffer, } /** - * @param buffer an pointer to a char array - * @param size the size of the array + * parse an XML in-memory block and build a tree. * * @deprecated Use xmlReadMemory(). * - * parse an XML in-memory block and build a tree. - * + * @param buffer an pointer to a char array + * @param size the size of the array * @returns the resulting document tree */ @@ -12943,15 +12811,14 @@ xmlDocPtr xmlParseMemory(const char *buffer, int size) { } /** - * @param buffer an pointer to a char array - * @param size the size of the array - * - * @deprecated Use xmlReadMemory() with XML_PARSE_RECOVER. - * * parse an XML in-memory block and build a tree. * In the case the document is not Well Formed, an attempt to * build a tree is tried anyway * + * @deprecated Use xmlReadMemory() with XML_PARSE_RECOVER. + * + * @param buffer an pointer to a char array + * @param size the size of the array * @returns the resulting document tree or NULL in case of error */ @@ -12960,15 +12827,14 @@ xmlDocPtr xmlRecoverMemory(const char *buffer, int size) { } /** + * parse an XML in-memory buffer and call the given SAX handler routines. + * + * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadMemory(). + * * @param sax a SAX handler * @param user_data The user data returned on SAX callbacks * @param buffer an in-memory XML document input * @param size the length of the XML document in bytes - * - * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadMemory(). - * - * parse an XML in-memory buffer and call the given SAX handler routines. - * * @returns 0 in case of success or a error number otherwise */ int xmlSAXUserParseMemory(xmlSAXHandlerPtr sax, void *user_data, @@ -13009,10 +12875,9 @@ int xmlSAXUserParseMemory(xmlSAXHandlerPtr sax, void *user_data, #endif /* LIBXML_SAX1_ENABLED */ /** - * @param str a pointer to an array of xmlChar - * * Creates a parser context for an XML in-memory document. * + * @param str a pointer to an array of xmlChar * @returns the new parser context or NULL */ xmlParserCtxtPtr @@ -13040,17 +12905,16 @@ xmlCreateDocParserCtxt(const xmlChar *str) { #ifdef LIBXML_SAX1_ENABLED /** - * @param sax the SAX handler block - * @param cur a pointer to an array of xmlChar - * @param recovery work in recovery mode, i.e. tries to read no Well Formed - * documents - * - * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadDoc(). - * * parse an XML in-memory document and build a tree. * It use the given SAX function block to handle the parsing callback. * If sax is NULL, fallback to the default DOM tree building routines. * + * @deprecated Use xmlNewSAXParserCtxt() and xmlCtxtReadDoc(). + * + * @param sax the SAX handler block + * @param cur a pointer to an array of xmlChar + * @param recovery work in recovery mode, i.e. tries to read no Well Formed + * documents * @returns the resulting document tree */ @@ -13086,12 +12950,11 @@ xmlSAXParseDoc(xmlSAXHandlerPtr sax, const xmlChar *cur, int recovery) { } /** - * @param cur a pointer to an array of xmlChar + * parse an XML in-memory document and build a tree. * * @deprecated Use xmlReadDoc(). * - * parse an XML in-memory document and build a tree. - * + * @param cur a pointer to an array of xmlChar * @returns the resulting document tree */ @@ -13108,10 +12971,10 @@ xmlParseDoc(const xmlChar *cur) { ************************************************************************/ /** - * @param str a string - * * Free a string if it is not owned by the "dict" dictionary in the * current scope + * + * @param str a string */ #define DICT_FREE(str) \ if ((str) && ((!dict) || \ @@ -13119,9 +12982,9 @@ xmlParseDoc(const xmlChar *cur) { xmlFree((char *)(str)); /** - * @param ctxt an XML parser context - * * Reset a parser context + * + * @param ctxt an XML parser context */ void xmlCtxtReset(xmlParserCtxtPtr ctxt) @@ -13217,14 +13080,13 @@ xmlCtxtReset(xmlParserCtxtPtr ctxt) } /** + * Reset a push parser context + * * @param ctxt an XML parser context * @param chunk a pointer to an array of chars * @param size number of chars in the array * @param filename an optional file name or URI * @param encoding the document encoding, or NULL - * - * Reset a push parser context - * * @returns 0 in case of success and 1 in case of error */ int @@ -13331,9 +13193,6 @@ xmlCtxtSetOptionsInternal(xmlParserCtxtPtr ctxt, int options, int keepMask) } /** - * @param ctxt an XML parser context - * @param options a bitmask of xmlParserOption values - * * Applies the options to the parser context. Unset options are * cleared. * @@ -13341,6 +13200,8 @@ xmlCtxtSetOptionsInternal(xmlParserCtxtPtr ctxt, int options, int keepMask) * * With older versions, you can use xmlCtxtUseOptions(). * + * @param ctxt an XML parser context + * @param options a bitmask of xmlParserOption values * @returns 0 in case of success, the set of unknown or unimplemented options * in case of error. */ @@ -13356,12 +13217,11 @@ xmlCtxtSetOptions(xmlParserCtxtPtr ctxt, int options) } /** - * @param ctxt an XML parser context - * * Get the current options of the parser context. * * @since 2.14.0 * + * @param ctxt an XML parser context * @returns the current options set in the parser context, or -1 if ctxt is NULL. */ int @@ -13374,14 +13234,11 @@ xmlCtxtGetOptions(xmlParserCtxtPtr ctxt) } /** - * @param ctxt an XML parser context - * @param options a combination of xmlParserOption - * - * @deprecated Use xmlCtxtSetOptions(). - * * Applies the options to the parser context. The following options * are never cleared and can only be enabled: * + * @deprecated Use xmlCtxtSetOptions(). + * * - XML_PARSE_NOERROR * - XML_PARSE_NOWARNING * - XML_PARSE_NONET @@ -13394,6 +13251,8 @@ xmlCtxtGetOptions(xmlParserCtxtPtr ctxt) * - XML_PARSE_IGNORE_ENC * - XML_PARSE_BIG_LINES * + * @param ctxt an XML parser context + * @param options a combination of xmlParserOption * @returns 0 in case of success, the set of unknown or unimplemented options * in case of error. */ @@ -13426,9 +13285,6 @@ xmlCtxtUseOptions(xmlParserCtxtPtr ctxt, int options) } /** - * @param ctxt an XML parser context - * @param maxAmpl maximum amplification factor - * * To protect against exponential entity expansion ("billion laughs"), the * size of serialized output is (roughly) limited to the input size * multiplied by this factor. The default value is 5. @@ -13436,6 +13292,8 @@ xmlCtxtUseOptions(xmlParserCtxtPtr ctxt, int options) * When working with documents making heavy use of entity expansion, it can * be necessary to increase the value. For security reasons, this should only * be considered when processing trusted input. + * @param ctxt an XML parser context + * @param maxAmpl maximum amplification factor */ void xmlCtxtSetMaxAmplification(xmlParserCtxtPtr ctxt, unsigned maxAmpl) @@ -13446,14 +13304,13 @@ xmlCtxtSetMaxAmplification(xmlParserCtxtPtr ctxt, unsigned maxAmpl) } /** - * @param ctxt an XML parser context - * @param input parser input - * * Parse an XML document and return the resulting document tree. * Takes ownership of the input object. * * @since 2.13.0 * + * @param ctxt an XML parser context + * @param input parser input * @returns the resulting document tree or NULL */ xmlDocPtr @@ -13488,16 +13345,15 @@ xmlCtxtParseDocument(xmlParserCtxtPtr ctxt, xmlParserInputPtr input) } /** - * @param cur a pointer to a zero terminated string - * @param URL base URL (optional) - * @param encoding the document encoding (optional) - * @param options a combination of xmlParserOption - * * Convenience function to parse an XML document from a * zero-terminated string. * * See xmlCtxtReadDoc() for details. * + * @param cur a pointer to a zero terminated string + * @param URL base URL (optional) + * @param encoding the document encoding (optional) + * @param options a combination of xmlParserOption * @returns the resulting document tree */ xmlDocPtr @@ -13525,10 +13381,6 @@ xmlReadDoc(const xmlChar *cur, const char *URL, const char *encoding, } /** - * @param filename a file or URL - * @param encoding the document encoding (optional) - * @param options a combination of xmlParserOption - * * Convenience function to parse an XML file from the filesystem, * the network or a global user-define resource loader. * @@ -13539,6 +13391,9 @@ xmlReadDoc(const xmlChar *cur, const char *URL, const char *encoding, * * See xmlCtxtReadFile() for details. * + * @param filename a file or URL + * @param encoding the document encoding (optional) + * @param options a combination of xmlParserOption * @returns the resulting document tree */ xmlDocPtr @@ -13575,17 +13430,16 @@ xmlReadFile(const char *filename, const char *encoding, int options) } /** - * @param buffer a pointer to a char array - * @param size the size of the array - * @param url base URL (optional) - * @param encoding the document encoding (optional) - * @param options a combination of xmlParserOption - * * Parse an XML in-memory document and build a tree. The input buffer must * not contain a terminating null byte. * * See xmlCtxtReadMemory() for details. * + * @param buffer a pointer to a char array + * @param size the size of the array + * @param url base URL (optional) + * @param encoding the document encoding (optional) + * @param options a combination of xmlParserOption * @returns the resulting document tree */ xmlDocPtr @@ -13616,11 +13470,6 @@ xmlReadMemory(const char *buffer, int size, const char *url, } /** - * @param fd an open file descriptor - * @param URL base URL (optional) - * @param encoding the document encoding (optional) - * @param options a combination of xmlParserOption - * * Parse an XML from a file descriptor and build a tree. * * See xmlCtxtReadFd() for details. @@ -13628,6 +13477,10 @@ xmlReadMemory(const char *buffer, int size, const char *url, * NOTE that the file descriptor will not be closed when the * context is freed or reset. * + * @param fd an open file descriptor + * @param URL base URL (optional) + * @param encoding the document encoding (optional) + * @param options a combination of xmlParserOption * @returns the resulting document tree */ xmlDocPtr @@ -13653,17 +13506,16 @@ xmlReadFd(int fd, const char *URL, const char *encoding, int options) } /** + * Parse an XML document from I/O functions and context and build a tree. + * + * See xmlCtxtReadIO() for details. + * * @param ioread an I/O read function * @param ioclose an I/O close function (optional) * @param ioctx an I/O handler * @param URL base URL (optional) * @param encoding the document encoding (optional) * @param options a combination of xmlParserOption - * - * Parse an XML document from I/O functions and context and build a tree. - * - * See xmlCtxtReadIO() for details. - * * @returns the resulting document tree */ xmlDocPtr @@ -13691,12 +13543,6 @@ xmlReadIO(xmlInputReadCallback ioread, xmlInputCloseCallback ioclose, } /** - * @param ctxt an XML parser context - * @param str a pointer to a zero terminated string - * @param URL base URL (optional) - * @param encoding the document encoding (optional) - * @param options a combination of xmlParserOption - * * Parse an XML in-memory document and build a tree. * * `URL` is used as base to resolve external entities and for error @@ -13704,6 +13550,11 @@ xmlReadIO(xmlInputReadCallback ioread, xmlInputCloseCallback ioclose, * * See xmlCtxtUseOptions() for details. * + * @param ctxt an XML parser context + * @param str a pointer to a zero terminated string + * @param URL base URL (optional) + * @param encoding the document encoding (optional) + * @param options a combination of xmlParserOption * @returns the resulting document tree */ xmlDocPtr @@ -13727,11 +13578,6 @@ xmlCtxtReadDoc(xmlParserCtxtPtr ctxt, const xmlChar *str, } /** - * @param ctxt an XML parser context - * @param filename a file or URL - * @param encoding the document encoding (optional) - * @param options a combination of xmlParserOption - * * Parse an XML file from the filesystem, the network or a user-defined * resource loader. * @@ -13739,6 +13585,10 @@ xmlCtxtReadDoc(xmlParserCtxtPtr ctxt, const xmlChar *str, * backward compatibility. This feature is potentially insecure * and might be removed from later versions. * + * @param ctxt an XML parser context + * @param filename a file or URL + * @param encoding the document encoding (optional) + * @param options a combination of xmlParserOption * @returns the resulting document tree */ xmlDocPtr @@ -13763,13 +13613,6 @@ xmlCtxtReadFile(xmlParserCtxtPtr ctxt, const char *filename, } /** - * @param ctxt an XML parser context - * @param buffer a pointer to a char array - * @param size the size of the array - * @param URL base URL (optional) - * @param encoding the document encoding (optional) - * @param options a combination of xmlParserOption - * * Parse an XML in-memory document and build a tree. The input buffer must * not contain a terminating null byte. * @@ -13778,6 +13621,12 @@ xmlCtxtReadFile(xmlParserCtxtPtr ctxt, const char *filename, * * See xmlCtxtUseOptions() for details. * + * @param ctxt an XML parser context + * @param buffer a pointer to a char array + * @param size the size of the array + * @param URL base URL (optional) + * @param encoding the document encoding (optional) + * @param options a combination of xmlParserOption * @returns the resulting document tree */ xmlDocPtr @@ -13801,12 +13650,6 @@ xmlCtxtReadMemory(xmlParserCtxtPtr ctxt, const char *buffer, int size, } /** - * @param ctxt an XML parser context - * @param fd an open file descriptor - * @param URL base URL (optional) - * @param encoding the document encoding (optional) - * @param options a combination of xmlParserOption - * * Parse an XML document from a file descriptor and build a tree. * * NOTE that the file descriptor will not be closed when the @@ -13817,6 +13660,11 @@ xmlCtxtReadMemory(xmlParserCtxtPtr ctxt, const char *buffer, int size, * * See xmlCtxtUseOptions() for details. * + * @param ctxt an XML parser context + * @param fd an open file descriptor + * @param URL base URL (optional) + * @param encoding the document encoding (optional) + * @param options a combination of xmlParserOption * @returns the resulting document tree */ xmlDocPtr @@ -13839,14 +13687,6 @@ xmlCtxtReadFd(xmlParserCtxtPtr ctxt, int fd, } /** - * @param ctxt an XML parser context - * @param ioread an I/O read function - * @param ioclose an I/O close function - * @param ioctx an I/O handler - * @param URL the base URL to use for the document - * @param encoding the document encoding, or NULL - * @param options a combination of xmlParserOption - * * parse an XML document from I/O functions and source and build a tree. * This reuses the existing `ctxt` parser context * @@ -13855,6 +13695,13 @@ xmlCtxtReadFd(xmlParserCtxtPtr ctxt, int fd, * * See xmlCtxtUseOptions() for details. * + * @param ctxt an XML parser context + * @param ioread an I/O read function + * @param ioclose an I/O close function + * @param ioctx an I/O handler + * @param URL the base URL to use for the document + * @param encoding the document encoding, or NULL + * @param options a combination of xmlParserOption * @returns the resulting document tree */ xmlDocPtr diff --git a/parserInternals.c b/parserInternals.c index c40deddb..9fa070de 100644 --- a/parserInternals.c +++ b/parserInternals.c @@ -63,9 +63,9 @@ */ /** - * @param version the include version number - * * check the compiled lib version against the include one. + * + * @param version the include version number */ void xmlCheckVersion(int version) { @@ -93,10 +93,6 @@ xmlCheckVersion(int version) { /** - * @param ctxt an XML parser context - * @param handler error handler - * @param data data for error handler - * * Register a callback function that will be called on errors and * warnings. If handler is NULL, the error handler will be deactivated. * @@ -112,6 +108,9 @@ xmlCheckVersion(int version) { * - print to stderr * * @since 2.13.0 + * @param ctxt an XML parser context + * @param handler error handler + * @param data data for error handler */ void xmlCtxtSetErrorHandler(xmlParserCtxtPtr ctxt, xmlStructuredErrorFunc handler, @@ -124,8 +123,6 @@ xmlCtxtSetErrorHandler(xmlParserCtxtPtr ctxt, xmlStructuredErrorFunc handler, } /** - * @param ctx an XML parser context - * * Get the last error raised. * * Note that the XML parser typically doesn't stop after @@ -133,6 +130,7 @@ xmlCtxtSetErrorHandler(xmlParserCtxtPtr ctxt, xmlStructuredErrorFunc handler, * Most of the time, the last error isn't useful. Future * versions might return the first parser error instead. * + * @param ctx an XML parser context * @returns NULL if no error occurred or a pointer to the error */ const xmlError * @@ -148,10 +146,10 @@ xmlCtxtGetLastError(void *ctx) } /** - * @param ctx an XML parser context - * * Reset the last parser error to success. This does not change * the well-formedness status. + * + * @param ctx an XML parser context */ void xmlCtxtResetLastError(void *ctx) @@ -167,11 +165,10 @@ xmlCtxtResetLastError(void *ctx) } /** - * @param ctxt an XML parser context - * * Handle an out-of-memory error. * * @since 2.13.0 + * @param ctxt an XML parser context */ void xmlCtxtErrMemory(xmlParserCtxtPtr ctxt) @@ -207,13 +204,12 @@ xmlCtxtErrMemory(xmlParserCtxtPtr ctxt) } /** - * @param ctxt parser context - * @param code xmlParserErrors code - * @param uri filename or URI (optional) - * * If filename is empty, use the one from context input if available. * * Report an IO error to the parser context. + * @param ctxt parser context + * @param code xmlParserErrors code + * @param uri filename or URI (optional) */ void xmlCtxtErrIO(xmlParserCtxtPtr ctxt, int code, const char *uri) @@ -261,7 +257,6 @@ xmlCtxtErrIO(xmlParserCtxtPtr ctxt, int code, const char *uri) /** * @param ctxt parser context - * * @returns true if the last error is catastrophic. */ int @@ -274,6 +269,8 @@ xmlCtxtIsCatastrophicError(xmlParserCtxtPtr ctxt) { } /** + * Raise a parser error. + * * @param ctxt a parser context * @param node the current node or NULL * @param domain the domain for the error @@ -285,8 +282,6 @@ xmlCtxtIsCatastrophicError(xmlParserCtxtPtr ctxt) { * @param int1 extra int info * @param msg the message to display/transmit * @param ap extra parameters for the message display - * - * Raise a parser error. */ void xmlCtxtVErr(xmlParserCtxtPtr ctxt, xmlNodePtr node, xmlErrorDomain domain, @@ -398,6 +393,10 @@ xmlCtxtVErr(xmlParserCtxtPtr ctxt, xmlNodePtr node, xmlErrorDomain domain, } /** + * Raise a parser error. + * + * @...: extra parameters for the message display + * * @param ctxt a parser context * @param node the current node or NULL * @param domain the domain for the error @@ -408,9 +407,6 @@ xmlCtxtVErr(xmlParserCtxtPtr ctxt, xmlNodePtr node, xmlErrorDomain domain, * @param str3 extra string info * @param int1 extra int info * @param msg the message to display/transmit - * @...: extra parameters for the message display - * - * Raise a parser error. */ void xmlCtxtErr(xmlParserCtxtPtr ctxt, xmlNodePtr node, xmlErrorDomain domain, @@ -427,14 +423,13 @@ xmlCtxtErr(xmlParserCtxtPtr ctxt, xmlNodePtr node, xmlErrorDomain domain, } /** - * @param ctxt an XML parser context - * * Get well-formedness and validation status after parsing. Also * reports catastrophic errors which are not related to parsing * like out-of-memory, I/O or other errors. * * @since 2.14.0 * + * @param ctxt an XML parser context * @returns a bitmask of XML_STATUS_* flags ORed together. */ xmlParserStatus @@ -462,11 +457,11 @@ xmlCtxtGetStatus(xmlParserCtxt *ctxt) { } /** + * Handle a fatal parser error, i.e. violating Well-Formedness constraints + * * @param ctxt an XML parser context * @param code the error number * @param info extra information string - * - * Handle a fatal parser error, i.e. violating Well-Formedness constraints */ void xmlFatalErr(xmlParserCtxtPtr ctxt, xmlParserErrors code, const char *info) @@ -486,16 +481,15 @@ xmlFatalErr(xmlParserCtxtPtr ctxt, xmlParserErrors code, const char *info) } /** - * @param c an unicode character (int) + * Check whether the character is allowed by the production * * @deprecated Internal function, don't use. * - * Check whether the character is allowed by the production - * * ``` * [84] Letter ::= BaseChar | Ideographic * ``` * + * @param c an unicode character (int) * @returns 0 if not, non-zero otherwise */ int @@ -513,10 +507,10 @@ xmlIsLetter(int c) { #define LINE_LEN 80 /** - * @param ctxt an XML parser context - * * Blocks further parser processing don't override error * for internal use + * + * @param ctxt an XML parser context */ void xmlHaltParser(xmlParserCtxtPtr ctxt) { @@ -527,11 +521,10 @@ xmlHaltParser(xmlParserCtxtPtr ctxt) { } /** - * @param in an XML parser input - * @param len an indicative size for the lookahead - * * @deprecated This function was internal and is deprecated. * + * @param in an XML parser input + * @param len an indicative size for the lookahead * @returns -1 as this is an error to use it. */ int @@ -540,10 +533,9 @@ xmlParserInputRead(xmlParserInputPtr in ATTRIBUTE_UNUSED, int len ATTRIBUTE_UNUS } /** - * @param ctxt an XML parser context - * * Grow the input buffer. * + * @param ctxt an XML parser context * @returns the number of bytes read or -1 in case of error. */ int @@ -589,11 +581,11 @@ xmlParserGrow(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt parser ctxt - * @param code error code - * * Raises an error with `code` if the input wasn't consumed * completely. + * + * @param ctxt parser ctxt + * @param code error code */ void xmlParserCheckEOF(xmlParserCtxtPtr ctxt, xmlParserErrors code) { @@ -631,14 +623,13 @@ xmlParserCheckEOF(xmlParserCtxtPtr ctxt, xmlParserErrors code) { } /** - * @param in an XML parser input - * @param len an indicative size for the lookahead - * - * @deprecated Don't use. - * * This function increase the input for the parser. It tries to * preserve pointers to the input buffer, and keep already read data * + * @deprecated Don't use. + * + * @param in an XML parser input + * @param len an indicative size for the lookahead * @returns the amount of char read, or -1 in case of error, 0 indicate the * end of this entity */ @@ -677,9 +668,9 @@ xmlParserInputGrow(xmlParserInputPtr in, int len) { } /** - * @param ctxt an XML parser context - * * Shrink the input buffer. + * + * @param ctxt an XML parser context */ void xmlParserShrink(xmlParserCtxtPtr ctxt) { @@ -709,11 +700,11 @@ xmlParserShrink(xmlParserCtxtPtr ctxt) { } /** - * @param in an XML parser input + * This function removes used input for the parser. * * @deprecated Don't use. * - * This function removes used input for the parser. + * @param in an XML parser input */ void xmlParserInputShrink(xmlParserInputPtr in) { @@ -750,11 +741,11 @@ xmlParserInputShrink(xmlParserInputPtr in) { ************************************************************************/ /** - * @param ctxt the XML parser context + * Skip to the next char input char. * * @deprecated Internal function, do not use. * - * Skip to the next char input char. + * @param ctxt the XML parser context */ void @@ -845,14 +836,11 @@ encoding_error: } /** - * @param ctxt the XML parser context - * @param len pointer to the length of the char read - * - * @deprecated Internal function, do not use. - * * The current char value, if using UTF-8 this may actually span multiple * bytes in the input buffer. Implement the end of line normalization: * + * @deprecated Internal function, do not use. + * * 2.11 End-of-Line Handling * * Wherever an external parsed entity or the literal entity value @@ -862,6 +850,8 @@ encoding_error: * This behavior can conveniently be produced by normalizing all * line breaks to \#xA on input, before parsing.) * + * @param ctxt the XML parser context + * @param len pointer to the length of the char read * @returns the current char value and its length */ @@ -992,15 +982,14 @@ incomplete_sequence: } /** - * @param ctxt the XML parser context - * @param cur pointer to the beginning of the char - * @param len pointer to the length of the char read - * - * @deprecated Internal function, do not use. - * * The current char value, if using UTF-8 this may actually span multiple * bytes in the input buffer. * + * @deprecated Internal function, do not use. + * + * @param ctxt the XML parser context + * @param cur pointer to the beginning of the char + * @param len pointer to the length of the char read * @returns the current char value and its length */ @@ -1020,13 +1009,12 @@ xmlStringCurrentChar(xmlParserCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** - * @param out pointer to an array of xmlChar - * @param val the char value + * append the char value in the array * * @deprecated Internal function, don't use. * - * append the char value in the array - * + * @param out pointer to an array of xmlChar + * @param val the char value * @returns the number of xmlChar written */ int @@ -1062,14 +1050,13 @@ xmlCopyCharMultiByte(xmlChar *out, int val) { } /** - * @param len Ignored, compatibility - * @param out pointer to an array of xmlChar - * @param val the char value + * append the char value in the array * * @deprecated Don't use. * - * append the char value in the array - * + * @param len Ignored, compatibility + * @param out pointer to an array of xmlChar + * @param val the char value * @returns the number of xmlChar written */ @@ -1091,10 +1078,6 @@ xmlCopyChar(int len ATTRIBUTE_UNUSED, xmlChar *out, int val) { ************************************************************************/ /** - * @param ctxt parser context - * @param impl callback - * @param vctxt user data - * * Installs a custom implementation to convert between character * encodings. * @@ -1102,6 +1085,9 @@ xmlCopyChar(int len ATTRIBUTE_UNUSED, xmlChar *out, int val) { * encoding aliases. * * @since 2.14.0 + * @param ctxt parser context + * @param impl callback + * @param vctxt user data */ void xmlCtxtSetCharEncConvImpl(xmlParserCtxtPtr ctxt, xmlCharEncConvImpl impl, @@ -1197,15 +1183,14 @@ done: } /** - * @param ctxt the parser context - * @param enc the encoding value (number) - * * Use encoding specified by enum to decode input data. This overrides * the encoding found in the XML declaration. * * This function can also be used to override the encoding of chunks * passed to xmlParseChunk(). * + * @param ctxt the parser context + * @param enc the encoding value (number) * @returns 0 in case of success, -1 otherwise */ int @@ -1237,7 +1222,6 @@ xmlSwitchEncoding(xmlParserCtxtPtr ctxt, xmlCharEncoding enc) * @param ctxt the parser context * @param input the input strea, * @param encoding the encoding name - * * @returns 0 in case of success, -1 otherwise */ static int @@ -1270,9 +1254,6 @@ xmlSwitchInputEncodingName(xmlParserCtxtPtr ctxt, xmlParserInputPtr input, } /** - * @param ctxt the parser context - * @param encoding the encoding name - * * Use specified encoding to decode input data. This overrides the * encoding found in the XML declaration. * @@ -1281,6 +1262,8 @@ xmlSwitchInputEncodingName(xmlParserCtxtPtr ctxt, xmlParserInputPtr input, * * @since 2.13.0 * + * @param ctxt the parser context + * @param encoding the encoding name * @returns 0 in case of success, -1 otherwise */ int @@ -1292,13 +1275,12 @@ xmlSwitchEncodingName(xmlParserCtxtPtr ctxt, const char *encoding) { } /** - * @param input the input stream - * @param handler the encoding handler - * * Use encoding handler to decode input data. * * Closes the handler on error. * + * @param input the input stream + * @param handler the encoding handler * @returns an xmlParserErrors code. */ xmlParserErrors @@ -1391,14 +1373,13 @@ xmlInputSetEncodingHandler(xmlParserInputPtr input, } /** - * @param ctxt the parser context, only for error reporting - * @param input the input stream - * @param handler the encoding handler + * Use encoding handler to decode input data. * * @deprecated Internal function, don't use. * - * Use encoding handler to decode input data. - * + * @param ctxt the parser context, only for error reporting + * @param input the input stream + * @param handler the encoding handler * @returns 0 in case of success, -1 otherwise */ int @@ -1415,14 +1396,13 @@ xmlSwitchInputEncoding(xmlParserCtxtPtr ctxt, xmlParserInputPtr input, } /** - * @param ctxt the parser context - * @param handler the encoding handler - * * Use encoding handler to decode input data. * * This function can be used to enforce the encoding of chunks passed * to xmlParseChunk(). * + * @param ctxt the parser context + * @param handler the encoding handler * @returns 0 in case of success, -1 otherwise */ int @@ -1443,11 +1423,10 @@ xmlSwitchToEncoding(xmlParserCtxtPtr ctxt, xmlCharEncodingHandlerPtr handler) } /** - * @param ctxt the parser context - * * Handle optional BOM, detect and switch to encoding. * * Assumes that there are at least four bytes in the input buffer. + * @param ctxt the parser context */ void xmlDetectEncoding(xmlParserCtxtPtr ctxt) { @@ -1573,15 +1552,14 @@ xmlDetectEncoding(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt the parser context - * @param encoding declared encoding - * * Set the encoding from a declaration in the document. * * If no encoding was set yet, switch the encoding. Otherwise, only warn * about encoding mismatches. * * Takes ownership of 'encoding'. + * @param ctxt the parser context + * @param encoding declared encoding */ void xmlSetDeclaredEncoding(xmlParserCtxtPtr ctxt, xmlChar *encoding) { @@ -1669,10 +1647,9 @@ xmlSetDeclaredEncoding(xmlParserCtxtPtr ctxt, xmlChar *encoding) { } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns the encoding from the encoding declaration. This can differ * from the actual encoding. */ @@ -1686,7 +1663,6 @@ xmlCtxtGetDeclaredEncoding(xmlParserCtxtPtr ctxt) { /** * @param ctxt the parser context - * * @returns the actual used to parse the document. This can differ from * the declared encoding. */ @@ -1714,9 +1690,9 @@ xmlGetActualEncoding(xmlParserCtxtPtr ctxt) { ************************************************************************/ /** - * @param input an xmlParserInputPtr - * * Free up an input stream. + * + * @param input an xmlParserInputPtr */ void xmlFreeInputStream(xmlParserInputPtr input) { @@ -1732,12 +1708,11 @@ xmlFreeInputStream(xmlParserInputPtr input) { } /** - * @param ctxt an XML parser context + * Create a new input stream structure. * * @deprecated Use xmlNewInputFromUrl() or similar functions. * - * Create a new input stream structure. - * + * @param ctxt an XML parser context * @returns the new input stream or NULL */ xmlParserInputPtr @@ -1757,15 +1732,14 @@ xmlNewInputStream(xmlParserCtxtPtr ctxt) { } /** + * Creates a new parser input from the filesystem, the network or + * a user-defined resource loader. + * * @param ctxt parser context * @param url filename or URL * @param publicId publid ID from doctype (optional) * @param encoding character encoding (optional) * @param flags unused, pass 0 - * - * Creates a new parser input from the filesystem, the network or - * a user-defined resource loader. - * * @returns a new parser input. */ xmlParserInputPtr @@ -1788,11 +1762,10 @@ xmlCtxtNewInputFromUrl(xmlParserCtxtPtr ctxt, const char *url, } /** - * @param buf parser input buffer - * @param filename filename or URL - * * Internal helper function. * + * @param buf parser input buffer + * @param filename filename or URL * @returns a new parser input. */ static xmlParserInputPtr @@ -1823,11 +1796,6 @@ xmlNewInputInternal(xmlParserInputBufferPtr buf, const char *filename) { } /** - * @param url base URL (optional) - * @param mem pointer to char array - * @param size size of array - * @param flags optimization hints - * * Creates a new parser input to read from a memory area. * * `url` is used as base to resolve external entities and for @@ -1843,6 +1811,10 @@ xmlNewInputInternal(xmlParserInputBufferPtr buf, const char *filename) { * * @since 2.14.0 * + * @param url base URL (optional) + * @param mem pointer to char array + * @param size size of array + * @param flags optimization hints * @returns a new parser input or NULL if a memory allocation failed. */ xmlParserInputPtr @@ -1867,7 +1839,6 @@ xmlNewInputFromMemory(const char *url, const void *mem, size_t size, * @param size size of array * @param encoding character encoding (optional) * @param flags optimization hints - * * @returns a new parser input or NULL in case of error. */ xmlParserInputPtr @@ -1892,10 +1863,6 @@ xmlCtxtNewInputFromMemory(xmlParserCtxtPtr ctxt, const char *url, } /** - * @param url base URL (optional) - * @param str zero-terminated string - * @param flags optimization hints - * * Creates a new parser input to read from a zero-terminated string. * * `url` is used as base to resolve external entities and for @@ -1907,6 +1874,9 @@ xmlCtxtNewInputFromMemory(xmlParserCtxtPtr ctxt, const char *url, * * @since 2.14.0 * + * @param url base URL (optional) + * @param str zero-terminated string + * @param flags optimization hints * @returns a new parser input or NULL if a memory allocation failed. */ xmlParserInputPtr @@ -1930,7 +1900,6 @@ xmlNewInputFromString(const char *url, const char *str, * @param str zero-terminated string * @param encoding character encoding (optional) * @param flags optimization hints - * * @returns a new parser input. */ xmlParserInputPtr @@ -1955,10 +1924,6 @@ xmlCtxtNewInputFromString(xmlParserCtxtPtr ctxt, const char *url, } /** - * @param url base URL (optional) - * @param fd file descriptor - * @param flags input flags - * * Creates a new parser input to read from a zero-terminated string. * * `url` is used as base to resolve external entities and for @@ -1972,6 +1937,9 @@ xmlCtxtNewInputFromString(xmlParserCtxtPtr ctxt, const char *url, * * @since 2.14.0 * + * @param url base URL (optional) + * @param fd file descriptor + * @param flags input flags * @returns a new parser input or NULL if a memory allocation failed. */ xmlParserInputPtr @@ -1999,7 +1967,6 @@ xmlNewInputFromFd(const char *url, int fd, xmlParserInputFlags flags) { * @param fd file descriptor * @param encoding character encoding (optional) * @param flags unused, pass 0 - * * @returns a new parser input. */ xmlParserInputPtr @@ -2027,12 +1994,6 @@ xmlCtxtNewInputFromFd(xmlParserCtxtPtr ctxt, const char *url, } /** - * @param url base URL (optional) - * @param ioRead read callback - * @param ioClose close callback (optional) - * @param ioCtxt IO context - * @param flags unused, pass 0 - * * Creates a new parser input to read from input callbacks and * cintext. * @@ -2049,6 +2010,11 @@ xmlCtxtNewInputFromFd(xmlParserCtxtPtr ctxt, const char *url, * * @since 2.14.0 * + * @param url base URL (optional) + * @param ioRead read callback + * @param ioClose close callback (optional) + * @param ioCtxt IO context + * @param flags unused, pass 0 * @returns a new parser input or NULL if a memory allocation failed. */ xmlParserInputPtr @@ -2082,7 +2048,6 @@ xmlNewInputFromIO(const char *url, xmlInputReadCallback ioRead, * @param ioCtxt IO context * @param encoding character encoding (optional) * @param flags unused, pass 0 - * * @returns a new parser input. */ xmlParserInputPtr @@ -2109,12 +2074,11 @@ xmlCtxtNewInputFromIO(xmlParserCtxtPtr ctxt, const char *url, } /** + * Creates a new parser input for a push parser. + * * @param url base URL (optional) * @param chunk pointer to char array * @param size size of array - * - * Creates a new parser input for a push parser. - * * @returns a new parser input or NULL if a memory allocation failed. */ xmlParserInputPtr @@ -2147,13 +2111,12 @@ xmlNewPushInput(const char *url, const char *chunk, int size) { } /** - * @param ctxt an XML parser context - * @param buf an input buffer - * @param enc the charset encoding if known - * * Create a new input stream structure encapsulating the `input` into * a stream suitable for the parser. * + * @param ctxt an XML parser context + * @param buf an input buffer + * @param enc the charset encoding if known * @returns the new input stream or NULL */ xmlParserInputPtr @@ -2179,13 +2142,12 @@ xmlNewIOInputStream(xmlParserCtxtPtr ctxt, xmlParserInputBufferPtr buf, } /** - * @param ctxt an XML parser context - * @param ent an Entity pointer + * Create a new input stream based on an xmlEntityPtr * * @deprecated Internal function, do not use. * - * Create a new input stream based on an xmlEntityPtr - * + * @param ctxt an XML parser context + * @param ent an Entity pointer * @returns the new input stream or NULL */ xmlParserInputPtr @@ -2221,13 +2183,12 @@ xmlNewEntityInputStream(xmlParserCtxtPtr ctxt, xmlEntityPtr ent) { } /** - * @param ctxt an XML parser context - * @param buffer an memory buffer + * Create a new input stream based on a memory buffer. * * @deprecated Use xmlNewInputFromString(). * - * Create a new input stream based on a memory buffer. - * + * @param ctxt an XML parser context + * @param buffer an memory buffer * @returns the new input stream */ xmlParserInputPtr @@ -2246,14 +2207,13 @@ xmlNewStringInputStream(xmlParserCtxtPtr ctxt, const xmlChar *buffer) { #ifdef LIBXML_CATALOG_ENABLED /** - * @param URL the URL for the entity to load - * @param ID the System ID for the entity to load - * @param ctxt the context in which the entity is called or NULL - * * Resolves the URL and ID against the appropriate catalog. * This function is used by xmlDefaultExternalEntityLoader() and * xmlNoNetExternalEntityLoader(). * + * @param URL the URL for the entity to load + * @param ID the System ID for the entity to load + * @param ctxt the context in which the entity is called or NULL * @returns a new allocated URL, or NULL. */ static xmlChar * @@ -2332,11 +2292,10 @@ xmlResolveResourceFromCatalog(const char *URL, const char *ID, #endif /** - * @param ctxt an XML parser context - * @param ret an XML parser input - * * @deprecated Internal function, don't use. * + * @param ctxt an XML parser context + * @param ret an XML parser input * @returns NULL. */ xmlParserInputPtr @@ -2346,10 +2305,6 @@ xmlCheckHTTPInput(xmlParserCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** - * @param filename the filename to use as entity - * @param flags XML_INPUT flags - * @param out pointer to new parser input - * * Create a new input stream based on a file or a URL. * * The flag XML_INPUT_UNZIP allows decompression. @@ -2369,6 +2324,9 @@ xmlCheckHTTPInput(xmlParserCtxtPtr ctxt ATTRIBUTE_UNUSED, * * @since 2.14.0 * + * @param filename the filename to use as entity + * @param flags XML_INPUT flags + * @param out pointer to new parser input * @returns an xmlParserErrors code. */ xmlParserErrors @@ -2405,13 +2363,12 @@ xmlNewInputFromUrl(const char *filename, xmlParserInputFlags flags, } /** - * @param ctxt an XML parser context - * @param filename the filename to use as entity + * Create a new input stream based on a file or an URL. * * @deprecated Use xmlNewInputFromUrl(). * - * Create a new input stream based on a file or an URL. - * + * @param ctxt an XML parser context + * @param filename the filename to use as entity * @returns the new input stream or NULL in case of error */ xmlParserInputPtr @@ -2438,12 +2395,11 @@ xmlNewInputFromFile(xmlParserCtxtPtr ctxt, const char *filename) { } /** + * By default we don't load external entities, yet. + * * @param url the URL for the entity to load * @param ID the System ID for the entity to load * @param ctxt the context in which the entity is called or NULL - * - * By default we don't load external entities, yet. - * * @returns a new allocated xmlParserInputPtr, or NULL. */ static xmlParserInputPtr @@ -2482,15 +2438,14 @@ xmlDefaultExternalEntityLoader(const char *url, const char *ID, } /** - * @param URL the URL for the entity to load - * @param ID the System ID for the entity to load - * @param ctxt the context in which the entity is called or NULL - * - * @deprecated Use XML_PARSE_NONET. - * * A specific entity loader disabling network accesses, though still * allowing local catalog accesses for resolution. * + * @deprecated Use XML_PARSE_NONET. + * + * @param URL the URL for the entity to load + * @param ID the System ID for the entity to load + * @param ctxt the context in which the entity is called or NULL * @returns a new allocated xmlParserInputPtr, or NULL. */ xmlParserInputPtr @@ -2519,13 +2474,13 @@ static xmlExternalEntityLoader xmlCurrentExternalEntityLoader = xmlDefaultExternalEntityLoader; /** - * @param f the new entity resolver function + * Changes the default external entity resolver function for the + * application. * * @deprecated This is a global setting and not thread-safe. Use * xmlCtxtSetResourceLoader() or similar functions. * - * Changes the default external entity resolver function for the - * application. + * @param f the new entity resolver function */ void xmlSetExternalEntityLoader(xmlExternalEntityLoader f) { @@ -2533,10 +2488,10 @@ xmlSetExternalEntityLoader(xmlExternalEntityLoader f) { } /** - * @deprecated See xmlSetExternalEntityLoader(). - * * Get the default external entity resolver function for the application * + * @deprecated See xmlSetExternalEntityLoader(). + * * @returns the xmlExternalEntityLoader() function pointer */ xmlExternalEntityLoader @@ -2545,14 +2500,13 @@ xmlGetExternalEntityLoader(void) { } /** - * @param ctxt parser context - * @param loader callback - * @param vctxt user data - * * Installs a custom callback to load documents, DTDs or external * entities. * * @since 2.14.0 + * @param ctxt parser context + * @param loader callback + * @param vctxt user data */ void xmlCtxtSetResourceLoader(xmlParserCtxtPtr ctxt, xmlResourceLoader loader, @@ -2569,7 +2523,6 @@ xmlCtxtSetResourceLoader(xmlParserCtxtPtr ctxt, xmlResourceLoader loader, * @param url the URL for the entity to load * @param publicId the Public ID for the entity to load * @param type resource type - * * @returns the xmlParserInputPtr or NULL in case of error. */ xmlParserInputPtr @@ -2620,10 +2573,6 @@ xmlLoadResource(xmlParserCtxtPtr ctxt, const char *url, const char *publicId, } /** - * @param URL the URL for the entity to load - * @param ID the Public ID for the entity to load - * @param ctxt the context in which the entity is called or NULL - * * `URL` is a filename or URL. If if contains the substring "://", * it is assumed to be a Legacy Extended IRI. Otherwise, it is * treated as a filesystem path. @@ -2648,6 +2597,9 @@ xmlLoadResource(xmlParserCtxtPtr ctxt, const char *url, const char *publicId, * - a file opened from the filesystem, with automatic detection * of compressed files if support is compiled in. * + * @param URL the URL for the entity to load + * @param ID the Public ID for the entity to load + * @param ctxt the context in which the entity is called or NULL * @returns the xmlParserInputPtr or NULL */ xmlParserInputPtr @@ -2663,12 +2615,11 @@ xmlLoadExternalEntity(const char *URL, const char *ID, ************************************************************************/ /** + * Initialize a SAX parser context + * * @param ctxt XML parser context * @param sax SAX handlert * @param userData user data - * - * Initialize a SAX parser context - * * @returns 0 in case of success and -1 in case of error */ @@ -2833,13 +2784,12 @@ xmlInitSAXParserCtxt(xmlParserCtxtPtr ctxt, const xmlSAXHandler *sax, } /** - * @param ctxt an XML parser context + * Initialize a parser context * * @deprecated Internal function which will be made private in a future * version. * - * Initialize a parser context - * + * @param ctxt an XML parser context * @returns 0 in case of success and -1 in case of error */ @@ -2850,10 +2800,10 @@ xmlInitParserCtxt(xmlParserCtxtPtr ctxt) } /** - * @param ctxt an XML parser context - * * Free all the memory used by a parser context. However the parsed * document in ctxt->myDoc is not freed. + * + * @param ctxt an XML parser context */ void @@ -2949,9 +2899,6 @@ xmlNewParserCtxt(void) } /** - * @param sax SAX handler - * @param userData user data - * * Allocate and initialize a new SAX parser context. If userData is NULL, * the parser context will be passed as user data. * @@ -2961,6 +2908,8 @@ xmlNewParserCtxt(void) * it's best to invoke xmlNewParserCtxt() and set ctxt->sax with * struct assignment. * + * @param sax SAX handler + * @param userData user data * @returns the xmlParserCtxtPtr or NULL if memory allocation failed. */ @@ -2983,10 +2932,9 @@ xmlNewSAXParserCtxt(const xmlSAXHandler *sax, void *userData) } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns the private application data. */ void * @@ -2998,12 +2946,12 @@ xmlCtxtGetPrivate(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt parser context - * @param priv private application data + * Set the private application data. * * @since 2.14.0 * - * Set the private application data. + * @param ctxt parser context + * @param priv private application data */ void xmlCtxtSetPrivate(xmlParserCtxtPtr ctxt, void *priv) { @@ -3014,10 +2962,9 @@ xmlCtxtSetPrivate(xmlParserCtxtPtr ctxt, void *priv) { } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns the local catalogs. */ void * @@ -3029,12 +2976,12 @@ xmlCtxtGetCatalogs(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt parser context - * @param catalogs catalogs pointer + * Set the local catalogs. * * @since 2.14.0 * - * Set the local catalogs. + * @param ctxt parser context + * @param catalogs catalogs pointer */ void xmlCtxtSetCatalogs(xmlParserCtxtPtr ctxt, void *catalogs) { @@ -3045,10 +2992,9 @@ xmlCtxtSetCatalogs(xmlParserCtxtPtr ctxt, void *catalogs) { } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns the dictionary. */ xmlDictPtr @@ -3060,13 +3006,13 @@ xmlCtxtGetDict(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt parser context - * @param dict dictionary + * Set the dictionary. This should only be done immediately after + * creating a parser context. * * @since 2.14.0 * - * Set the dictionary. This should only be done immediately after - * creating a parser context. + * @param ctxt parser context + * @param dict dictionary */ void xmlCtxtSetDict(xmlParserCtxtPtr ctxt, xmlDictPtr dict) { @@ -3081,10 +3027,9 @@ xmlCtxtSetDict(xmlParserCtxtPtr ctxt, xmlDictPtr dict) { } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns the SAX handler struct. This is not a copy and must not * be freed. Handlers can be updated. */ @@ -3097,13 +3042,12 @@ xmlCtxtGetSaxHandler(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt parser context - * @param sax SAX handler + * Set the SAX handler struct to a copy of `sax`. * * @since 2.14.0 * - * Set the SAX handler struct to a copy of `sax`. - * + * @param ctxt parser context + * @param sax SAX handler * @returns 0 on success or -1 if arguments are invalid or a memory * allocation failed. */ @@ -3125,10 +3069,9 @@ xmlCtxtSetSaxHandler(xmlParserCtxtPtr ctxt, const xmlSAXHandler *sax) { } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns the parsed document or NULL if a fatal error occurred when * parsing. The document must be freed by the caller. Resets the * context's document to NULL. @@ -3156,10 +3099,9 @@ xmlCtxtGetDocument(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns 1 if this is a HTML parser context, 0 otherwise. */ int @@ -3171,10 +3113,9 @@ xmlCtxtIsHtml(xmlParserCtxtPtr ctxt) { } /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns 1 if the parser is stopped, 0 otherwise. */ int @@ -3187,10 +3128,9 @@ xmlCtxtIsStopped(xmlParserCtxtPtr ctxt) { #ifdef LIBXML_VALID_ENABLED /** - * @param ctxt parser context - * * @since 2.14.0 * + * @param ctxt parser context * @returns the validation context. */ xmlValidCtxtPtr @@ -3209,11 +3149,11 @@ xmlCtxtGetValidCtxt(xmlParserCtxtPtr ctxt) { ************************************************************************/ /** - * @param ctxt an XML parser context + * Same as xmlCtxtReset() * * @deprecated Use xmlCtxtReset() * - * Same as xmlCtxtReset() + * @param ctxt an XML parser context */ void xmlClearParserCtxt(xmlParserCtxtPtr ctxt) @@ -3223,13 +3163,12 @@ xmlClearParserCtxt(xmlParserCtxtPtr ctxt) /** - * @param ctx an XML parser context - * @param node an XML node within the tree + * Find the parser node info struct for a given node * * @deprecated Don't use. * - * Find the parser node info struct for a given node - * + * @param ctx an XML parser context + * @param node an XML node within the tree * @returns an xmlParserNodeInfo block pointer or NULL */ const xmlParserNodeInfo * @@ -3250,11 +3189,11 @@ xmlParserFindNodeInfo(xmlParserCtxtPtr ctx, xmlNodePtr node) /** - * @param seq a node info sequence pointer + * Initialize (set to initial state) node info sequence * * @deprecated Don't use. * - * Initialize (set to initial state) node info sequence + * @param seq a node info sequence pointer */ void xmlInitNodeInfoSeq(xmlParserNodeInfoSeqPtr seq) @@ -3267,11 +3206,11 @@ xmlInitNodeInfoSeq(xmlParserNodeInfoSeqPtr seq) } /** - * @param seq a node info sequence pointer + * Clear (release memory and reinitialize) node info sequence * * @deprecated Don't use. * - * Clear (release memory and reinitialize) node info sequence + * @param seq a node info sequence pointer */ void xmlClearNodeInfoSeq(xmlParserNodeInfoSeqPtr seq) @@ -3284,14 +3223,13 @@ xmlClearNodeInfoSeq(xmlParserNodeInfoSeqPtr seq) } /** - * @param seq a node info sequence pointer - * @param node an XML node pointer - * - * @deprecated Don't use. - * * Find the index that the info record for the given node is or * should be at in a sorted sequence. * + * @deprecated Don't use. + * + * @param seq a node info sequence pointer + * @param node an XML node pointer * @returns a long indicating the position of the record */ unsigned long @@ -3327,12 +3265,12 @@ xmlParserFindNodeInfoIndex(xmlParserNodeInfoSeqPtr seq, /** - * @param ctxt an XML parser context - * @param info a node info sequence pointer + * Insert node info record into the sorted sequence * * @deprecated Don't use. * - * Insert node info record into the sorted sequence + * @param ctxt an XML parser context + * @param info a node info sequence pointer */ void xmlParserAddNodeInfo(xmlParserCtxtPtr ctxt, @@ -3393,12 +3331,11 @@ xmlParserAddNodeInfo(xmlParserCtxtPtr ctxt, * * ************************************************************************/ /** - * @param val int 0 or 1 + * Set and return the previous value for enabling pedantic warnings. * * @deprecated Use the modern options API with XML_PARSE_PEDANTIC. * - * Set and return the previous value for enabling pedantic warnings. - * + * @param val int 0 or 1 * @returns the last value for 0 for no substitution, 1 for substitution. */ @@ -3411,13 +3348,12 @@ xmlPedanticParserDefault(int val) { } /** - * @param val int 0 or 1 - * - * @deprecated The modern options API always enables line numbers. - * * Set and return the previous value for enabling line numbers in elements * contents. This may break on old application and is turned off by default. * + * @deprecated The modern options API always enables line numbers. + * + * @param val int 0 or 1 * @returns the last value for 0 for no substitution, 1 for substitution. */ @@ -3430,10 +3366,6 @@ xmlLineNumbersDefault(int val) { } /** - * @param val int 0 or 1 - * - * @deprecated Use the modern options API with XML_PARSE_NOENT. - * * 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 @@ -3441,6 +3373,9 @@ xmlLineNumbersDefault(int val) { * 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. + * + * @param val int 0 or 1 * @returns the last value for 0 for no substitution, 1 for substitution. */ @@ -3453,10 +3388,6 @@ xmlSubstituteEntitiesDefault(int val) { } /** - * @param val int 0 or 1 - * - * @deprecated Use the modern options API with XML_PARSE_NOBLANKS. - * * 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 @@ -3474,6 +3405,9 @@ xmlSubstituteEntitiesDefault(int val) { * 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. + * + * @param val int 0 or 1 * @returns the last value for 0 for no substitution, 1 for substitution. */ diff --git a/pattern.c b/pattern.c index bad9d6f4..8a6a78e2 100644 --- a/pattern.c +++ b/pattern.c @@ -213,9 +213,9 @@ xmlNewPattern(void) { } /** - * @param comp an XSLT comp - * * Free up the memory allocated by `comp` + * + * @param comp an XSLT comp */ void xmlFreePattern(xmlPatternPtr comp) { @@ -253,9 +253,9 @@ xmlFreePatternInternal(xmlPatternPtr comp) { } /** - * @param comp an XSLT comp list - * * Free up the memory allocated by all the elements of `comp` + * + * @param comp an XSLT comp list */ void xmlFreePatternList(xmlPatternPtr comp) { @@ -270,13 +270,12 @@ xmlFreePatternList(xmlPatternPtr comp) { } /** + * Create a new XML pattern parser context + * * @param pattern the pattern context * @param dict the inherited dictionary or NULL * @param namespaces the prefix definitions, array of [URI, prefix] terminated * with [NULL, NULL] or NULL if no namespace is used - * - * Create a new XML pattern parser context - * * @returns the newly allocated xmlPatParserContextPtr or NULL in case of error */ static xmlPatParserContextPtr @@ -310,9 +309,9 @@ xmlNewPatParserContext(const xmlChar *pattern, xmlDictPtr dict, } /** - * @param ctxt an XSLT parser context - * * Free up the memory allocated by `ctxt` + * + * @param ctxt an XSLT parser context */ static void xmlFreePatParserContext(xmlPatParserContextPtr ctxt) { @@ -341,14 +340,13 @@ xmlPatternGrow(xmlPatternPtr comp) { } /** + * Add a step to an XSLT Compiled Match + * * @param ctxt the pattern parser context * @param comp the compiled match expression * @param op an op * @param value the first value * @param value2 the second value - * - * Add a step to an XSLT Compiled Match - * * @returns -1 in case of failure, 0 otherwise. */ static int @@ -369,10 +367,9 @@ xmlPatternAdd(xmlPatParserContextPtr ctxt, xmlPatternPtr comp, } /** - * @param comp the compiled match expression - * * reverse all the stack of expressions * + * @param comp the compiled match expression * @returns 0 in case of success and -1 in case of error. */ static int @@ -451,11 +448,10 @@ xmlPatPushState(xmlStepStates *states, int step, xmlNodePtr node) { } /** - * @param comp the precompiled pattern - * @param node a node - * * Test whether the node matches the pattern * + * @param comp the precompiled pattern + * @param node a node * @returns 1 if it matches, 0 if it doesn't and -1 in case of failure */ static int @@ -675,8 +671,6 @@ rollback: if (xmlPatternAdd(ctxt, ctxt->comp, (op), (val), (val2))) goto error; /** - * @param ctxt the XPath Parser context - * * [4] NameChar ::= Letter | Digit | '.' | '-' | '_' | * CombiningChar | Extender * @@ -684,6 +678,7 @@ rollback: * * [6] Names ::= Name (S Name)* * + * @param ctxt the XPath Parser context * @returns the Name parsed or NULL */ @@ -717,10 +712,9 @@ xmlPatScanName(xmlPatParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Parses a non qualified name * + * @param ctxt the XPath Parser context * @returns the Name parsed or NULL */ @@ -756,9 +750,9 @@ xmlPatScanNCName(xmlPatParserContextPtr ctxt) { } /** - * @param ctxt the compilation context - * * Compile an attribute test. + * + * @param ctxt the compilation context */ static void xmlCompileAttributeTest(xmlPatParserContextPtr ctxt) { @@ -846,13 +840,12 @@ error: } /** - * @param ctxt the compilation context - * * Compile the Step Pattern and generates a precompiled * form suitable for fast matching. * * [3] Step ::= '.' | NameTest * [4] NameTest ::= QName | '*' | NCName ':' '*' + * @param ctxt the compilation context */ static void @@ -1068,12 +1061,11 @@ error: } /** - * @param ctxt the compilation context - * * Compile the Path Pattern and generates a precompiled * form suitable for fast matching. * * [5] Path ::= ('.//')? ( Step '/' )* ( Step | '@' NameTest ) + * @param ctxt the compilation context */ static void xmlCompilePathPattern(xmlPatParserContextPtr ctxt) { @@ -1166,12 +1158,11 @@ error: } /** - * @param ctxt the compilation context - * * Compile the Path Pattern and generates a precompiled * form suitable for fast matching. * * [5] Path ::= ('.//')? ( Step '/' )* ( Step | '@' NameTest ) + * @param ctxt the compilation context */ static void xmlCompileIDCXPathPath(xmlPatParserContextPtr ctxt) { @@ -1271,10 +1262,9 @@ error_unfinished: ************************************************************************/ /** - * @param size the number of expected steps - * * build a new compiled pattern for streaming * + * @param size the number of expected steps * @returns the new structure or NULL in case of error. */ static xmlStreamCompPtr @@ -1304,9 +1294,9 @@ xmlNewStreamComp(int size) { } /** - * @param comp the compiled pattern for streaming - * * Free the compiled pattern for streaming + * + * @param comp the compiled pattern for streaming */ static void xmlFreeStreamComp(xmlStreamCompPtr comp) { @@ -1320,14 +1310,13 @@ xmlFreeStreamComp(xmlStreamCompPtr comp) { } /** + * Add a new step to the compiled pattern + * * @param comp the compiled pattern for streaming * @param name the first string, the name, or NULL for * * @param ns the second step, the namespace name * @param nodeType the node type * @param flags the flags for that step - * - * Add a new step to the compiled pattern - * * @returns -1 in case of error or the step index if successful */ static int @@ -1364,10 +1353,9 @@ xmlStreamCompAddStep(xmlStreamCompPtr comp, const xmlChar *name, } /** - * @param comp the precompiled pattern - * * Tries to stream compile a pattern * + * @param comp the precompiled pattern * @returns -1 in case of failure and 0 in case of success. */ static int @@ -1542,10 +1530,9 @@ error: } /** - * @param stream the copmiled stream - * * build a new stream context * + * @param stream the copmiled stream * @returns the new structure or NULL in case of error. */ static xmlStreamCtxtPtr @@ -1569,9 +1556,9 @@ xmlNewStreamCtxt(xmlStreamCompPtr stream) { } /** - * @param stream the stream context - * * Free the stream context + * + * @param stream the stream context */ void xmlFreeStreamCtxt(xmlStreamCtxtPtr stream) { @@ -1587,12 +1574,11 @@ xmlFreeStreamCtxt(xmlStreamCtxtPtr stream) { } /** + * Add a new state to the stream context + * * @param comp the stream context * @param idx the step index for that streaming state * @param level the level - * - * Add a new state to the stream context - * * @returns -1 in case of error or the state index if successful */ static int @@ -1631,17 +1617,16 @@ xmlStreamCtxtAddState(xmlStreamCtxtPtr comp, int idx, int level) { } /** - * @param stream the stream context - * @param name the current name - * @param ns the namespace name - * @param nodeType the type of the node - * * Push new data onto the stream. NOTE: if the call xmlPatterncompile() * indicated a dictionary, then strings for name and ns will be expected * to come from the dictionary. * Both `name` and `ns` being NULL means the / i.e. the root of the document. * This can also act as a reset. * + * @param stream the stream context + * @param name the current name + * @param ns the namespace name + * @param nodeType the type of the node * @returns -1 in case of error, 1 if the current state in the stream is a * match and 0 otherwise. */ @@ -1954,10 +1939,6 @@ stream_next: } /** - * @param stream the stream context - * @param name the current name - * @param ns the namespace name - * * Push new data onto the stream. NOTE: if the call xmlPatterncompile() * indicated a dictionary, then strings for name and ns will be expected * to come from the dictionary. @@ -1965,6 +1946,9 @@ stream_next: * This can also act as a reset. * Otherwise the function will act as if it has been given an element-node. * + * @param stream the stream context + * @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. */ @@ -1975,11 +1959,6 @@ xmlStreamPush(xmlStreamCtxtPtr stream, } /** - * @param stream the stream context - * @param name the current name - * @param ns the namespace name - * @param nodeType the type of the node being pushed - * * Push new data onto the stream. NOTE: if the call xmlPatterncompile() * indicated a dictionary, then strings for name and ns will be expected * to come from the dictionary. @@ -1989,6 +1968,10 @@ xmlStreamPush(xmlStreamCtxtPtr stream, * element-, attribute-, text-, cdata-section-, comment- and * processing-instruction-node. * + * @param stream the stream context + * @param name the current name + * @param ns the namespace name + * @param nodeType the type of the node being pushed * @returns -1 in case of error, 1 if the current state in the stream is a * match and 0 otherwise. */ @@ -2003,6 +1986,7 @@ xmlStreamPushNode(xmlStreamCtxtPtr stream, /** * xmlStreamPushAttr: + * * @stream: the stream context * @name: the current name * @ns: the namespace name @@ -2024,10 +2008,9 @@ xmlStreamPushAttr(xmlStreamCtxtPtr stream, } /** - * @param stream the stream context - * * push one level from the stream. * + * @param stream the stream context * @returns -1 in case of error, 0 otherwise. */ int @@ -2067,13 +2050,12 @@ xmlStreamPop(xmlStreamCtxtPtr stream) { } /** - * @param streamCtxt the stream context - * * Query if the streaming pattern additionally needs to be fed with * text-, cdata-section-, comment- and processing-instruction-nodes. * If the result is 0 then only element-nodes and attribute-nodes * need to be pushed. * + * @param streamCtxt the stream context * @returns 1 in case of need of nodes of the above described types, * 0 otherwise. -1 on API errors. */ @@ -2097,16 +2079,15 @@ xmlStreamWantsAnyNode(xmlStreamCtxtPtr streamCtxt) ************************************************************************/ /** + * Compile a pattern. + * + * @since 2.13.0 + * * @param pattern the pattern to compile * @param dict an optional dictionary for interned strings * @param flags compilation flags, see xmlPatternFlags * @param namespaces the prefix definitions, array of [URI, prefix] or NULL * @param patternOut output pattern - * - * Compile a pattern. - * - * @since 2.13.0 - * * @returns 0 on success, 1 on error, -1 if a memory allocation failed. */ int @@ -2226,13 +2207,12 @@ error: } /** + * Compile a pattern. + * * @param pattern the pattern to compile * @param dict an optional dictionary for interned strings * @param flags compilation flags, see xmlPatternFlags * @param namespaces the prefix definitions, array of [URI, prefix] or NULL - * - * Compile a pattern. - * * @returns the compiled form of the pattern or NULL in case of error */ xmlPatternPtr @@ -2244,11 +2224,10 @@ xmlPatterncompile(const xmlChar *pattern, xmlDict *dict, int flags, } /** - * @param comp the precompiled pattern - * @param node a node - * * Test whether the node matches the pattern * + * @param comp the precompiled pattern + * @param node a node * @returns 1 if it matches, 0 if it doesn't and -1 in case of failure */ int @@ -2269,11 +2248,10 @@ xmlPatternMatch(xmlPatternPtr comp, xmlNodePtr node) } /** - * @param comp the precompiled pattern - * * Get a streaming context for that pattern * Use xmlFreeStreamCtxt() to free the context. * + * @param comp the precompiled pattern * @returns a pointer to the context or NULL in case of failure */ xmlStreamCtxtPtr @@ -2306,11 +2284,10 @@ failed: } /** - * @param comp the precompiled pattern - * * Check if the pattern is streamable i.e. xmlPatternGetStreamCtxt() * should work. * + * @param comp the precompiled pattern * @returns 1 if streamable, 0 if not and -1 in case of error. */ int @@ -2326,10 +2303,9 @@ xmlPatternStreamable(xmlPatternPtr comp) { } /** - * @param comp the precompiled pattern - * * Check the maximum depth reachable by a pattern * + * @param comp the precompiled pattern * @returns -2 if no limit (using //), otherwise the depth, * and -1 in case of error */ @@ -2352,13 +2328,11 @@ xmlPatternMaxDepth(xmlPatternPtr comp) { } /** - * @param comp the precompiled pattern - * * Check the minimum depth reachable by a pattern, 0 mean the / or . are * part of the set. * + * @param comp the precompiled pattern * @returns -1 in case of error otherwise the depth, - * */ int xmlPatternMinDepth(xmlPatternPtr comp) { @@ -2378,10 +2352,9 @@ xmlPatternMinDepth(xmlPatternPtr comp) { } /** - * @param comp the precompiled pattern - * * Check if the pattern must be looked at from the root. * + * @param comp the precompiled pattern * @returns 1 if true, 0 if false and -1 in case of error */ int diff --git a/relaxng.c b/relaxng.c index 96688a6c..125bad69 100644 --- a/relaxng.c +++ b/relaxng.c @@ -387,9 +387,9 @@ struct _xmlRelaxNGDocument { ************************************************************************/ /** - * @param ctxt an Relax-NG parser context - * * Handle a redefinition of attribute error + * + * @param ctxt an Relax-NG parser context */ static void xmlRngPErrMemory(xmlRelaxNGParserCtxtPtr ctxt) @@ -411,9 +411,9 @@ xmlRngPErrMemory(xmlRelaxNGParserCtxtPtr ctxt) } /** - * @param ctxt a Relax-NG validation context - * * Handle a redefinition of attribute error + * + * @param ctxt a Relax-NG validation context */ static void xmlRngVErrMemory(xmlRelaxNGValidCtxtPtr ctxt) @@ -435,14 +435,14 @@ xmlRngVErrMemory(xmlRelaxNGValidCtxtPtr ctxt) } /** + * Handle a Relax NG Parsing error + * * @param ctxt a Relax-NG parser context * @param node the node raising the error * @param error the error code * @param msg message * @param str1 extra info * @param str2 extra info - * - * Handle a Relax NG Parsing error */ static void LIBXML_ATTR_FORMAT(4,0) xmlRngPErr(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node, int error, @@ -476,14 +476,14 @@ xmlRngPErr(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node, int error, } /** + * Handle a Relax NG Validation error + * * @param ctxt a Relax-NG validation context * @param node the node raising the error * @param error the error code * @param msg message * @param str1 extra info * @param str2 extra info - * - * Handle a Relax NG Validation error */ static void LIBXML_ATTR_FORMAT(4,0) xmlRngVErr(xmlRelaxNGValidCtxtPtr ctxt, xmlNodePtr node, int error, @@ -523,23 +523,21 @@ xmlRngVErr(xmlRelaxNGValidCtxtPtr ctxt, xmlNodePtr node, int error, ************************************************************************/ /** - * @param data data needed for the library - * @param type the type name - * * Function provided by a type library to check if a type is exported * + * @param data data needed for the library + * @param type the type name * @returns 1 if yes, 0 if no and -1 in case of error. */ typedef int (*xmlRelaxNGTypeHave) (void *data, const xmlChar * type); /** + * Function provided by a type library to check if a value match a type + * * @param data data needed for the library * @param type the type name * @param value the value to check * @param result place to store the result if needed - * - * Function provided by a type library to check if a value match a type - * * @returns 1 if yes, 0 if no and -1 in case of error. */ typedef int (*xmlRelaxNGTypeCheck) (void *data, const xmlChar * type, @@ -547,15 +545,14 @@ typedef int (*xmlRelaxNGTypeCheck) (void *data, const xmlChar * type, xmlNodePtr node); /** + * Function provided by a type library to check a value facet + * * @param data data needed for the library * @param type the type name * @param facet the facet name * @param val the facet value * @param strval the string value * @param value the value to check - * - * Function provided by a type library to check a value facet - * * @returns 1 if yes, 0 if no and -1 in case of error. */ typedef int (*xmlRelaxNGFacetCheck) (void *data, const xmlChar * type, @@ -564,22 +561,21 @@ typedef int (*xmlRelaxNGFacetCheck) (void *data, const xmlChar * type, const xmlChar * strval, void *value); /** + * Function provided by a type library to free a returned result + * * @param data data needed for the library * @param result the value to free - * - * Function provided by a type library to free a returned result */ typedef void (*xmlRelaxNGTypeFree) (void *data, void *result); /** + * Function provided by a type library to compare two values accordingly + * to a type. + * * @param data data needed for the library * @param type the type name * @param value1 the first value * @param value2 the second value - * - * Function provided by a type library to compare two values accordingly - * to a type. - * * @returns 1 if yes, 0 if no and -1 in case of error. */ typedef int (*xmlRelaxNGTypeCompare) (void *data, const xmlChar * type, @@ -617,9 +613,9 @@ static void xmlRelaxNGFreeValidState(xmlRelaxNGValidCtxtPtr ctxt, xmlRelaxNGValidStatePtr state); /** - * @param docu a document structure - * * Deallocate a RelaxNG document structure. + * + * @param docu a document structure */ static void xmlRelaxNGFreeDocument(xmlRelaxNGDocumentPtr docu) @@ -637,9 +633,9 @@ xmlRelaxNGFreeDocument(xmlRelaxNGDocumentPtr docu) } /** - * @param docu a list of document structure - * * Deallocate a RelaxNG document structures. + * + * @param docu a list of document structure */ static void xmlRelaxNGFreeDocumentList(xmlRelaxNGDocumentPtr docu) @@ -654,9 +650,9 @@ xmlRelaxNGFreeDocumentList(xmlRelaxNGDocumentPtr docu) } /** - * @param incl a include structure - * * Deallocate a RelaxNG include structure. + * + * @param incl a include structure */ static void xmlRelaxNGFreeInclude(xmlRelaxNGIncludePtr incl) @@ -674,9 +670,9 @@ xmlRelaxNGFreeInclude(xmlRelaxNGIncludePtr incl) } /** - * @param incl a include structure list - * * Deallocate a RelaxNG include structure. + * + * @param incl a include structure list */ static void xmlRelaxNGFreeIncludeList(xmlRelaxNGIncludePtr incl) @@ -691,10 +687,9 @@ xmlRelaxNGFreeIncludeList(xmlRelaxNGIncludePtr incl) } /** - * @param ctxt a Relax-NG validation context (optional) - * * Allocate a new RelaxNG structure. * + * @param ctxt a Relax-NG validation context (optional) * @returns the newly allocated structure or NULL in case or error */ static xmlRelaxNGPtr @@ -713,9 +708,9 @@ xmlRelaxNGNewRelaxNG(xmlRelaxNGParserCtxtPtr ctxt) } /** - * @param schema a schema structure - * * Deallocate a RelaxNG schema structure. + * + * @param schema a schema structure */ static void xmlRelaxNGFreeInnerSchema(xmlRelaxNGPtr schema) @@ -737,9 +732,9 @@ xmlRelaxNGFreeInnerSchema(xmlRelaxNGPtr schema) } /** - * @param schema a schema structure - * * Deallocate a RelaxNG structure. + * + * @param schema a schema structure */ void xmlRelaxNGFree(xmlRelaxNGPtr schema) @@ -767,10 +762,9 @@ xmlRelaxNGFree(xmlRelaxNGPtr schema) } /** - * @param ctxt a Relax-NG validation context (optional) - * * Allocate a new RelaxNG grammar. * + * @param ctxt a Relax-NG validation context (optional) * @returns the newly allocated structure or NULL in case or error */ static xmlRelaxNGGrammarPtr @@ -789,9 +783,9 @@ xmlRelaxNGNewGrammar(xmlRelaxNGParserCtxtPtr ctxt) } /** - * @param grammar a grammar structure - * * Deallocate a RelaxNG grammar structure. + * + * @param grammar a grammar structure */ static void xmlRelaxNGFreeGrammar(xmlRelaxNGGrammarPtr grammar) @@ -816,11 +810,10 @@ xmlRelaxNGFreeGrammar(xmlRelaxNGGrammarPtr grammar) } /** - * @param ctxt a Relax-NG validation context - * @param node the node in the input document. - * * Allocate a new RelaxNG define. * + * @param ctxt a Relax-NG validation context + * @param node the node in the input document. * @returns the newly allocated structure or NULL in case or error */ static xmlRelaxNGDefinePtr @@ -864,9 +857,9 @@ xmlRelaxNGNewDefine(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** - * @param partitions a partition set structure - * * Deallocate RelaxNG partition set structures. + * + * @param partitions a partition set structure */ static void xmlRelaxNGFreePartition(xmlRelaxNGPartitionPtr partitions) @@ -896,9 +889,9 @@ xmlRelaxNGFreePartition(xmlRelaxNGPartitionPtr partitions) } /** - * @param define a define structure - * * Deallocate a RelaxNG define structure. + * + * @param define a define structure */ static void xmlRelaxNGFreeDefine(xmlRelaxNGDefinePtr define) @@ -929,11 +922,10 @@ xmlRelaxNGFreeDefine(xmlRelaxNGDefinePtr define) } /** - * @param ctxt a Relax-NG validation context - * @param size the default size for the container - * * Allocate a new RelaxNG validation state container * + * @param ctxt a Relax-NG validation context + * @param size the default size for the container * @returns the newly allocated structure or NULL in case or error */ static xmlRelaxNGStatesPtr @@ -973,13 +965,12 @@ xmlRelaxNGNewStates(xmlRelaxNGValidCtxtPtr ctxt, int size) } /** - * @param ctxt a Relax-NG validation context - * @param states the states container - * @param state the validation state - * * Add a RelaxNG validation state to the container without checking * for unicity. * + * @param ctxt a Relax-NG validation context + * @param states the states container + * @param state the validation state * @returns 1 in case of success and 0 if this is a duplicate and -1 on error */ static int @@ -1011,12 +1002,11 @@ xmlRelaxNGAddStatesUniq(xmlRelaxNGValidCtxtPtr ctxt, } /** + * Add a RelaxNG validation state to the container + * * @param ctxt a Relax-NG validation context * @param states the states container * @param state the validation state - * - * Add a RelaxNG validation state to the container - * * @returns 1 in case of success and 0 if this is a duplicate and -1 on error */ static int @@ -1056,10 +1046,10 @@ xmlRelaxNGAddStates(xmlRelaxNGValidCtxtPtr ctxt, } /** + * Free a RelaxNG validation state container + * * @param ctxt a Relax-NG validation context * @param states the container - * - * Free a RelaxNG validation state container */ static void xmlRelaxNGFreeStates(xmlRelaxNGValidCtxtPtr ctxt, @@ -1101,11 +1091,10 @@ xmlRelaxNGFreeStates(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * @param node the current node or NULL for the document - * * Allocate a new RelaxNG validation state * + * @param ctxt a Relax-NG validation context + * @param node the current node or NULL for the document * @returns the newly allocated structure or NULL in case or error */ static xmlRelaxNGValidStatePtr @@ -1195,11 +1184,10 @@ xmlRelaxNGNewValidState(xmlRelaxNGValidCtxtPtr ctxt, xmlNodePtr node) } /** - * @param ctxt a Relax-NG validation context - * @param state a validation state - * * Copy the validation state * + * @param ctxt a Relax-NG validation context + * @param state a validation state * @returns the newly allocated structure or NULL in case or error */ static xmlRelaxNGValidStatePtr @@ -1260,12 +1248,11 @@ xmlRelaxNGCopyValidState(xmlRelaxNGValidCtxtPtr ctxt, } /** + * Compare the validation states for equality + * * @param ctxt a Relax-NG validation context * @param state1 a validation state * @param state2 a validation state - * - * Compare the validation states for equality - * * @returns 1 if equal, 0 otherwise */ static int @@ -1300,10 +1287,10 @@ xmlRelaxNGEqualValidState(xmlRelaxNGValidCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** + * Deallocate a RelaxNG validation state structure. + * * @param ctxt validation context * @param state a validation state structure - * - * Deallocate a RelaxNG validation state structure. */ static void xmlRelaxNGFreeValidState(xmlRelaxNGValidCtxtPtr ctxt, @@ -1331,12 +1318,11 @@ xmlRelaxNGFreeValidState(xmlRelaxNGValidCtxtPtr ctxt, ************************************************************************/ /** - * @param ctxt a RelaxNG parser context - * @param flags a set of flags values - * * Semi private function used to pass information to a parser context * which are a combination of xmlRelaxNGParserFlag . * + * @param ctxt a RelaxNG parser context + * @param flags a set of flags values * @returns 0 if success and -1 in case of error */ int @@ -1406,11 +1392,10 @@ xmlRelaxReadMemory(xmlRelaxNGParserCtxtPtr ctxt, const char *buf, int size) { } /** - * @param ctxt the parser context - * @param value the element doc - * * Pushes a new include on top of the include stack * + * @param ctxt the parser context + * @param value the element doc * @returns 0 in case of error, the index in the stack otherwise */ static int @@ -1445,10 +1430,9 @@ xmlRelaxNGIncludePush(xmlRelaxNGParserCtxtPtr ctxt, } /** - * @param ctxt the parser context - * * Pops the top include from the include stack * + * @param ctxt the parser context * @returns the include just removed */ static xmlRelaxNGIncludePtr @@ -1469,13 +1453,12 @@ xmlRelaxNGIncludePop(xmlRelaxNGParserCtxtPtr ctxt) } /** + * Applies the elimination algorithm of 4.7 + * * @param ctxt the parser context * @param URL the normalized URL * @param target the included target * @param name the define name to eliminate - * - * Applies the elimination algorithm of 4.7 - * * @returns 0 in case of error, 1 in case of success. */ static int @@ -1531,15 +1514,14 @@ xmlRelaxNGRemoveRedefine(xmlRelaxNGParserCtxtPtr ctxt, } /** - * @param ctxt the parser context - * @param URL the normalized URL - * @param node the include node. - * @param ns the namespace passed from the context. - * * First lookup if the document is already loaded into the parser context, * check against recursion. If not found the resource is loaded and * the content is preprocessed before being returned back to the caller. * + * @param ctxt the parser context + * @param URL the normalized URL + * @param node the include node. + * @param ns the namespace passed from the context. * @returns the xmlRelaxNGIncludePtr or NULL in case of error */ static xmlRelaxNGIncludePtr @@ -1694,14 +1676,13 @@ xmlRelaxNGLoadInclude(xmlRelaxNGParserCtxtPtr ctxt, const xmlChar * URL, } /** + * Pushes a new error on top of the error stack + * * @param ctxt the validation context * @param err the error code * @param arg1 the first string argument * @param arg2 the second string argument * @param dup arg need to be duplicated - * - * Pushes a new error on top of the error stack - * * @returns 0 in case of error, the index in the stack otherwise */ static int @@ -1763,9 +1744,9 @@ xmlRelaxNGValidErrorPush(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt the validation context - * * Pops the top error from the error stack + * + * @param ctxt the validation context */ static void xmlRelaxNGValidErrorPop(xmlRelaxNGValidCtxtPtr ctxt) @@ -1794,11 +1775,10 @@ xmlRelaxNGValidErrorPop(xmlRelaxNGValidCtxtPtr ctxt) } /** - * @param ctxt the parser context - * @param value the element doc - * * Pushes a new doc on top of the doc stack * + * @param ctxt the parser context + * @param value the element doc * @returns 0 in case of error, the index in the stack otherwise */ static int @@ -1833,10 +1813,9 @@ xmlRelaxNGDocumentPush(xmlRelaxNGParserCtxtPtr ctxt, } /** - * @param ctxt the parser context - * * Pops the top doc from the doc stack * + * @param ctxt the parser context * @returns the doc just removed */ static xmlRelaxNGDocumentPtr @@ -1857,14 +1836,13 @@ xmlRelaxNGDocumentPop(xmlRelaxNGParserCtxtPtr ctxt) } /** - * @param ctxt the parser context - * @param URL the normalized URL - * @param ns the inherited ns if any - * * First lookup if the document is already loaded into the parser context, * check against recursion. If not found the resource is loaded and * the content is preprocessed before being returned back to the caller. * + * @param ctxt the parser context + * @param URL the normalized URL + * @param ns the inherited ns if any * @returns the xmlRelaxNGDocumentPtr or NULL in case of error */ static xmlRelaxNGDocumentPtr @@ -2012,12 +1990,11 @@ xmlRelaxNGDefName(xmlRelaxNGDefinePtr def) } /** + * computes a formatted error string for the given error code and args + * * @param err the error code * @param arg1 the first string argument * @param arg2 the second string argument - * - * computes a formatted error string for the given error code and args - * * @returns the error string, it must be deallocated by the caller */ static xmlChar * @@ -2158,14 +2135,14 @@ xmlRelaxNGGetErrorString(xmlRelaxNGValidErr err, const xmlChar * arg1, } /** + * Show a validation error. + * * @param ctxt the validation context * @param err the error number * @param node the node * @param child the node child generating the problem. * @param arg1 the first argument * @param arg2 the second argument - * - * Show a validation error. */ static void xmlRelaxNGShowValidError(xmlRelaxNGValidCtxtPtr ctxt, @@ -2190,10 +2167,10 @@ xmlRelaxNGShowValidError(xmlRelaxNGValidCtxtPtr ctxt, } /** + * pop and discard all errors until the given level is reached + * * @param ctxt the validation context * @param level the error level in the stack - * - * pop and discard all errors until the given level is reached */ static void xmlRelaxNGPopErrors(xmlRelaxNGValidCtxtPtr ctxt, int level) @@ -2219,9 +2196,9 @@ xmlRelaxNGPopErrors(xmlRelaxNGValidCtxtPtr ctxt, int level) } /** - * @param ctxt the validation context - * * Show all validation error over a given index. + * + * @param ctxt the validation context */ static void xmlRelaxNGDumpValidError(xmlRelaxNGValidCtxtPtr ctxt) @@ -2259,14 +2236,14 @@ xmlRelaxNGDumpValidError(xmlRelaxNGValidCtxtPtr ctxt) } /** + * Register a validation error, either generating it if it's sure + * or stacking it for later handling if unsure. + * * @param ctxt the validation context * @param err the error number * @param arg1 the first argument * @param arg2 the second argument * @param dup need to dup the args - * - * Register a validation error, either generating it if it's sure - * or stacking it for later handling if unsure. */ static void xmlRelaxNGAddValidError(xmlRelaxNGValidCtxtPtr ctxt, @@ -2320,12 +2297,11 @@ static xmlChar *xmlRelaxNGNormalize(xmlRelaxNGValidCtxtPtr ctxt, const xmlChar * str); /** - * @param data data needed for the library - * @param type the type name - * * Check if the given type is provided by * the W3C XMLSchema Datatype library. * + * @param data data needed for the library + * @param type the type name * @returns 1 if yes, 0 if no and -1 in case of error. */ static int @@ -2344,15 +2320,14 @@ xmlRelaxNGSchemaTypeHave(void *data ATTRIBUTE_UNUSED, const xmlChar * type) } /** + * Check if the given type and value are validated by + * the W3C XMLSchema Datatype library. + * * @param data data needed for the library * @param type the type name * @param value the value to check * @param result pointer to result * @param node the node - * - * Check if the given type and value are validated by - * the W3C XMLSchema Datatype library. - * * @returns 1 if yes, 0 if no and -1 in case of error. */ static int @@ -2383,15 +2358,14 @@ xmlRelaxNGSchemaTypeCheck(void *data ATTRIBUTE_UNUSED, } /** + * Function provided by a type library to check a value facet + * * @param data data needed for the library * @param type the type name * @param facetname the facet name * @param val the facet value * @param strval the string value * @param value the value to check - * - * Function provided by a type library to check a value facet - * * @returns 1 if yes, 0 if no and -1 in case of error. */ static int @@ -2458,11 +2432,10 @@ xmlRelaxNGSchemaFacetCheck(void *data ATTRIBUTE_UNUSED, } /** - * @param data data needed for the library - * @param value the value to free - * * Function provided by a type library to free a Schemas value * + * @param data data needed for the library + * @param value the value to free * @returns 1 if yes, 0 if no and -1 in case of error. */ static void @@ -2472,6 +2445,9 @@ xmlRelaxNGSchemaFreeValue(void *data ATTRIBUTE_UNUSED, void *value) } /** + * Compare two values for equality accordingly a type from the W3C XMLSchema + * Datatype library. + * * @param data data needed for the library * @param type the type name * @param value1 the first value @@ -2479,10 +2455,6 @@ xmlRelaxNGSchemaFreeValue(void *data ATTRIBUTE_UNUSED, void *value) * @param comp1 value to compare with * @param value2 the second value * @param ctxt2 the second context node - * - * Compare two values for equality accordingly a type from the W3C XMLSchema - * Datatype library. - * * @returns 1 if equal, 0 if no and -1 in case of error. */ static int @@ -2531,12 +2503,11 @@ xmlRelaxNGSchemaTypeCompare(void *data ATTRIBUTE_UNUSED, } /** - * @param data data needed for the library - * @param type the type name - * * Check if the given type is provided by * the default datatype library. * + * @param data data needed for the library + * @param type the type name * @returns 1 if yes, 0 if no and -1 in case of error. */ static int @@ -2553,15 +2524,14 @@ xmlRelaxNGDefaultTypeHave(void *data ATTRIBUTE_UNUSED, } /** + * Check if the given type and value are validated by + * the default datatype library. + * * @param data data needed for the library * @param type the type name * @param value the value to check * @param result pointer to result * @param node the node - * - * Check if the given type and value are validated by - * the default datatype library. - * * @returns 1 if yes, 0 if no and -1 in case of error. */ static int @@ -2583,6 +2553,9 @@ xmlRelaxNGDefaultTypeCheck(void *data ATTRIBUTE_UNUSED, } /** + * Compare two values accordingly a type from the default + * datatype library. + * * @param data data needed for the library * @param type the type name * @param value1 the first value @@ -2590,10 +2563,6 @@ xmlRelaxNGDefaultTypeCheck(void *data ATTRIBUTE_UNUSED, * @param comp1 value to compare with * @param value2 the second value * @param ctxt2 the second context node - * - * Compare two values accordingly a type from the default - * datatype library. - * * @returns 1 if yes, 0 if no and -1 in case of error. */ static int @@ -2640,10 +2609,10 @@ static int xmlRelaxNGTypeInitialized = 0; static xmlHashTablePtr xmlRelaxNGRegisteredTypes = NULL; /** + * Free the structure associated to the type library + * * @param payload the type library structure * @param namespace the URI bound to the library - * - * Free the structure associated to the type library */ static void xmlRelaxNGFreeTypeLibrary(void *payload, @@ -2658,6 +2627,8 @@ xmlRelaxNGFreeTypeLibrary(void *payload, } /** + * Register a new type library + * * @param namespace the URI bound to the library * @param data data associated to the library * @param have the provide function @@ -2665,9 +2636,6 @@ xmlRelaxNGFreeTypeLibrary(void *payload, * @param comp the comparison function * @param facet facet check function * @param freef free function - * - * Register a new type library - * * @returns 0 in case of success and -1 in case of error. */ static int @@ -2739,12 +2707,13 @@ xmlRelaxNGInitTypes(void) } /** + * Cleanup the default Schemas type library associated to RelaxNG + * * @deprecated This function will be made private. Call xmlCleanupParser() * to free global state but see the warnings there. xmlCleanupParser() * should be only called once at program exit. In most cases, you don't * have call cleanup functions at all. * - * Cleanup the default Schemas type library associated to RelaxNG */ void xmlRelaxNGCleanupTypes(void) @@ -2769,10 +2738,9 @@ static int xmlRelaxNGTryCompile(xmlRelaxNGParserCtxtPtr ctxt, xmlRelaxNGDefinePtr def); /** - * @param def the definition to check - * * Check if a definition is nullable. * + * @param def the definition to check * @returns 1 if yes, 0 if no and -1 in case of error */ static int @@ -2887,12 +2855,11 @@ xmlRelaxNGIsCompilable(xmlRelaxNGDefinePtr def) } /** - * @param ctxt the RelaxNG parser context - * @param def the definition tree to compile - * * Compile the set of definitions, it works recursively, till the * element boundaries, where it tries to compile the content if possible * + * @param ctxt the RelaxNG parser context + * @param def the definition tree to compile * @returns 0 if success and -1 in case of error */ static int @@ -3107,12 +3074,11 @@ xmlRelaxNGCompile(xmlRelaxNGParserCtxtPtr ctxt, xmlRelaxNGDefinePtr def) } /** - * @param ctxt the RelaxNG parser context - * @param def the definition tree to compile - * * Try to compile the set of definitions, it works recursively, * possibly ignoring parts which cannot be compiled. * + * @param ctxt the RelaxNG parser context + * @param def the definition tree to compile * @returns 0 if success and -1 in case of error */ static int @@ -3207,10 +3173,9 @@ static int xmlRelaxNGElementMatch(xmlRelaxNGValidCtxtPtr ctxt, #define IS_BLANK_NODE(n) (xmlRelaxNGIsBlank((n)->content)) /** - * @param define the definition to verify - * * Check if a definition is nullable. * + * @param define the definition to verify * @returns 1 if yes, 0 if no and -1 in case of error */ static int @@ -3285,10 +3250,9 @@ xmlRelaxNGIsNullable(xmlRelaxNGDefinePtr define) } /** - * @param str a string - * * Check if a string is ignorable c.f. 4.2. Whitespace * + * @param str a string * @returns 1 if the string is NULL or made of blanks chars, 0 otherwise */ static int @@ -3305,11 +3269,10 @@ xmlRelaxNGIsBlank(xmlChar * str) } /** - * @param ctxt a Relax-NG parser context - * @param node the current data or value element - * * Applies algorithm from 4.3. datatypeLibrary attribute * + * @param ctxt a Relax-NG parser context + * @param node the current data or value element * @returns the datatypeLibrary value or NULL if not found */ static xmlChar * @@ -3357,11 +3320,10 @@ xmlRelaxNGGetDataTypeLibrary(xmlRelaxNGParserCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** - * @param ctxt a Relax-NG parser context - * @param node the data node. - * * parse the content of a RelaxNG value node. * + * @param ctxt a Relax-NG parser context + * @param node the data node. * @returns the definition pointer or NULL in case of error */ static xmlRelaxNGDefinePtr @@ -3448,11 +3410,10 @@ xmlRelaxNGParseValue(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** - * @param ctxt a Relax-NG parser context - * @param node the data node. - * * parse the content of a RelaxNG data node. * + * @param ctxt a Relax-NG parser context + * @param node the data node. * @returns the definition pointer or NULL in case of error */ static xmlRelaxNGDefinePtr @@ -3609,13 +3570,12 @@ xmlRelaxNGParseData(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) static const xmlChar *invalidName = BAD_CAST "\1"; /** - * @param def1 the first element/attribute defs - * @param def2 the second element/attribute defs - * * Compare the 2 lists of element definitions. The comparison is * that if both lists do not accept the same QNames, it returns 1 * If the 2 lists can accept the same QName the comparison returns 0 * + * @param def1 the first element/attribute defs + * @param def2 the second element/attribute defs * @returns 1 distinct, 0 if equal */ static int @@ -3710,14 +3670,13 @@ xmlRelaxNGCompareNameClasses(xmlRelaxNGDefinePtr def1, } /** - * @param ctxt a Relax-NG parser context - * @param def1 the first list of element/attribute defs - * @param def2 the second list of element/attribute defs - * * Compare the 2 lists of element or attribute definitions. The comparison * is that if both lists do not accept the same QNames, it returns 1 * If the 2 lists can accept the same QName the comparison returns 0 * + * @param ctxt a Relax-NG parser context + * @param def1 the first list of element/attribute defs + * @param def2 the second list of element/attribute defs * @returns 1 distinct, 0 if equal */ static int @@ -3744,11 +3703,10 @@ xmlRelaxNGCompareElemDefLists(xmlRelaxNGParserCtxtPtr ctxt } /** - * @param ctxt a Relax-NG parser context - * @param def the definition definition - * * Check if the definition can only generate attributes * + * @param ctxt a Relax-NG parser context + * @param def the definition definition * @returns 1 if yes, 0 if no and -1 in case of error. */ static int @@ -3818,12 +3776,11 @@ xmlRelaxNGGenerateAttributes(xmlRelaxNGParserCtxtPtr ctxt, } /** + * Compute the list of top elements a definition can generate + * * @param ctxt a Relax-NG parser context * @param def the definition definition * @param eora gather elements (0), attributes (1) or elements and text (2) - * - * Compute the list of top elements a definition can generate - * * @returns a list of elements or NULL if none was found. */ static xmlRelaxNGDefinePtr * @@ -3922,10 +3879,10 @@ xmlRelaxNGGetElements(xmlRelaxNGParserCtxtPtr ctxt, } /** + * Also used to find indeterministic pattern in choice + * * @param ctxt a Relax-NG parser context * @param def the choice definition - * - * Also used to find indeterministic pattern in choice */ static void xmlRelaxNGCheckChoiceDeterminism(xmlRelaxNGParserCtxtPtr ctxt, @@ -4057,10 +4014,10 @@ xmlRelaxNGCheckChoiceDeterminism(xmlRelaxNGParserCtxtPtr ctxt, } /** + * Detects violations of rule 7.3 + * * @param ctxt a Relax-NG parser context * @param def the group definition - * - * Detects violations of rule 7.3 */ static void xmlRelaxNGCheckGroupAttrs(xmlRelaxNGParserCtxtPtr ctxt, @@ -4140,10 +4097,6 @@ xmlRelaxNGCheckGroupAttrs(xmlRelaxNGParserCtxtPtr ctxt, } /** - * @param payload the interleave definition - * @param data a Relax-NG parser context - * @param name the definition name - * * A lot of work for preprocessing interleave definitions * is potentially needed to get a decent execution speed at runtime * - trying to get a total order on the element nodes generated @@ -4152,6 +4105,10 @@ xmlRelaxNGCheckGroupAttrs(xmlRelaxNGParserCtxtPtr ctxt, * - if `` is used to handle mixed content, it is better to * flag this in the define and simplify the runtime checking * algorithm + * + * @param payload the interleave definition + * @param data a Relax-NG parser context + * @param name the definition name */ static void xmlRelaxNGComputeInterleaves(void *payload, void *data, @@ -4305,11 +4262,10 @@ xmlRelaxNGComputeInterleaves(void *payload, void *data, } /** - * @param ctxt a Relax-NG parser context - * @param node the data node. - * * parse the content of a RelaxNG interleave node. * + * @param ctxt a Relax-NG parser context + * @param node the data node. * @returns the definition pointer or NULL in case of error */ static xmlRelaxNGDefinePtr @@ -4366,11 +4322,10 @@ xmlRelaxNGParseInterleave(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** - * @param ctxt a Relax-NG parser context - * @param node the include node - * * Integrate the content of an include node in the current grammar * + * @param ctxt a Relax-NG parser context + * @param node the include node * @returns 0 in case of success or -1 in case of error */ static int @@ -4415,11 +4370,10 @@ xmlRelaxNGParseInclude(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** - * @param ctxt a Relax-NG parser context - * @param node the define node - * * parse the content of a RelaxNG define element node. * + * @param ctxt a Relax-NG parser context + * @param node the define node * @returns 0 in case of success or -1 in case of error */ static int @@ -4486,11 +4440,11 @@ xmlRelaxNGParseDefine(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** + * Import import one references into the current grammar + * * @param payload the parser context * @param data the current grammar * @param name the reference name - * - * Import import one references into the current grammar */ static void xmlRelaxNGParseImportRef(void *payload, void *data, const xmlChar *name) { @@ -4524,11 +4478,10 @@ xmlRelaxNGParseImportRef(void *payload, void *data, const xmlChar *name) { } /** - * @param ctxt the parser context - * @param grammar the sub grammar - * * Import references from the subgrammar into the current grammar * + * @param ctxt the parser context + * @param grammar the sub grammar * @returns 0 in case of success, -1 in case of failure */ static int @@ -4550,11 +4503,10 @@ xmlRelaxNGParseImportRefs(xmlRelaxNGParserCtxtPtr ctxt, } /** - * @param ctxt the parser context - * @param node the externalRef node - * * Process and compile an externalRef node * + * @param ctxt the parser context + * @param node the externalRef node * @returns the xmlRelaxNGDefinePtr or NULL in case of error */ static xmlRelaxNGDefinePtr @@ -4635,11 +4587,10 @@ xmlRelaxNGProcessExternalRef(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** - * @param ctxt a Relax-NG parser context - * @param node the pattern node. - * * parse the content of a RelaxNG pattern node. * + * @param ctxt a Relax-NG parser context + * @param node the pattern node. * @returns the definition pointer or NULL in case of error or if no * pattern is generated. */ @@ -4929,11 +4880,10 @@ xmlRelaxNGParsePattern(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** - * @param ctxt a Relax-NG parser context - * @param node the element node - * * parse the content of a RelaxNG attribute node. * + * @param ctxt a Relax-NG parser context + * @param node the element node * @returns the definition pointer or NULL in case of error. */ static xmlRelaxNGDefinePtr @@ -5011,12 +4961,11 @@ xmlRelaxNGParseAttribute(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** + * parse the content of a RelaxNG nameClass node. + * * @param ctxt a Relax-NG parser context * @param node the except node * @param attr 1 if within an attribute, 0 if within an element - * - * parse the content of a RelaxNG nameClass node. - * * @returns the definition pointer or NULL in case of error. */ static xmlRelaxNGDefinePtr @@ -5071,12 +5020,11 @@ xmlRelaxNGParseExceptNameClass(xmlRelaxNGParserCtxtPtr ctxt, } /** + * parse the content of a RelaxNG nameClass node. + * * @param ctxt a Relax-NG parser context * @param node the nameClass node * @param def the current definition - * - * parse the content of a RelaxNG nameClass node. - * * @returns the definition pointer or NULL in case of error. */ static xmlRelaxNGDefinePtr @@ -5216,11 +5164,10 @@ xmlRelaxNGParseNameClass(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node, } /** - * @param ctxt a Relax-NG parser context - * @param node the element node - * * parse the content of a RelaxNG element node. * + * @param ctxt a Relax-NG parser context + * @param node the element node * @returns the definition pointer or NULL in case of error. */ static xmlRelaxNGDefinePtr @@ -5327,12 +5274,11 @@ xmlRelaxNGParseElement(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** + * parse the content of a RelaxNG start node. + * * @param ctxt a Relax-NG parser context * @param nodes list of nodes * @param group use an implicit `` for elements - * - * parse the content of a RelaxNG start node. - * * @returns the definition pointer or NULL in case of error. */ static xmlRelaxNGDefinePtr @@ -5379,11 +5325,10 @@ xmlRelaxNGParsePatterns(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr nodes, } /** - * @param ctxt a Relax-NG parser context - * @param nodes start children nodes - * * parse the content of a RelaxNG start node. * + * @param ctxt a Relax-NG parser context + * @param nodes start children nodes * @returns 0 in case of success, -1 in case of error */ static int @@ -5436,11 +5381,10 @@ xmlRelaxNGParseStart(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr nodes) } /** - * @param ctxt a Relax-NG parser context - * @param nodes grammar children nodes - * * parse the content of a RelaxNG grammar node. * + * @param ctxt a Relax-NG parser context + * @param nodes grammar children nodes * @returns 0 in case of success, -1 in case of error */ static int @@ -5484,12 +5428,12 @@ xmlRelaxNGParseGrammarContent(xmlRelaxNGParserCtxtPtr ctxt, } /** + * Applies the 4.17. combine attribute rule for all the define + * element of a given grammar using the same name. + * * @param payload the ref * @param data a Relax-NG parser context * @param name the name associated to the defines - * - * Applies the 4.17. combine attribute rule for all the define - * element of a given grammar using the same name. */ static void xmlRelaxNGCheckReference(void *payload, void *data, const xmlChar * name) @@ -5539,12 +5483,12 @@ xmlRelaxNGCheckReference(void *payload, void *data, const xmlChar * name) } /** + * Applies the 4.17. combine attribute rule for all the define + * element of a given grammar using the same name. + * * @param payload the define(s) list * @param data a Relax-NG parser context * @param name the name associated to the defines - * - * Applies the 4.17. combine attribute rule for all the define - * element of a given grammar using the same name. */ static void xmlRelaxNGCheckCombine(void *payload, void *data, const xmlChar * name) @@ -5654,11 +5598,11 @@ xmlRelaxNGCheckCombine(void *payload, void *data, const xmlChar * name) } /** - * @param ctxt a Relax-NG parser context - * @param grammar the grammar - * * Applies the 4.17. combine rule for all the start * element of a given grammar. + * + * @param ctxt a Relax-NG parser context + * @param grammar the grammar */ static void xmlRelaxNGCombineStart(xmlRelaxNGParserCtxtPtr ctxt, @@ -5753,12 +5697,11 @@ xmlRelaxNGCombineStart(xmlRelaxNGParserCtxtPtr ctxt, } /** + * Check for cycles. + * * @param ctxt a Relax-NG parser context * @param cur grammar children nodes * @param depth the counter - * - * Check for cycles. - * * @returns 0 if check passed, and -1 in case of error */ static int @@ -5791,13 +5734,12 @@ xmlRelaxNGCheckCycles(xmlRelaxNGParserCtxtPtr ctxt, } /** + * Try to unlink a definition. If not possible make it a NOOP + * * @param ctxt a Relax-NG parser context * @param cur the definition to unlink * @param parent the parent definition * @param prev the previous sibling definition - * - * Try to unlink a definition. If not possible make it a NOOP - * * @returns the new prev definition */ static xmlRelaxNGDefinePtr @@ -5824,11 +5766,11 @@ xmlRelaxNGTryUnlink(xmlRelaxNGParserCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** + * Check for simplification of empty and notAllowed + * * @param ctxt a Relax-NG parser context * @param cur grammar children nodes * @param parent parent - * - * Check for simplification of empty and notAllowed */ static void xmlRelaxNGSimplify(xmlRelaxNGParserCtxtPtr ctxt, @@ -5990,11 +5932,10 @@ xmlRelaxNGSimplify(xmlRelaxNGParserCtxtPtr ctxt, } /** - * @param ct1 the first content type - * @param ct2 the second content type - * * Try to group 2 content types * + * @param ct1 the first content type + * @param ct2 the second content type * @returns the content type */ static xmlRelaxNGContentType @@ -6015,11 +5956,10 @@ xmlRelaxNGGroupContentType(xmlRelaxNGContentType ct1, } /** - * @param ct1 the first content type - * @param ct2 the second content type - * * Compute the max content-type * + * @param ct1 the first content type + * @param ct2 the second content type * @returns the content type */ static xmlRelaxNGContentType @@ -6039,13 +5979,12 @@ xmlRelaxNGMaxContentType(xmlRelaxNGContentType ct1, } /** + * Check for rules in section 7.1 and 7.2 + * * @param ctxt a Relax-NG parser context * @param cur the current definition * @param flags some accumulated flags * @param ptype the parent type - * - * Check for rules in section 7.1 and 7.2 - * * @returns the content type of `cur` */ static xmlRelaxNGContentType @@ -6366,11 +6305,10 @@ xmlRelaxNGCheckRules(xmlRelaxNGParserCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG parser context - * @param nodes grammar children nodes - * * parse a Relax-NG `` node * + * @param ctxt a Relax-NG parser context + * @param nodes grammar children nodes * @returns the internal xmlRelaxNGGrammarPtr built or * NULL in case of error */ @@ -6433,12 +6371,11 @@ xmlRelaxNGParseGrammar(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr nodes) } /** - * @param ctxt a Relax-NG parser context - * @param node the root node of the RelaxNG schema - * * parse a Relax-NG definition resource and build an internal * xmlRelaxNG structure which can be used to validate instances. * + * @param ctxt a Relax-NG parser context + * @param node the root node of the RelaxNG schema * @returns the internal XML RelaxNG structure built or * NULL in case of error */ @@ -6517,11 +6454,10 @@ xmlRelaxNGParseDocument(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) ************************************************************************/ /** - * @param URL the location of the schema - * * Create an XML RelaxNGs parse context for that file/resource expected * to contain an XML RelaxNGs file. * + * @param URL the location of the schema * @returns the parser context or NULL in case of error */ xmlRelaxNGParserCtxtPtr @@ -6544,12 +6480,11 @@ xmlRelaxNGNewParserCtxt(const char *URL) } /** - * @param buffer a pointer to a char array containing the schemas - * @param size the size of the array - * * Create an XML RelaxNGs parse context for that memory buffer expected * to contain an XML RelaxNGs file. * + * @param buffer a pointer to a char array containing the schemas + * @param size the size of the array * @returns the parser context or NULL in case of error */ xmlRelaxNGParserCtxtPtr @@ -6573,12 +6508,11 @@ xmlRelaxNGNewMemParserCtxt(const char *buffer, int size) } /** - * @param doc a preparsed document tree - * * Create an XML RelaxNGs parser context for that document. * Note: since the process of compiling a RelaxNG schemas modifies the * document, the `doc` parameter is duplicated internally. * + * @param doc a preparsed document tree * @returns the parser context or NULL in case of error */ xmlRelaxNGParserCtxtPtr @@ -6608,9 +6542,9 @@ xmlRelaxNGNewDocParserCtxt(xmlDocPtr doc) } /** - * @param ctxt the schema parser context - * * Free the resources associated to the schema parser context + * + * @param ctxt the schema parser context */ void xmlRelaxNGFreeParserCtxt(xmlRelaxNGParserCtxtPtr ctxt) @@ -6644,10 +6578,10 @@ xmlRelaxNGFreeParserCtxt(xmlRelaxNGParserCtxtPtr ctxt) } /** - * @param value a value - * * Removes the leading and ending spaces of the value * The string is modified "in situ" + * + * @param value a value */ static void xmlRelaxNGNormExtSpace(xmlChar * value) @@ -6695,10 +6629,10 @@ xmlRelaxNGNormExtSpace(xmlChar * value) } /** + * Check all the attributes on the given node + * * @param ctxt a Relax-NG parser context * @param node a Relax-NG node - * - * Check all the attributes on the given node */ static void xmlRelaxNGCleanupAttributes(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) @@ -6781,11 +6715,11 @@ xmlRelaxNGCleanupAttributes(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr node) } /** - * @param ctxt a Relax-NG parser context - * @param root an xmlNodePtr subtree - * * Cleanup the subtree from unwanted nodes for parsing, resolve * Include and externalRef lookups. + * + * @param ctxt a Relax-NG parser context + * @param root an xmlNodePtr subtree */ static void xmlRelaxNGCleanupTree(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr root) @@ -7221,12 +7155,11 @@ xmlRelaxNGCleanupTree(xmlRelaxNGParserCtxtPtr ctxt, xmlNodePtr root) } /** - * @param ctxt a Relax-NG parser context - * @param doc an xmldocPtr document pointer - * * Cleanup the document from unwanted nodes for parsing, resolve * Include and externalRef lookups. * + * @param ctxt a Relax-NG parser context + * @param doc an xmldocPtr document pointer * @returns the cleaned up document or NULL in case of error */ static xmlDocPtr @@ -7248,11 +7181,10 @@ xmlRelaxNGCleanupDoc(xmlRelaxNGParserCtxtPtr ctxt, xmlDocPtr doc) } /** - * @param ctxt a Relax-NG parser context - * * parse a schema definition resource and build an internal * XML Schema structure which can be used to validate instances. * + * @param ctxt a Relax-NG parser context * @returns the internal XML RelaxNG structure built from the resource or * NULL in case of error */ @@ -7385,14 +7317,14 @@ xmlRelaxNGParse(xmlRelaxNGParserCtxtPtr ctxt) } /** + * Set the callback functions used to handle errors for a validation context + * + * @deprecated Use xmlRelaxNGSetParserStructuredErrors(). + * * @param ctxt a Relax-NG validation context * @param err the error callback * @param warn the warning callback * @param ctx contextual data for the callbacks - * - * @deprecated Use xmlRelaxNGSetParserStructuredErrors(). - * - * Set the callback functions used to handle errors for a validation context */ void xmlRelaxNGSetParserErrors(xmlRelaxNGParserCtxtPtr ctxt, @@ -7408,13 +7340,12 @@ xmlRelaxNGSetParserErrors(xmlRelaxNGParserCtxtPtr ctxt, } /** + * Get the callback information used to handle errors for a validation context + * * @param ctxt a Relax-NG validation context * @param err the error callback result * @param warn the warning callback result * @param ctx contextual data for the callbacks result - * - * Get the callback information used to handle errors for a validation context - * * @returns -1 in case of failure, 0 otherwise. */ int @@ -7434,11 +7365,11 @@ xmlRelaxNGGetParserErrors(xmlRelaxNGParserCtxtPtr ctxt, } /** + * Set the callback functions used to handle errors for a parsing context + * * @param ctxt a Relax-NG parser context * @param serror the error callback * @param ctx contextual data for the callbacks - * - * Set the callback functions used to handle errors for a parsing context */ void xmlRelaxNGSetParserStructuredErrors(xmlRelaxNGParserCtxtPtr ctxt, @@ -7454,11 +7385,11 @@ xmlRelaxNGSetParserStructuredErrors(xmlRelaxNGParserCtxtPtr ctxt, } /** + * Set the callback function used to load external resources. + * * @param ctxt a Relax-NG parser context * @param loader the callback * @param vctxt contextual data for the callbacks - * - * Set the callback function used to load external resources. */ void xmlRelaxNGSetResourceLoader(xmlRelaxNGParserCtxtPtr ctxt, @@ -7480,10 +7411,10 @@ static void xmlRelaxNGDumpDefine(FILE * output, xmlRelaxNGDefinePtr define); /** + * Dump a RelaxNG structure back + * * @param output the file output * @param defines a list of define structures - * - * Dump a RelaxNG structure back */ static void xmlRelaxNGDumpDefines(FILE * output, xmlRelaxNGDefinePtr defines) @@ -7495,10 +7426,10 @@ xmlRelaxNGDumpDefines(FILE * output, xmlRelaxNGDefinePtr defines) } /** + * Dump a RelaxNG structure back + * * @param output the file output * @param define a define structure - * - * Dump a RelaxNG structure back */ static void xmlRelaxNGDumpDefine(FILE * output, xmlRelaxNGDefinePtr define) @@ -7612,11 +7543,11 @@ xmlRelaxNGDumpDefine(FILE * output, xmlRelaxNGDefinePtr define) } /** + * Dump a RelaxNG structure back + * * @param output the file output * @param grammar a grammar structure * @param top is this a top grammar - * - * Dump a RelaxNG structure back */ static void xmlRelaxNGDumpGrammar(FILE * output, xmlRelaxNGGrammarPtr grammar, int top) @@ -7652,10 +7583,10 @@ xmlRelaxNGDumpGrammar(FILE * output, xmlRelaxNGGrammarPtr grammar, int top) } /** + * Dump a RelaxNG structure back + * * @param output the file output * @param schema a schema structure - * - * Dump a RelaxNG structure back */ void xmlRelaxNGDump(FILE * output, xmlRelaxNGPtr schema) @@ -7682,10 +7613,10 @@ xmlRelaxNGDump(FILE * output, xmlRelaxNGPtr schema) } /** + * Dump the transformed RelaxNG tree. + * * @param output the file output * @param schema a schema structure - * - * Dump the transformed RelaxNG tree. */ void xmlRelaxNGDumpTree(FILE * output, xmlRelaxNGPtr schema) @@ -7713,12 +7644,12 @@ static int xmlRelaxNGValidateDefinition(xmlRelaxNGValidCtxtPtr ctxt, xmlRelaxNGDefinePtr define); /** + * Handle the callback and if needed validate the element children. + * * @param exec the regular expression instance * @param token the token which matched * @param transdata callback data, the define for the subelement if available * @param inputdata callback data, the Relax NG validation context - * - * Handle the callback and if needed validate the element children. */ static void xmlRelaxNGValidateCompiledCallback(xmlRegExecCtxtPtr exec ATTRIBUTE_UNUSED, @@ -7756,12 +7687,11 @@ xmlRelaxNGValidateCompiledCallback(xmlRegExecCtxtPtr exec ATTRIBUTE_UNUSED, } /** + * Validate the content model of an element or start using the regexp + * * @param ctxt the RelaxNG validation context * @param regexp the regular expression as compiled * @param content list of children to test against the regexp - * - * Validate the content model of an element or start using the regexp - * * @returns 0 in case of success, -1 in case of error. */ static int @@ -7853,11 +7783,10 @@ static int xmlRelaxNGValidateElementEnd(xmlRelaxNGValidCtxtPtr ctxt, static void xmlRelaxNGLogBestError(xmlRelaxNGValidCtxtPtr ctxt); /** - * @param ctxt the validation context - * @param exec the regexp runtime for the new content model - * * Push a new regexp for the current node content model on the stack * + * @param ctxt the validation context + * @param exec the regexp runtime for the new content model * @returns 0 in case of success and -1 in case of error. */ static int @@ -7890,10 +7819,9 @@ xmlRelaxNGElemPush(xmlRelaxNGValidCtxtPtr ctxt, xmlRegExecCtxtPtr exec) } /** - * @param ctxt the validation context - * * Pop the regexp of the current node content model from the stack * + * @param ctxt the validation context * @returns the exec or NULL if empty */ static xmlRegExecCtxtPtr @@ -7914,13 +7842,13 @@ xmlRelaxNGElemPop(xmlRelaxNGValidCtxtPtr ctxt) } /** + * Handle the callback and if needed validate the element children. + * some of the in/out information are passed via the context in `inputdata`. + * * @param exec the regular expression instance * @param token the token which matched * @param transdata callback data, the define for the subelement if available * @param inputdata callback data, the Relax NG validation context - * - * Handle the callback and if needed validate the element children. - * some of the in/out information are passed via the context in `inputdata`. */ static void xmlRelaxNGValidateProgressiveCallback(xmlRegExecCtxtPtr exec @@ -8046,12 +7974,11 @@ xmlRelaxNGValidateProgressiveCallback(xmlRegExecCtxtPtr exec } /** + * Push a new element start on the RelaxNG validation stack. + * * @param ctxt the validation context * @param doc a document instance * @param elem an element instance - * - * Push a new element start on the RelaxNG validation stack. - * * @returns 1 if no validation problem was found or 0 if validating the * element requires a full node, and -1 in case of error. */ @@ -8117,12 +8044,11 @@ xmlRelaxNGValidatePushElement(xmlRelaxNGValidCtxtPtr ctxt, } /** + * check the CData parsed for validation in the current stack + * * @param ctxt the RelaxNG validation context * @param data some character data read * @param len the length of the data - * - * check the CData parsed for validation in the current stack - * * @returns 1 if no validation problem was found or -1 otherwise */ int @@ -8152,12 +8078,11 @@ xmlRelaxNGValidatePushCData(xmlRelaxNGValidCtxtPtr ctxt, } /** + * Pop the element end from the RelaxNG validation stack. + * * @param ctxt the RelaxNG validation context * @param doc a document instance * @param elem an element instance - * - * Pop the element end from the RelaxNG validation stack. - * * @returns 1 if no validation problem was found or 0 otherwise */ int @@ -8191,13 +8116,12 @@ xmlRelaxNGValidatePopElement(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt the validation context - * @param doc a document instance - * @param elem an element instance - * * Validate a full subtree when xmlRelaxNGValidatePushElement() returned * 0 and the content of the node has been expanded. * + * @param ctxt the validation context + * @param doc a document instance + * @param elem an element instance * @returns 1 if no validation problem was found or -1 in case of error. */ int @@ -8236,11 +8160,10 @@ static int xmlRelaxNGValidateValue(xmlRelaxNGValidCtxtPtr ctxt, xmlRelaxNGDefinePtr define); /** - * @param ctxt a schema validation context - * @param node the top node. - * * Skip ignorable nodes in that context * + * @param ctxt a schema validation context + * @param node the top node. * @returns the new sibling or NULL in case of error. */ static xmlNodePtr @@ -8265,12 +8188,11 @@ xmlRelaxNGSkipIgnored(xmlRelaxNGValidCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** - * @param ctxt a schema validation context - * @param str the string to normalize - * * Implements the normalizeWhiteSpace( s ) function from * section 6.2.9 of the spec * + * @param ctxt a schema validation context + * @param str the string to normalize * @returns the new string or NULL in case of error. */ static xmlChar * @@ -8310,13 +8232,12 @@ xmlRelaxNGNormalize(xmlRelaxNGValidCtxtPtr ctxt, const xmlChar * str) } /** + * Validate the given value against the datatype + * * @param ctxt a Relax-NG validation context * @param value the string value * @param define the datatype definition * @param node the node - * - * Validate the given value against the datatype - * * @returns 0 if the validation succeeded or an error code. */ static int @@ -8383,10 +8304,9 @@ xmlRelaxNGValidateDatatype(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * * Skip to the next value when validating within a list * + * @param ctxt a Relax-NG validation context * @returns 0 if the operation succeeded or an error code. */ static int @@ -8412,11 +8332,10 @@ xmlRelaxNGNextValue(xmlRelaxNGValidCtxtPtr ctxt) } /** - * @param ctxt a Relax-NG validation context - * @param defines the list of definitions to verify - * * Validate the given set of definitions for the current value * + * @param ctxt a Relax-NG validation context + * @param defines the list of definitions to verify * @returns 0 if the validation succeeded or an error code. */ static int @@ -8435,11 +8354,10 @@ xmlRelaxNGValidateValueList(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * @param define the definition to verify - * * Validate the given definition for the current value * + * @param ctxt a Relax-NG validation context + * @param define the definition to verify * @returns 0 if the validation succeeded or an error code. */ static int @@ -8703,11 +8621,10 @@ xmlRelaxNGValidateValue(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * @param defines the list of definitions to verify - * * Validate the given definitions for the current value * + * @param ctxt a Relax-NG validation context + * @param defines the list of definitions to verify * @returns 0 if the validation succeeded or an error code. */ static int @@ -8726,12 +8643,11 @@ xmlRelaxNGValidateValueContent(xmlRelaxNGValidCtxtPtr ctxt, } /** + * Check if the attribute matches the definition nameClass + * * @param ctxt a Relax-NG validation context * @param define the definition to check * @param prop the attribute - * - * Check if the attribute matches the definition nameClass - * * @returns 1 if the attribute matches, 0 if no, or -1 in case of error */ static int @@ -8790,11 +8706,10 @@ xmlRelaxNGAttributeMatch(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * @param define the definition to verify - * * Validate the given attribute definition for that node * + * @param ctxt a Relax-NG validation context + * @param define the definition to verify * @returns 0 if the validation succeeded or an error code. */ static int @@ -8883,11 +8798,10 @@ xmlRelaxNGValidateAttribute(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * @param defines the list of definition to verify - * * Validate the given node against the list of attribute definitions * + * @param ctxt a Relax-NG validation context + * @param defines the list of definition to verify * @returns 0 if the validation succeeded or an error code. */ static int @@ -8930,11 +8844,10 @@ xmlRelaxNGValidateAttributeList(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param node the node - * @param list a NULL terminated array of definitions - * * Check if a node can be matched by one of the definitions * + * @param node the node + * @param list a NULL terminated array of definitions * @returns 1 if matches 0 otherwise */ static int @@ -8967,11 +8880,10 @@ xmlRelaxNGNodeMatchesList(xmlNodePtr node, xmlRelaxNGDefinePtr * list) } /** - * @param ctxt a Relax-NG validation context - * @param define the definition to verify - * * Validate an interleave definition for a node. * + * @param ctxt a Relax-NG validation context + * @param define the definition to verify * @returns 0 if the validation succeeded or an error code. */ static int @@ -9271,11 +9183,10 @@ xmlRelaxNGValidateInterleave(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * @param defines the list of definition to verify - * * Validate the given node content against the (list) of definitions * + * @param ctxt a Relax-NG validation context + * @param defines the list of definition to verify * @returns 0 if the validation succeeded or an error code. */ static int @@ -9308,12 +9219,11 @@ xmlRelaxNGValidateDefinitionList(xmlRelaxNGValidCtxtPtr ctxt, } /** + * Check if the element matches the definition nameClass + * * @param ctxt a Relax-NG validation context * @param define the definition to check * @param elem the element - * - * Check if the element matches the definition nameClass - * * @returns 1 if the element matches, 0 if no, or -1 in case of error */ static int @@ -9421,13 +9331,12 @@ xmlRelaxNGElementMatch(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * * Find the "best" state in the ctxt->states list of states to report * errors about. I.e. a state with no element left in the child list * or the one with the less attributes left. * This is called only if a validation error was detected * + * @param ctxt a Relax-NG validation context * @returns the index of the "best" state or -1 in case of error */ static int @@ -9463,10 +9372,10 @@ xmlRelaxNGBestState(xmlRelaxNGValidCtxtPtr ctxt) } /** - * @param ctxt a Relax-NG validation context - * * Find the "best" state in the ctxt->states list of states to report * errors about and log it. + * + * @param ctxt a Relax-NG validation context */ static void xmlRelaxNGLogBestError(xmlRelaxNGValidCtxtPtr ctxt) @@ -9486,13 +9395,12 @@ xmlRelaxNGLogBestError(xmlRelaxNGValidCtxtPtr ctxt) } /** - * @param ctxt a Relax-NG validation context - * @param dolog indicate that error logging should be done - * * Validate the end of the element, implements check that * there is nothing left not consumed in the element content * or in the attribute list. * + * @param ctxt a Relax-NG validation context + * @param dolog indicate that error logging should be done * @returns 0 if the validation succeeded or an error code. */ static int @@ -9525,11 +9433,10 @@ xmlRelaxNGValidateElementEnd(xmlRelaxNGValidCtxtPtr ctxt, int dolog) } /** - * @param ctxt a Relax-NG validation context - * @param define the definition to verify - * * Validate the current state against the definition * + * @param ctxt a Relax-NG validation context + * @param define the definition to verify * @returns 0 if the validation succeeded or an error code. */ static int @@ -10248,11 +10155,10 @@ xmlRelaxNGValidateState(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * @param define the definition to verify - * * Validate the current node lists against the definition * + * @param ctxt a Relax-NG validation context + * @param define the definition to verify * @returns 0 if the validation succeeded or an error code. */ static int @@ -10380,11 +10286,10 @@ xmlRelaxNGValidateDefinition(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * @param doc the document - * * Validate the given document * + * @param ctxt a Relax-NG validation context + * @param doc the document * @returns 0 if the validation succeeded or an error code. */ static int @@ -10472,14 +10377,13 @@ xmlRelaxNGValidateDocument(xmlRelaxNGValidCtxtPtr ctxt, xmlDocPtr doc) } /** - * @param node an input element or document - * * Call this routine to speed up XPath computation on static documents. * This stamps all the element nodes with the document order * Like for line information, the order is kept in the element->content * field, the value stored is actually - the node number (starting at -1) * to be able to differentiate from line numbers. * + * @param node an input element or document * @returns the number of elements found in the document or -1 in case * of error. */ @@ -10530,10 +10434,9 @@ xmlRelaxNGCleanPSVI(xmlNodePtr node) { ************************************************************************/ /** - * @param schema a precompiled XML RelaxNGs - * * Create an XML RelaxNGs validation context based on the given schema * + * @param schema a precompiled XML RelaxNGs * @returns the validation context or NULL in case of error */ xmlRelaxNGValidCtxtPtr @@ -10562,9 +10465,9 @@ xmlRelaxNGNewValidCtxt(xmlRelaxNGPtr schema) } /** - * @param ctxt the schema validation context - * * Free the resources associated to the schema validation context + * + * @param ctxt the schema validation context */ void xmlRelaxNGFreeValidCtxt(xmlRelaxNGValidCtxtPtr ctxt) @@ -10603,14 +10506,14 @@ xmlRelaxNGFreeValidCtxt(xmlRelaxNGValidCtxtPtr ctxt) } /** + * Set the error and warning callback information + * + * @deprecated Use xmlRelaxNGSetValidStructuredErrors(). + * * @param ctxt a Relax-NG validation context * @param err the error function * @param warn the warning function * @param ctx the functions context - * - * @deprecated Use xmlRelaxNGSetValidStructuredErrors(). - * - * Set the error and warning callback information */ void xmlRelaxNGSetValidErrors(xmlRelaxNGValidCtxtPtr ctxt, @@ -10626,11 +10529,11 @@ xmlRelaxNGSetValidErrors(xmlRelaxNGValidCtxtPtr ctxt, } /** + * Set the structured error callback + * * @param ctxt a Relax-NG validation context * @param serror the structured error function * @param ctx the functions context - * - * Set the structured error callback */ void xmlRelaxNGSetValidStructuredErrors(xmlRelaxNGValidCtxtPtr ctxt, @@ -10645,13 +10548,12 @@ xmlRelaxNGSetValidStructuredErrors(xmlRelaxNGValidCtxtPtr ctxt, } /** + * Get the error and warning callback information + * * @param ctxt a Relax-NG validation context * @param err the error function result * @param warn the warning function result * @param ctx the functions context result - * - * Get the error and warning callback information - * * @returns -1 in case of error and 0 otherwise */ int @@ -10671,11 +10573,10 @@ xmlRelaxNGGetValidErrors(xmlRelaxNGValidCtxtPtr ctxt, } /** - * @param ctxt a Relax-NG validation context - * @param doc a parsed document tree - * * Validate a document tree in memory. * + * @param ctxt a Relax-NG validation context + * @param doc a parsed document tree * @returns 0 if the document is valid, a positive error code * number otherwise and -1 in case of internal or API error. */ diff --git a/runtest.c b/runtest.c index 8f78ad81..812c8528 100644 --- a/runtest.c +++ b/runtest.c @@ -607,10 +607,9 @@ static int callbacks = 0; static int quiet = 0; /** - * @param ctxt An XML parser context - * * Is this document tagged standalone ? * + * @param ctxt An XML parser context * @returns 1 if true */ static int @@ -624,10 +623,9 @@ isStandaloneDebug(void *ctx ATTRIBUTE_UNUSED) } /** - * @param ctxt An XML parser context - * * Does this document has an internal subset * + * @param ctxt An XML parser context * @returns 1 if true */ static int @@ -641,10 +639,9 @@ hasInternalSubsetDebug(void *ctx ATTRIBUTE_UNUSED) } /** - * @param ctxt An XML parser context - * * Does this document has an external subset * + * @param ctxt An XML parser context * @returns 1 if true */ static int @@ -658,9 +655,9 @@ hasExternalSubsetDebug(void *ctx ATTRIBUTE_UNUSED) } /** - * @param ctxt An XML parser context - * * Does this document has an internal subset + * + * @param ctxt An XML parser context */ static void internalSubsetDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, @@ -683,9 +680,9 @@ internalSubsetDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, } /** - * @param ctxt An XML parser context - * * Does this document has an external subset + * + * @param ctxt An XML parser context */ static void externalSubsetDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, @@ -706,16 +703,15 @@ externalSubsetDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, } /** - * @param ctxt An XML parser context - * @param publicId The public ID of the entity - * @param systemId The system ID of the entity - * * Special entity resolver, better left to the parser, it has * more context than the application layer. * The default behaviour is to NOT resolve the entities, in that case * the ENTITY_REF nodes are built in the structure (and the parameter * values). * + * @param ctxt An XML parser context + * @param publicId The public ID of the entity + * @param systemId The system ID of the entity * @returns the xmlParserInputPtr if inlined or NULL for DOM behaviour. */ static xmlParserInputPtr @@ -745,11 +741,10 @@ resolveEntityDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *publicId, const xm } /** - * @param ctxt An XML parser context - * @param name The entity name - * * Get an entity by name * + * @param ctxt An XML parser context + * @param name The entity name * @returns the xmlParserInputPtr if inlined or NULL for DOM behaviour. */ static xmlEntityPtr @@ -766,11 +761,10 @@ getEntityDebug(void *ctx, const xmlChar *name) } /** - * @param ctxt An XML parser context - * @param name The entity name - * * Get a parameter entity by name * + * @param ctxt An XML parser context + * @param name The entity name * @returns the xmlParserInputPtr */ static xmlEntityPtr @@ -788,14 +782,14 @@ getParameterEntityDebug(void *ctx, const xmlChar *name) /** + * An entity definition has been parsed + * * @param ctxt An XML parser context * @param name the entity name * @param type the entity type * @param publicId The public ID of the entity * @param systemId The system ID of the entity * @param content the entity value (without processing). - * - * An entity definition has been parsed */ static void entityDeclDebug(void *ctx, const xmlChar *name, int type, @@ -830,11 +824,11 @@ entityDeclDebug(void *ctx, const xmlChar *name, int type, } /** + * An attribute definition has been parsed + * * @param ctxt An XML parser context * @param name the attribute name * @param type the attribute type - * - * An attribute definition has been parsed */ static void attributeDeclDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar * elem, @@ -854,12 +848,12 @@ attributeDeclDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar * elem, } /** + * An element definition has been parsed + * * @param ctxt An XML parser context * @param name the element name * @param type the element type * @param content the element value (without processing). - * - * An element definition has been parsed */ static void elementDeclDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, int type, @@ -873,12 +867,12 @@ elementDeclDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, int type, } /** + * What to do when a notation declaration has been parsed. + * * @param ctxt An XML parser context * @param name The name of the notation * @param publicId The public ID of the entity * @param systemId The system ID of the entity - * - * What to do when a notation declaration has been parsed. */ static void notationDeclDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, @@ -892,13 +886,13 @@ notationDeclDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, } /** + * What to do when an unparsed entity declaration is parsed + * * @param ctxt An XML parser context * @param name The name of the entity * @param publicId The public ID of the entity * @param systemId The system ID of the entity * @param notationName the name of the notation - * - * What to do when an unparsed entity declaration is parsed */ static void unparsedEntityDeclDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, @@ -922,11 +916,11 @@ const xmlChar *nullstr = BAD_CAST "(null)"; } /** - * @param ctxt An XML parser context - * @param 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. + * + * @param ctxt An XML parser context + * @param loc A SAX Locator */ static void setDocumentLocatorDebug(void *ctx ATTRIBUTE_UNUSED, xmlSAXLocatorPtr loc ATTRIBUTE_UNUSED) @@ -938,9 +932,9 @@ setDocumentLocatorDebug(void *ctx ATTRIBUTE_UNUSED, xmlSAXLocatorPtr loc ATTRIBU } /** - * @param ctxt An XML parser context - * * called when the document start being processed. + * + * @param ctxt An XML parser context */ static void startDocumentDebug(void *ctx ATTRIBUTE_UNUSED) @@ -952,9 +946,9 @@ startDocumentDebug(void *ctx ATTRIBUTE_UNUSED) } /** - * @param ctxt An XML parser context - * * called when the document end has been detected. + * + * @param ctxt An XML parser context */ static void endDocumentDebug(void *ctx ATTRIBUTE_UNUSED) @@ -966,10 +960,10 @@ endDocumentDebug(void *ctx ATTRIBUTE_UNUSED) } /** + * called when an opening tag has been processed. + * * @param ctxt An XML parser context * @param name The element name - * - * called when an opening tag has been processed. */ static void startElementDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, const xmlChar **atts) @@ -991,10 +985,10 @@ startElementDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, const xmlChar } /** + * called when the end of an element has been detected. + * * @param ctxt An XML parser context * @param name The element name - * - * called when the end of an element has been detected. */ static void endElementDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name) @@ -1006,12 +1000,12 @@ endElementDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name) } /** + * receiving some chars from the parser. + * Question: how much at a time ??? + * * @param ctxt An XML parser context * @param ch a xmlChar string * @param len the number of xmlChar - * - * receiving some chars from the parser. - * Question: how much at a time ??? */ static void charactersDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *ch, int len) @@ -1030,10 +1024,10 @@ charactersDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *ch, int len) } /** + * called when an entity reference is detected. + * * @param ctxt An XML parser context * @param name The entity name - * - * called when an entity reference is detected. */ static void referenceDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name) @@ -1045,13 +1039,13 @@ referenceDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name) } /** + * receiving some ignorable whitespaces from the parser. + * Question: how much at a time ??? + * * @param ctxt An XML parser context * @param ch a xmlChar string * @param start the first char in the string * @param len the number of xmlChar - * - * receiving some ignorable whitespaces from the parser. - * Question: how much at a time ??? */ static void ignorableWhitespaceDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *ch, int len) @@ -1069,12 +1063,12 @@ ignorableWhitespaceDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *ch, int len) } /** + * A processing instruction has been parsed. + * * @param ctxt An XML parser context * @param target the target name * @param data the PI data's * @param len the number of xmlChar - * - * A processing instruction has been parsed. */ static void processingInstructionDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *target, @@ -1092,11 +1086,11 @@ processingInstructionDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *target, } /** + * called when a pcdata block has been parsed + * * @param ctx the user data (XML parser context) * @param value The pcdata content * @param len the block length - * - * called when a pcdata block has been parsed */ static void cdataBlockDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *value, int len) @@ -1109,10 +1103,10 @@ cdataBlockDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *value, int len) } /** + * A comment has been parsed. + * * @param ctxt An XML parser context * @param value the comment content - * - * A comment has been parsed. */ static void commentDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *value) @@ -1124,12 +1118,13 @@ commentDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *value) } /** - * @param ctxt An XML parser context - * @param msg the message to display/transmit - * @...: extra parameters for the message display - * * Display and format a warning messages, gives file, line, position and * extra parameters. + * + * @...: extra parameters for the message display + * + * @param ctxt An XML parser context + * @param msg the message to display/transmit */ static void warningDebug(void *ctx ATTRIBUTE_UNUSED, const char *msg, ...) @@ -1146,12 +1141,13 @@ warningDebug(void *ctx ATTRIBUTE_UNUSED, const char *msg, ...) } /** - * @param ctxt An XML parser context - * @param msg the message to display/transmit - * @...: extra parameters for the message display - * * Display and format a error messages, gives file, line, position and * extra parameters. + * + * @...: extra parameters for the message display + * + * @param ctxt An XML parser context + * @param msg the message to display/transmit */ static void errorDebug(void *ctx ATTRIBUTE_UNUSED, const char *msg, ...) @@ -1168,12 +1164,13 @@ errorDebug(void *ctx ATTRIBUTE_UNUSED, const char *msg, ...) } /** - * @param ctxt An XML parser context - * @param msg the message to display/transmit - * @...: extra parameters for the message display - * * Display and format a fatalError messages, gives file, line, position and * extra parameters. + * + * @...: extra parameters for the message display + * + * @param ctxt An XML parser context + * @param msg the message to display/transmit */ static void fatalErrorDebug(void *ctx ATTRIBUTE_UNUSED, const char *msg, ...) @@ -1230,10 +1227,10 @@ static xmlSAXHandlerPtr debugSAXHandler = &debugSAXHandlerStruct; * SAX2 specific callbacks */ /** + * called when an opening tag has been processed. + * * @param ctxt An XML parser context * @param name The element name - * - * called when an opening tag has been processed. */ static void startElementNsDebug(void *ctx ATTRIBUTE_UNUSED, @@ -1286,10 +1283,10 @@ startElementNsDebug(void *ctx ATTRIBUTE_UNUSED, } /** + * called when the end of an element has been detected. + * * @param ctxt An XML parser context * @param name The element name - * - * called when the end of an element has been detected. */ static void endElementNsDebug(void *ctx ATTRIBUTE_UNUSED, @@ -1350,10 +1347,10 @@ static xmlSAXHandlerPtr debugSAX2Handler = &debugSAX2HandlerStruct; #ifdef LIBXML_HTML_ENABLED /** + * called when an opening tag has been processed. + * * @param ctxt An XML parser context * @param name The element name - * - * called when an opening tag has been processed. */ static void htmlstartElementDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, const xmlChar **atts) @@ -1384,12 +1381,12 @@ htmlstartElementDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *name, const xml } /** + * receiving some chars from the parser. + * Question: how much at a time ??? + * * @param ctxt An XML parser context * @param ch a xmlChar string * @param len the number of xmlChar - * - * receiving some chars from the parser. - * Question: how much at a time ??? */ static void htmlcharactersDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *ch, int len) @@ -1404,12 +1401,12 @@ htmlcharactersDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *ch, int len) } /** + * receiving some cdata chars from the parser. + * Question: how much at a time ??? + * * @param ctxt An XML parser context * @param ch a xmlChar string * @param len the number of xmlChar - * - * receiving some cdata chars from the parser. - * Question: how much at a time ??? */ static void htmlcdataDebug(void *ctx ATTRIBUTE_UNUSED, const xmlChar *ch, int len) @@ -1469,12 +1466,11 @@ hashFreeEntity(void *payload, const xmlChar *name ATTRIBUTE_UNUSED) { } /** + * Parse a file using the SAX API and check for errors. + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file using the SAX API and check for errors. - * * @returns 0 in case of success, an error code otherwise */ static int @@ -1710,12 +1706,11 @@ static xmlSAXHandler tokenizeHtmlSAXHandler = { }; /** + * Parse a file using the SAX API and check for errors. + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file using the SAX API and check for errors. - * * @returns 0 in case of success, an error code otherwise */ static int @@ -1804,14 +1799,13 @@ htmlTokenizerTest(const char *filename, const char *result, * * ************************************************************************/ /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages: unused - * * Parse a file using the old xmlParseFile() API, then serialize back * reparse the result and serialize again, then check for deviation * in serialization. * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages: unused * @returns 0 in case of success, an error code otherwise */ static int @@ -1874,13 +1868,12 @@ oldParseTest(const char *filename, const char *result, #ifdef LIBXML_PUSH_ENABLED /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages: unused - * * Parse a file using the Push API, then serialize back * to check for content. * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages: unused * @returns 0 in case of success, an error code otherwise */ static int @@ -2060,13 +2053,12 @@ endElementNsBnd(void *ctx, const xmlChar *localname, const xmlChar *prefix, } /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages: unused - * * Test whether the push parser detects boundaries between syntactical * elements correctly. * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages: unused * @returns 0 in case of success, an error code otherwise */ static int @@ -2374,14 +2366,13 @@ testParseContent(xmlParserCtxtPtr ctxt, xmlDocPtr doc, const char *filename) { } /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages: unused - * * Parse a file using the old xmlReadMemory() API, then serialize back * reparse the result and serialize again, then check for deviation * in serialization. * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages: unused * @returns 0 in case of success, an error code otherwise */ static int @@ -2428,14 +2419,13 @@ memParseTest(const char *filename, const char *result, } /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages: unused - * * Parse a file with entity resolution, then serialize back * reparse the result and serialize again, then check for deviation * in serialization. * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages: unused * @returns 0 in case of success, an error code otherwise */ static int @@ -2486,12 +2476,11 @@ noentParseTest(const char *filename, const char *result, } /** + * Parse a file using the xmlReadFile() API and check for errors. + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file using the xmlReadFile() API and check for errors. - * * @returns 0 in case of success, an error code otherwise */ static int @@ -2574,12 +2563,11 @@ errParseTest(const char *filename, const char *result, const char *err, #if defined(LIBXML_VALID_ENABLED) || defined(LIBXML_HTML_ENABLED) /** + * Parse a file using the xmlReadFd() API and check for errors. + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file using the xmlReadFd() API and check for errors. - * * @returns 0 in case of success, an error code otherwise */ static int @@ -2760,12 +2748,11 @@ streamProcessTest(const char *filename, const char *result, const char *err, } /** + * Parse a file using the reader API and check for errors. + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file using the reader API and check for errors. - * * @returns 0 in case of success, an error code otherwise */ static int @@ -2783,12 +2770,11 @@ streamParseTest(const char *filename, const char *result, const char *err, } /** + * Parse a file using the walker, i.e. a reader built from a atree. + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file using the walker, i.e. a reader built from a atree. - * * @returns 0 in case of success, an error code otherwise */ static int @@ -2811,12 +2797,11 @@ walkerParseTest(const char *filename, const char *result, const char *err, } /** + * Parse a file using the reader API from memory and check for errors. + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file using the reader API from memory and check for errors. - * * @returns 0 in case of success, an error code otherwise */ static int @@ -2893,12 +2878,11 @@ testXPath(const char *str, int xptr, int expr) { } /** + * Parse a file containing XPath standalone expressions and evaluate them + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file containing XPath standalone expressions and evaluate them - * * @returns 0 in case of success, an error code otherwise */ static int @@ -2960,12 +2944,11 @@ xpathCommonTest(const char *filename, const char *result, } /** + * Parse a file containing XPath standalone expressions and evaluate them + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file containing XPath standalone expressions and evaluate them - * * @returns 0 in case of success, an error code otherwise */ static int @@ -2976,13 +2959,12 @@ xpathExprTest(const char *filename, const char *result, } /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages - * * Parse a file containing XPath expressions and evaluate them against * a set of corresponding documents. * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages * @returns 0 in case of success, an error code otherwise */ static int @@ -3027,13 +3009,12 @@ xpathDocTest(const char *filename, #ifdef LIBXML_XPTR_ENABLED /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages - * * Parse a file containing XPath expressions and evaluate them against * a set of corresponding documents. * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages * @returns 0 in case of success, an error code otherwise */ static int @@ -3079,13 +3060,12 @@ xptrDocTest(const char *filename, #ifdef LIBXML_VALID_ENABLED /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages - * * Parse a file containing xml:id and check for errors and verify * that XPath queries will work on them as expected. * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages * @returns 0 in case of success, an error code otherwise */ static int @@ -3188,12 +3168,11 @@ handleURI(const char *str, const char *base, FILE *o) { } /** + * Parse a file containing URI and check for errors + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file containing URI and check for errors - * * @returns 0 in case of success, an error code otherwise */ static int @@ -3275,12 +3254,11 @@ uriCommonTest(const char *filename, } /** + * Parse a file containing URI and check for errors + * * @param filename the file to parse * @param result the file with expected result * @param err the file with error messages - * - * Parse a file containing URI and check for errors - * * @returns 0 in case of success, an error code otherwise */ static int @@ -3292,13 +3270,12 @@ uriParseTest(const char *filename, } /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages - * * Parse a file containing URI, compose them against a fixed base and * check for errors * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages * @returns 0 in case of success, an error code otherwise */ static int @@ -3347,10 +3324,9 @@ static const char *urip_cur = NULL; static int urip_rlen; /** - * @param URI an URI to test - * * Check for an urip: query * + * @param URI an URI to test * @returns 1 if yes and 0 if another Input module should be used */ static int @@ -3368,10 +3344,8 @@ uripMatch(const char * URI) { /** * @param URI an URI to test - * * @returns a pointer to the urip: query handler, in this example simply * the urip_current pointer... - * * @returns an Input context or NULL in case or error */ static void * @@ -3390,10 +3364,9 @@ uripOpen(const char * URI) { } /** - * @param context the read context - * * Close the urip: query handler * + * @param context the read context * @returns 0 or -1 in case of error */ static int @@ -3405,12 +3378,11 @@ uripClose(void * context) { } /** + * Implement an urip: query read. + * * @param context the read context * @param buffer where to store data * @param len number of bytes to read - * - * Implement an urip: query read. - * * @returns the number of bytes read or -1 in case of error */ static int @@ -3438,13 +3410,12 @@ urip_checkURL(const char *URL) { } /** - * @param filename ignored - * @param result ignored - * @param err ignored - * * Run a set of tests to check how Path and URI are handled before * being passed to the I/O layer * + * @param filename ignored + * @param result ignored + * @param err ignored * @returns 0 in case of success, an error code otherwise */ static int @@ -3552,13 +3523,12 @@ done: return(ret); } /** - * @param filename the schemas file - * @param result the file with expected result - * @param err the file with error messages - * * Parse a file containing URI, compose them against a fixed base and * check for errors * + * @param filename the schemas file + * @param result the file with expected result + * @param err the file with error messages * @returns 0 in case of success, an error code otherwise */ static int @@ -3684,12 +3654,11 @@ rngOneTest(const char *sch, return(0); } /** + * Parse an RNG schemas and then apply it to the related .xml + * * @param filename the schemas file * @param result the file with expected result * @param err the file with error messages - * - * Parse an RNG schemas and then apply it to the related .xml - * * @returns 0 in case of success, an error code otherwise */ static int @@ -3775,12 +3744,11 @@ rngTest(const char *filename, #ifdef LIBXML_READER_ENABLED /** + * Parse a set of files with streaming, applying an RNG schemas + * * @param filename the schemas file * @param result the file with expected result * @param err the file with error messages - * - * Parse a set of files with streaming, applying an RNG schemas - * * @returns 0 in case of success, an error code otherwise */ static int @@ -3916,7 +3884,6 @@ schematronOneTest(const char *sch, const char *filename, int options, * @param filename the schemas file * @param result the file with expected result * @param err the file with error messages - * * @returns 0 in case of success, an error code otherwise */ static int @@ -4064,12 +4031,11 @@ static void patternNode(FILE *out, xmlTextReaderPtr reader, } /** + * Parse a set of files with streaming, applying an RNG schemas + * * @param filename the schemas file * @param result the file with expected result * @param err the file with error messages - * - * Parse a set of files with streaming, applying an RNG schemas - * * @returns 0 in case of success, an error code otherwise */ static int diff --git a/schematron.c b/schematron.c index 2e82d7da..69bd6ef9 100644 --- a/schematron.c +++ b/schematron.c @@ -213,9 +213,9 @@ struct _xmlSchematronParserCtxt { ************************************************************************/ /** - * @param ctxt parser context - * * Handle an out of memory condition + * + * @param ctxt parser context */ static void xmlSchematronPErrMemory(xmlSchematronParserCtxtPtr ctxt) @@ -226,14 +226,14 @@ xmlSchematronPErrMemory(xmlSchematronParserCtxtPtr ctxt) } /** + * Handle a parser error + * * @param ctxt the parsing context * @param node the context node * @param error the error code * @param msg the error message * @param str1 extra data * @param str2 extra data - * - * Handle a parser error */ static void LIBXML_ATTR_FORMAT(4,0) xmlSchematronPErr(xmlSchematronParserCtxtPtr ctxt, xmlNodePtr node, int error, @@ -265,9 +265,9 @@ xmlSchematronPErr(xmlSchematronParserCtxtPtr ctxt, xmlNodePtr node, int error, } /** - * @param ctxt validation context - * * Handle an out of memory condition + * + * @param ctxt validation context */ static void xmlSchematronVErrMemory(xmlSchematronValidCtxtPtr ctxt) @@ -280,12 +280,12 @@ xmlSchematronVErrMemory(xmlSchematronValidCtxtPtr ctxt) } /** + * Handle a validation error + * * @param ctxt validation context * @param error the error code * @param msg the error message * @param str1 extra data - * - * Handle a validation error */ static void LIBXML_ATTR_FORMAT(3,0) xmlSchematronVErr(xmlSchematronValidCtxtPtr ctxt, int error, @@ -323,15 +323,14 @@ xmlSchematronVErr(xmlSchematronValidCtxtPtr ctxt, int error, ************************************************************************/ /** + * Add a test to a schematron + * * @param ctxt the schema parsing context * @param type the type of test * @param rule the parent rule * @param node the node hosting the test * @param test the associated test * @param report the associated report string - * - * Add a test to a schematron - * * @returns the new pointer or NULL in case of error */ static xmlSchematronTestPtr @@ -384,9 +383,9 @@ xmlSchematronAddTest(xmlSchematronParserCtxtPtr ctxt, } /** - * @param tests a list of tests - * * Free a list of tests. + * + * @param tests a list of tests */ static void xmlSchematronFreeTests(xmlSchematronTestPtr tests) { @@ -406,9 +405,9 @@ xmlSchematronFreeTests(xmlSchematronTestPtr tests) { } /** - * @param lets a list of let variables - * * Free a list of let variables. + * + * @param lets a list of let variables */ static void xmlSchematronFreeLets(xmlSchematronLetPtr lets) { @@ -426,15 +425,14 @@ xmlSchematronFreeLets(xmlSchematronLetPtr lets) { } /** + * Add a rule to a schematron + * * @param ctxt the schema parsing context * @param schema a schema structure * @param pat a pattern * @param node the node hosting the rule * @param context the associated context string * @param report the associated report string - * - * Add a rule to a schematron - * * @returns the new pointer or NULL in case of error */ static xmlSchematronRulePtr @@ -496,9 +494,9 @@ xmlSchematronAddRule(xmlSchematronParserCtxtPtr ctxt, xmlSchematronPtr schema, } /** - * @param rules a list of rules - * * Free a list of rules. + * + * @param rules a list of rules */ static void xmlSchematronFreeRules(xmlSchematronRulePtr rules) { @@ -522,13 +520,12 @@ xmlSchematronFreeRules(xmlSchematronRulePtr rules) { } /** + * Add a pattern to a schematron + * * @param ctxt the schema parsing context * @param schema a schema structure * @param node the node hosting the pattern * @param name the name of the pattern - * - * Add a pattern to a schematron - * * @returns the new pointer or NULL in case of error */ static xmlSchematronPatternPtr @@ -561,9 +558,9 @@ xmlSchematronAddPattern(xmlSchematronParserCtxtPtr ctxt, } /** - * @param patterns a list of patterns - * * Free a list of patterns. + * + * @param patterns a list of patterns */ static void xmlSchematronFreePatterns(xmlSchematronPatternPtr patterns) { @@ -579,10 +576,9 @@ xmlSchematronFreePatterns(xmlSchematronPatternPtr patterns) { } /** - * @param ctxt a schema validation context - * * Allocate a new Schematron structure. * + * @param ctxt a schema validation context * @returns the newly allocated structure or NULL in case or error */ static xmlSchematronPtr @@ -603,9 +599,9 @@ xmlSchematronNewSchematron(xmlSchematronParserCtxtPtr ctxt) } /** - * @param schema a schema structure - * * Deallocate a Schematron structure. + * + * @param schema a schema structure */ void xmlSchematronFree(xmlSchematronPtr schema) @@ -626,11 +622,10 @@ xmlSchematronFree(xmlSchematronPtr schema) } /** - * @param URL the location of the schema - * * Create an XML Schematrons parse context for that file/resource expected * to contain an XML Schematrons file. * + * @param URL the location of the schema * @returns the parser context or NULL in case of error */ xmlSchematronParserCtxtPtr @@ -664,12 +659,11 @@ xmlSchematronNewParserCtxt(const char *URL) } /** - * @param buffer a pointer to a char array containing the schemas - * @param size the size of the array - * * Create an XML Schematrons parse context for that memory buffer expected * to contain an XML Schematrons file. * + * @param buffer a pointer to a char array containing the schemas + * @param size the size of the array * @returns the parser context or NULL in case of error */ xmlSchematronParserCtxtPtr @@ -701,11 +695,10 @@ xmlSchematronNewMemParserCtxt(const char *buffer, int size) } /** - * @param doc a preparsed document tree - * * Create an XML Schematrons parse context for that document. * NB. The document may be modified during the parsing process. * + * @param doc a preparsed document tree * @returns the parser context or NULL in case of error */ xmlSchematronParserCtxtPtr @@ -739,9 +732,9 @@ xmlSchematronNewDocParserCtxt(xmlDocPtr doc) } /** - * @param ctxt the schema parser context - * * Free the resources associated to the schema parser context + * + * @param ctxt the schema parser context */ void xmlSchematronFreeParserCtxt(xmlSchematronParserCtxtPtr ctxt) @@ -761,11 +754,11 @@ xmlSchematronFreeParserCtxt(xmlSchematronParserCtxtPtr ctxt) #if 0 /** + * Add an included document + * * @param ctxt the schema parser context * @param doc the included document * @param cur the current include node - * - * Add an included document */ static void xmlSchematronPushInclude(xmlSchematronParserCtxtPtr ctxt, @@ -799,10 +792,9 @@ xmlSchematronPushInclude(xmlSchematronParserCtxtPtr ctxt, } /** - * @param ctxt the schema parser context - * * Pop an include level. The included document is being freed * + * @param ctxt the schema parser context * @returns the node immediately following the include or NULL if the * include list was empty. */ @@ -827,11 +819,11 @@ xmlSchematronPopInclude(xmlSchematronParserCtxtPtr ctxt) #endif /** + * Add a namespace definition in the context + * * @param ctxt the schema parser context * @param prefix the namespace prefix * @param ns the namespace name - * - * Add a namespace definition in the context */ static void xmlSchematronAddNamespace(xmlSchematronParserCtxtPtr ctxt, @@ -870,10 +862,10 @@ xmlSchematronAddNamespace(xmlSchematronParserCtxtPtr ctxt, } /** + * Format the message content of the assert or report test + * * @param ctxt the schema parser context * @param con the assert or report node - * - * Format the message content of the assert or report test */ static void xmlSchematronParseTestReportMsg(xmlSchematronParserCtxtPtr ctxt, xmlNodePtr con) @@ -919,11 +911,11 @@ xmlSchematronParseTestReportMsg(xmlSchematronParserCtxtPtr ctxt, xmlNodePtr con) } /** + * parse a rule element + * * @param ctxt a schema validation context * @param pattern a pattern * @param rule the rule node - * - * parse a rule element */ static void xmlSchematronParseRule(xmlSchematronParserCtxtPtr ctxt, @@ -1087,10 +1079,10 @@ xmlSchematronParseRule(xmlSchematronParserCtxtPtr ctxt, } /** + * parse a pattern element + * * @param ctxt a schema validation context * @param pat the pattern node - * - * parse a pattern element */ static void xmlSchematronParsePattern(xmlSchematronParserCtxtPtr ctxt, xmlNodePtr pat) @@ -1135,11 +1127,10 @@ xmlSchematronParsePattern(xmlSchematronParserCtxtPtr ctxt, xmlNodePtr pat) #if 0 /** - * @param ctxt a schema validation context - * @param cur the include element - * * Load the include document, Push the current pointer * + * @param ctxt a schema validation context + * @param cur the include element * @returns the updated node pointer */ static xmlNodePtr @@ -1200,11 +1191,10 @@ done: #endif /** - * @param ctxt a schema validation context - * * parse a schema definition resource and build an internal * XML Schema structure which can be used to validate instances. * + * @param ctxt a schema validation context * @returns the internal XML Schematron structure built from the resource or * NULL in case of error */ @@ -1398,11 +1388,11 @@ xmlSchematronGetNode(xmlSchematronValidCtxtPtr ctxt, } /** + * Output part of the report to whatever channel the user selected + * * @param ctxt the validation context * @param cur the current node tested * @param msg the message output - * - * Output part of the report to whatever channel the user selected */ static void xmlSchematronReportOutput(xmlSchematronValidCtxtPtr ctxt ATTRIBUTE_UNUSED, @@ -1413,12 +1403,11 @@ xmlSchematronReportOutput(xmlSchematronValidCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** + * Build the string being reported to the user. + * * @param ctxt the validation context * @param test the test node * @param cur the current node tested - * - * Build the string being reported to the user. - * * @returns a report string or NULL in case of error. The string needs * to be deallocated by the caller */ @@ -1541,14 +1530,14 @@ xmlSchematronFormatReport(xmlSchematronValidCtxtPtr ctxt, } /** + * called from the validation engine when an assert or report test have + * been done. + * * @param ctxt the validation context * @param test the compiled test * @param cur the current node tested * @param pattern a pattern * @param success boolean value for the result - * - * called from the validation engine when an assert or report test have - * been done. */ static void xmlSchematronReportSuccess(xmlSchematronValidCtxtPtr ctxt, @@ -1631,10 +1620,10 @@ xmlSchematronReportSuccess(xmlSchematronValidCtxtPtr ctxt, } /** + * called from the validation engine when starting to check a pattern + * * @param ctxt the validation context * @param pattern the current pattern - * - * called from the validation engine when starting to check a pattern */ static void xmlSchematronReportPattern(xmlSchematronValidCtxtPtr ctxt, @@ -1663,11 +1652,11 @@ xmlSchematronReportPattern(xmlSchematronValidCtxtPtr ctxt, ************************************************************************/ /** + * Set the structured error callback + * * @param ctxt a Schematron validation context * @param serror the structured error function * @param ctx the functions context - * - * Set the structured error callback */ void xmlSchematronSetValidStructuredErrors(xmlSchematronValidCtxtPtr ctxt, @@ -1682,11 +1671,10 @@ xmlSchematronSetValidStructuredErrors(xmlSchematronValidCtxtPtr ctxt, } /** - * @param schema a precompiled XML Schematrons - * @param options a set of xmlSchematronValidOptions - * * Create an XML Schematrons validation context based on the given schema. * + * @param schema a precompiled XML Schematrons + * @param options a set of xmlSchematronValidOptions * @returns the validation context or NULL in case of error */ xmlSchematronValidCtxtPtr @@ -1724,9 +1712,9 @@ xmlSchematronNewValidCtxt(xmlSchematronPtr schema, int options) } /** - * @param ctxt the schema validation context - * * Free the resources associated to the schema validation context + * + * @param ctxt the schema validation context */ void xmlSchematronFreeValidCtxt(xmlSchematronValidCtxtPtr ctxt) @@ -1776,14 +1764,13 @@ xmlSchematronNextNode(xmlNodePtr cur) { } /** + * Validate a rule against a tree instance at a given position + * * @param ctxt the schema validation context * @param test the current test * @param instance the document instance tree * @param cur the current node in the instance * @param pattern a pattern - * - * Validate a rule against a tree instance at a given position - * * @returns 1 in case of success, 0 if error and -1 in case of internal error */ static int @@ -1838,14 +1825,13 @@ xmlSchematronRunTest(xmlSchematronValidCtxtPtr ctxt, } /** + * Registers a list of let variables to the current context of `cur` + * * @param vctxt the schema validation context * @param ctxt an XPath context * @param let the list of let variables * @param instance the document instance tree * @param cur the current node - * - * Registers a list of let variables to the current context of `cur` - * * @returns -1 in case of errors, otherwise 0 */ static int @@ -1877,12 +1863,11 @@ xmlSchematronRegisterVariables(xmlSchematronValidCtxtPtr vctxt, } /** + * Unregisters a list of let variables from the context + * * @param vctxt the schema validation context * @param ctxt an XPath context * @param let the list of let variables - * - * Unregisters a list of let variables from the context - * * @returns -1 in case of errors, otherwise 0 */ static int @@ -1902,11 +1887,10 @@ xmlSchematronUnregisterVariables(xmlSchematronValidCtxtPtr vctxt, } /** - * @param ctxt the schema validation context - * @param instance the document instance tree - * * Validate a tree instance against the schematron * + * @param ctxt the schema validation context + * @param instance the document instance tree * @returns 0 in case of success, -1 in case of internal error * and an error count otherwise. */ diff --git a/shell.c b/shell.c index 9156feef..9b5f3125 100644 --- a/shell.c +++ b/shell.c @@ -62,10 +62,9 @@ struct _xmllintShellCtxt { }; /** - * @param node the node to count - * * Count the children of `node`. * + * @param node the node to count * @returns the number of children of `node`. */ static int @@ -116,10 +115,10 @@ xmllintLsCountNode(xmlNodePtr node) { } /** + * Dump to `output` the type and name of `node`. + * * @param output the FILE * for the output * @param node the node to dump - * - * Dump to `output` the type and name of `node`. */ static void xmllintLsOneNode(FILE *output, xmlNodePtr node) { @@ -250,14 +249,13 @@ xmllintLsOneNode(FILE *output, xmlNodePtr node) { } /** + * Implements the XML shell function "ls" + * Does an Unix like listing of the given node (like a directory) + * * @param ctxt the shell context * @param arg unused * @param node a node * @param node2 unused - * - * Implements the XML shell function "ls" - * Does an Unix like listing of the given node (like a directory) - * * @returns 0 */ static int @@ -292,14 +290,13 @@ xmllintShellList(xmllintShellCtxtPtr ctxt, } /** + * Implements the XML shell function "base" + * dumps the current XML base of the node + * * @param ctxt the shell context * @param arg unused * @param node a node * @param node2 unused - * - * Implements the XML shell function "base" - * dumps the current XML base of the node - * * @returns 0 */ static int @@ -327,14 +324,13 @@ xmllintShellBase(xmllintShellCtxtPtr ctxt, } /** + * Implements the XML shell function "setbase" + * change the current XML base of the node + * * @param ctxt the shell context * @param arg the new base * @param node a node * @param node2 unused - * - * Implements the XML shell function "setbase" - * change the current XML base of the node - * * @returns 0 */ static int @@ -348,15 +344,14 @@ xmllintShellSetBase(xmllintShellCtxtPtr ctxt ATTRIBUTE_UNUSED, #ifdef LIBXML_XPATH_ENABLED /** - * @param ctxt the shell context - * @param arg a string in prefix=nsuri format - * @param node unused - * @param node2 unused - * * Implements the XML shell function "setns" * register/unregister a prefix=namespace pair * on the XPath context * + * @param ctxt the shell context + * @param arg a string in prefix=nsuri format + * @param node unused + * @param node2 unused * @returns 0 on success and a negative value otherwise. */ static int @@ -404,14 +399,13 @@ xmllintShellRegisterNamespace(xmllintShellCtxtPtr ctxt, char *arg, return(0); } /** + * Implements the XML shell function "setrootns" + * which registers all namespaces declarations found on the root element. + * * @param ctxt the shell context * @param arg unused * @param root the root element * @param node2 unused - * - * Implements the XML shell function "setrootns" - * which registers all namespaces declarations found on the root element. - * * @returns 0 on success and a negative value otherwise. */ static int @@ -436,14 +430,13 @@ xmllintShellRegisterRootNamespaces(xmllintShellCtxtPtr ctxt, char *arg ATTRIBUTE #endif /** + * Implements the XML shell function "grep" + * dumps information about the node (namespace, attributes, content). + * * @param ctxt the shell context * @param arg the string or regular expression to find * @param node a node * @param node2 unused - * - * Implements the XML shell function "grep" - * dumps information about the node (namespace, attributes, content). - * * @returns 0 */ static int @@ -511,14 +504,13 @@ xmllintShellGrep(xmllintShellCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** + * Implements the XML shell function "dir" + * dumps information about the node (namespace, attributes, content). + * * @param ctxt the shell context * @param arg unused * @param node a node * @param node2 unused - * - * Implements the XML shell function "dir" - * dumps information about the node (namespace, attributes, content). - * * @returns 0 */ static int @@ -546,14 +538,13 @@ xmllintShellDir(xmllintShellCtxtPtr ctxt ATTRIBUTE_UNUSED, } /** + * Implements the XML shell function "dir" + * dumps information about the node (namespace, attributes, content). + * * @param ctxt the shell context * @param value the content as a string * @param node a node * @param node2 unused - * - * Implements the XML shell function "dir" - * dumps information about the node (namespace, attributes, content). - * * @returns 0 */ static int @@ -603,14 +594,13 @@ xmllintShellPrintf(void *ctx, const char *msg, ...) { #ifdef LIBXML_RELAXNG_ENABLED /** + * Implements the XML shell function "relaxng" + * validating the instance against a Relax-NG schemas + * * @param sctxt the shell context * @param schemas the path to the Relax-NG schemas * @param node a node * @param node2 unused - * - * Implements the XML shell function "relaxng" - * validating the instance against a Relax-NG schemas - * * @returns 0 */ static int @@ -652,14 +642,13 @@ xmllintShellRNGValidate(xmllintShellCtxtPtr sctxt, char *schemas, #ifdef LIBXML_OUTPUT_ENABLED /** + * Implements the XML shell function "cat" + * dumps the serialization node content (XML or HTML). + * * @param ctxt the shell context * @param arg unused * @param node a node * @param node2 unused - * - * Implements the XML shell function "cat" - * dumps the serialization node content (XML or HTML). - * * @returns 0 */ static int @@ -696,14 +685,13 @@ xmllintShellCat(xmllintShellCtxtPtr ctxt, char *arg ATTRIBUTE_UNUSED, #endif /* LIBXML_OUTPUT_ENABLED */ /** + * Implements the XML shell function "load" + * loads a new document specified by the filename + * * @param ctxt the shell context * @param filename the file name * @param node unused * @param node2 unused - * - * Implements the XML shell function "load" - * loads a new document specified by the filename - * * @returns 0 or -1 if loading failed */ static int @@ -750,15 +738,14 @@ xmllintShellLoad(xmllintShellCtxtPtr ctxt, char *filename, #ifdef LIBXML_OUTPUT_ENABLED /** - * @param ctxt the shell context - * @param filename the file name - * @param node a node in the tree - * @param node2 unused - * * Implements the XML shell function "write" * Write the current node to the filename, it saves the serialization * of the subtree under the `node` specified * + * @param ctxt the shell context + * @param filename the file name + * @param node a node in the tree + * @param node2 unused * @returns 0 or -1 in case of error */ static int @@ -810,14 +797,13 @@ xmllintShellWrite(xmllintShellCtxtPtr ctxt, char *filename, xmlNodePtr node, } /** + * Implements the XML shell function "save" + * Write the current document to the filename, or it's original name + * * @param ctxt the shell context * @param filename the file name (optional) * @param node unused * @param node2 unused - * - * Implements the XML shell function "save" - * Write the current document to the filename, or it's original name - * * @returns 0 or -1 in case of error */ static int @@ -863,15 +849,14 @@ xmllintShellSave(xmllintShellCtxtPtr ctxt, char *filename, #ifdef LIBXML_VALID_ENABLED /** - * @param ctxt the shell context - * @param dtd the DTD URI (optional) - * @param node unused - * @param node2 unused - * * Implements the XML shell function "validate" * Validate the document, if a DTD path is provided, then the validation * is done against the given DTD. * + * @param ctxt the shell context + * @param dtd the DTD URI (optional) + * @param node unused + * @param node2 unused * @returns 0 or -1 in case of error */ static int @@ -905,15 +890,14 @@ xmllintShellValidate(xmllintShellCtxtPtr ctxt, char *dtd, #endif /* LIBXML_VALID_ENABLED */ /** - * @param ctxt the shell context - * @param arg unused - * @param tree a node defining a subtree - * @param node2 unused - * * Implements the XML shell function "du" * show the structure of the subtree under node `tree` * If `tree` is null, the command works on the current node. * + * @param ctxt the shell context + * @param arg unused + * @param tree a node defining a subtree + * @param node2 unused * @returns 0 or -1 in case of error */ static int @@ -988,16 +972,15 @@ xmllintShellDu(xmllintShellCtxtPtr ctxt, } /** - * @param ctxt the shell context - * @param buffer the output buffer - * @param node a node - * @param node2 unused - * * Implements the XML shell function "pwd" * Show the full path from the root to the node, if needed building * thumblers when similar elements exists at a given ancestor level. * The output is compatible with XPath commands. * + * @param ctxt the shell context + * @param buffer the output buffer + * @param node a node + * @param node2 unused * @returns 0 or -1 in case of error */ static int @@ -1029,10 +1012,9 @@ xmllintShellPwd(xmllintShellCtxtPtr ctxt ATTRIBUTE_UNUSED, char *buffer, } /** - * @param prompt the prompt value - * * Read a string * + * @param prompt the prompt value * @returns a pointer to it or NULL on EOF the caller is expected to * free the returned string. */ @@ -1074,13 +1056,13 @@ xmllintShellReadline(char *prompt) { } /** - * @param doc the initial document - * @param filename the output buffer - * @param output the output FILE*, defaults to stdout if NULL - * * Implements the XML shell * This allow to load, validate, view, modify and save a document * using a environment similar to a UNIX commandline. + * + * @param doc the initial document + * @param filename the output buffer + * @param output the output FILE*, defaults to stdout if NULL */ void xmllintShell(xmlDocPtr doc, const char *filename, FILE * output) diff --git a/testlimits.c b/testlimits.c index fba54c6e..54b6c259 100644 --- a/testlimits.c +++ b/testlimits.c @@ -89,10 +89,9 @@ static unsigned int currentTest = 0; static int instate = 0; /** - * @param URI an URI to test - * * Check for an huge: query * + * @param URI an URI to test * @returns 1 if yes and 0 if another Input module should be used */ static int @@ -104,10 +103,8 @@ hugeMatch(const char * URI) { /** * @param URI an URI to test - * * @returns a pointer to the huge: query handler, in this example simply * the current pointer... - * * @returns an Input context or NULL in case or error */ static void * @@ -130,10 +127,9 @@ found: } /** - * @param context the read context - * * Close the huge: query handler * + * @param context the read context * @returns 0 or -1 in case of error */ static int @@ -161,12 +157,11 @@ size_t curlen = 0; size_t dotlen; /** + * Implement an huge: query read. + * * @param context the read context * @param buffer where to store data * @param len number of bytes to read - * - * Implement an huge: query read. - * * @returns the number of bytes read or -1 in case of error */ static int @@ -248,10 +243,9 @@ foo\ "; /** - * @param URI an URI to test - * * Check for a crazy: query * + * @param URI an URI to test * @returns 1 if yes and 0 if another Input module should be used */ static int @@ -263,10 +257,8 @@ crazyMatch(const char * URI) { /** * @param URI an URI to test - * * @returns a pointer to the crazy: query handler, in this example simply * the current pointer... - * * @returns an Input context or NULL in case or error */ static void * @@ -284,10 +276,9 @@ crazyOpen(const char * URI) { } /** - * @param context the read context - * * Close the crazy: query handler * + * @param context the read context * @returns 0 or -1 in case of error */ static int @@ -298,12 +289,11 @@ crazyClose(void * context) { /** + * Implement an crazy: query read. + * * @param context the read context * @param buffer where to store data * @param len number of bytes to read - * - * Implement an crazy: query read. - * * @returns the number of bytes read or -1 in case of error */ static int @@ -397,10 +387,9 @@ initializeLibxml2(void) { unsigned long callbacks = 0; /** - * @param ctxt An XML parser context - * * Is this document tagged standalone ? * + * @param ctxt An XML parser context * @returns 1 if true */ static int @@ -411,10 +400,9 @@ isStandaloneCallback(void *ctx ATTRIBUTE_UNUSED) } /** - * @param ctxt An XML parser context - * * Does this document has an internal subset * + * @param ctxt An XML parser context * @returns 1 if true */ static int @@ -425,10 +413,9 @@ hasInternalSubsetCallback(void *ctx ATTRIBUTE_UNUSED) } /** - * @param ctxt An XML parser context - * * Does this document has an external subset * + * @param ctxt An XML parser context * @returns 1 if true */ static int @@ -439,9 +426,9 @@ hasExternalSubsetCallback(void *ctx ATTRIBUTE_UNUSED) } /** - * @param ctxt An XML parser context - * * Does this document has an internal subset + * + * @param ctxt An XML parser context */ static void internalSubsetCallback(void *ctx ATTRIBUTE_UNUSED, @@ -453,9 +440,9 @@ internalSubsetCallback(void *ctx ATTRIBUTE_UNUSED, } /** - * @param ctxt An XML parser context - * * Does this document has an external subset + * + * @param ctxt An XML parser context */ static void externalSubsetCallback(void *ctx ATTRIBUTE_UNUSED, @@ -467,16 +454,15 @@ externalSubsetCallback(void *ctx ATTRIBUTE_UNUSED, } /** - * @param ctxt An XML parser context - * @param publicId The public ID of the entity - * @param systemId The system ID of the entity - * * Special entity resolver, better left to the parser, it has * more context than the application layer. * The default behaviour is to NOT resolve the entities, in that case * the ENTITY_REF nodes are built in the structure (and the parameter * values). * + * @param ctxt An XML parser context + * @param publicId The public ID of the entity + * @param systemId The system ID of the entity * @returns the xmlParserInputPtr if inlined or NULL for DOM behaviour. */ static xmlParserInputPtr @@ -489,11 +475,10 @@ resolveEntityCallback(void *ctx ATTRIBUTE_UNUSED, } /** - * @param ctxt An XML parser context - * @param name The entity name - * * Get an entity by name * + * @param ctxt An XML parser context + * @param name The entity name * @returns the xmlParserInputPtr if inlined or NULL for DOM behaviour. */ static xmlEntityPtr @@ -505,11 +490,10 @@ getEntityCallback(void *ctx ATTRIBUTE_UNUSED, } /** - * @param ctxt An XML parser context - * @param name The entity name - * * Get a parameter entity by name * + * @param ctxt An XML parser context + * @param name The entity name * @returns the xmlParserInputPtr */ static xmlEntityPtr @@ -522,14 +506,14 @@ getParameterEntityCallback(void *ctx ATTRIBUTE_UNUSED, /** + * An entity definition has been parsed + * * @param ctxt An XML parser context * @param name the entity name * @param type the entity type * @param publicId The public ID of the entity * @param systemId The system ID of the entity * @param content the entity value (without processing). - * - * An entity definition has been parsed */ static void entityDeclCallback(void *ctx ATTRIBUTE_UNUSED, @@ -543,11 +527,11 @@ entityDeclCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * An attribute definition has been parsed + * * @param ctxt An XML parser context * @param name the attribute name * @param type the attribute type - * - * An attribute definition has been parsed */ static void attributeDeclCallback(void *ctx ATTRIBUTE_UNUSED, @@ -561,12 +545,12 @@ attributeDeclCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * An element definition has been parsed + * * @param ctxt An XML parser context * @param name the element name * @param type the element type * @param content the element value (without processing). - * - * An element definition has been parsed */ static void elementDeclCallback(void *ctx ATTRIBUTE_UNUSED, @@ -578,12 +562,12 @@ elementDeclCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * What to do when a notation declaration has been parsed. + * * @param ctxt An XML parser context * @param name The name of the notation * @param publicId The public ID of the entity * @param systemId The system ID of the entity - * - * What to do when a notation declaration has been parsed. */ static void notationDeclCallback(void *ctx ATTRIBUTE_UNUSED, @@ -595,13 +579,13 @@ notationDeclCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * What to do when an unparsed entity declaration is parsed + * * @param ctxt An XML parser context * @param name The name of the entity * @param publicId The public ID of the entity * @param systemId The system ID of the entity * @param notationName the name of the notation - * - * What to do when an unparsed entity declaration is parsed */ static void unparsedEntityDeclCallback(void *ctx ATTRIBUTE_UNUSED, @@ -614,11 +598,11 @@ unparsedEntityDeclCallback(void *ctx ATTRIBUTE_UNUSED, } /** - * @param ctxt An XML parser context - * @param 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. + * + * @param ctxt An XML parser context + * @param loc A SAX Locator */ static void setDocumentLocatorCallback(void *ctx ATTRIBUTE_UNUSED, @@ -628,9 +612,9 @@ setDocumentLocatorCallback(void *ctx ATTRIBUTE_UNUSED, } /** - * @param ctxt An XML parser context - * * called when the document start being processed. + * + * @param ctxt An XML parser context */ static void startDocumentCallback(void *ctx ATTRIBUTE_UNUSED) @@ -639,9 +623,9 @@ startDocumentCallback(void *ctx ATTRIBUTE_UNUSED) } /** - * @param ctxt An XML parser context - * * called when the document end has been detected. + * + * @param ctxt An XML parser context */ static void endDocumentCallback(void *ctx ATTRIBUTE_UNUSED) @@ -651,10 +635,10 @@ endDocumentCallback(void *ctx ATTRIBUTE_UNUSED) #if 0 /** + * called when an opening tag has been processed. + * * @param ctxt An XML parser context * @param name The element name - * - * called when an opening tag has been processed. */ static void startElementCallback(void *ctx ATTRIBUTE_UNUSED, @@ -666,10 +650,10 @@ startElementCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * called when the end of an element has been detected. + * * @param ctxt An XML parser context * @param name The element name - * - * called when the end of an element has been detected. */ static void endElementCallback(void *ctx ATTRIBUTE_UNUSED, @@ -681,12 +665,12 @@ endElementCallback(void *ctx ATTRIBUTE_UNUSED, #endif /** + * receiving some chars from the parser. + * Question: how much at a time ??? + * * @param ctxt An XML parser context * @param ch a xmlChar string * @param len the number of xmlChar - * - * receiving some chars from the parser. - * Question: how much at a time ??? */ static void charactersCallback(void *ctx ATTRIBUTE_UNUSED, @@ -697,10 +681,10 @@ charactersCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * called when an entity reference is detected. + * * @param ctxt An XML parser context * @param name The entity name - * - * called when an entity reference is detected. */ static void referenceCallback(void *ctx ATTRIBUTE_UNUSED, @@ -710,13 +694,13 @@ referenceCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * receiving some ignorable whitespaces from the parser. + * Question: how much at a time ??? + * * @param ctxt An XML parser context * @param ch a xmlChar string * @param start the first char in the string * @param len the number of xmlChar - * - * receiving some ignorable whitespaces from the parser. - * Question: how much at a time ??? */ static void ignorableWhitespaceCallback(void *ctx ATTRIBUTE_UNUSED, @@ -727,12 +711,12 @@ ignorableWhitespaceCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * A processing instruction has been parsed. + * * @param ctxt An XML parser context * @param target the target name * @param data the PI data's * @param len the number of xmlChar - * - * A processing instruction has been parsed. */ static void processingInstructionCallback(void *ctx ATTRIBUTE_UNUSED, @@ -743,11 +727,11 @@ processingInstructionCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * called when a pcdata block has been parsed + * * @param ctx the user data (XML parser context) * @param value The pcdata content * @param len the block length - * - * called when a pcdata block has been parsed */ static void cdataBlockCallback(void *ctx ATTRIBUTE_UNUSED, @@ -758,10 +742,10 @@ cdataBlockCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * A comment has been parsed. + * * @param ctxt An XML parser context * @param value the comment content - * - * A comment has been parsed. */ static void commentCallback(void *ctx ATTRIBUTE_UNUSED, @@ -771,12 +755,13 @@ commentCallback(void *ctx ATTRIBUTE_UNUSED, } /** - * @param ctxt An XML parser context - * @param msg the message to display/transmit - * @...: extra parameters for the message display - * * Display and format a warning messages, gives file, line, position and * extra parameters. + * + * @...: extra parameters for the message display + * + * @param ctxt An XML parser context + * @param msg the message to display/transmit */ static void warningCallback(void *ctx ATTRIBUTE_UNUSED, @@ -786,12 +771,13 @@ warningCallback(void *ctx ATTRIBUTE_UNUSED, } /** - * @param ctxt An XML parser context - * @param msg the message to display/transmit - * @...: extra parameters for the message display - * * Display and format a error messages, gives file, line, position and * extra parameters. + * + * @...: extra parameters for the message display + * + * @param ctxt An XML parser context + * @param msg the message to display/transmit */ static void errorCallback(void *ctx ATTRIBUTE_UNUSED, const char *msg ATTRIBUTE_UNUSED, @@ -801,12 +787,13 @@ errorCallback(void *ctx ATTRIBUTE_UNUSED, const char *msg ATTRIBUTE_UNUSED, } /** - * @param ctxt An XML parser context - * @param msg the message to display/transmit - * @...: extra parameters for the message display - * * Display and format a fatalError messages, gives file, line, position and * extra parameters. + * + * @...: extra parameters for the message display + * + * @param ctxt An XML parser context + * @param msg the message to display/transmit */ static void fatalErrorCallback(void *ctx ATTRIBUTE_UNUSED, @@ -820,10 +807,10 @@ fatalErrorCallback(void *ctx ATTRIBUTE_UNUSED, */ /** + * called when an opening tag has been processed. + * * @param ctxt An XML parser context * @param name The element name - * - * called when an opening tag has been processed. */ static void startElementNsCallback(void *ctx ATTRIBUTE_UNUSED, @@ -840,10 +827,10 @@ startElementNsCallback(void *ctx ATTRIBUTE_UNUSED, } /** + * called when the end of an element has been detected. + * * @param ctxt An XML parser context * @param name The element name - * - * called when the end of an element has been detected. */ static void endElementNsCallback(void *ctx ATTRIBUTE_UNUSED, @@ -898,13 +885,12 @@ static xmlSAXHandlerPtr callbackSAX2Handler = &callbackSAX2HandlerStruct; ************************************************************************/ /** + * Parse a memory generated file using SAX + * * @param filename the file to parse * @param max_size size of the limit to test * @param options parsing options * @param fail should a failure be reported - * - * Parse a memory generated file using SAX - * * @returns 0 in case of success, an error code otherwise */ static int @@ -949,13 +935,12 @@ saxTest(const char *filename, size_t limit, int options, int fail) { } #ifdef LIBXML_READER_ENABLED /** + * Parse a memory generated file using the xmlReader + * * @param filename the file to parse * @param max_size size of the limit to test * @param options parsing options * @param fail should a failure be reported - * - * Parse a memory generated file using the xmlReader - * * @returns 0 in case of success, an error code otherwise */ static int diff --git a/testrecurse.c b/testrecurse.c index 6861ac11..01ff5543 100644 --- a/testrecurse.c +++ b/testrecurse.c @@ -244,10 +244,9 @@ static const char *current; static int rlen; /** - * @param URI an URI to test - * * Check for a huge query * + * @param URI an URI to test * @returns 1 if yes and 0 if another Input module should be used */ static int @@ -267,10 +266,8 @@ hugeMatch(const char * URI) { /** * @param URI an URI to test - * * @returns a pointer to the huge query handler, in this example simply * the current pointer... - * * @returns an Input context or NULL in case or error */ static void * @@ -294,10 +291,9 @@ hugeOpen(const char * URI) { } /** - * @param context the read context - * * Close the huge query handler * + * @param context the read context * @returns 0 or -1 in case of error */ static int @@ -309,12 +305,11 @@ hugeClose(void * context) { #define MAX_NODES 1000 /** + * Implement an huge query read. + * * @param context the read context * @param buffer where to store data * @param len number of bytes to read - * - * Implement an huge query read. - * * @returns the number of bytes read or -1 in case of error */ static int @@ -462,13 +457,12 @@ static int checkTestFile(const char *filename) { * * ************************************************************************/ /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages: unused - * * Parse a file loading DTD and replacing entities check it fails for * lol cases * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages: unused * @returns 0 in case of success, an error code otherwise */ static int @@ -509,13 +503,12 @@ recursiveDetectTest(const char *filename, } /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages: unused - * * Parse a file loading DTD and replacing entities check it works for * good cases * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages: unused * @returns 0 in case of success, an error code otherwise */ static int @@ -551,13 +544,12 @@ notRecursiveDetectTest(const char *filename, } /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages: unused - * * Parse a memory generated file * good cases * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages: unused * @returns 0 in case of success, an error code otherwise */ static int @@ -652,13 +644,12 @@ notRecursiveHugeTest(const char *filename ATTRIBUTE_UNUSED, } /** - * @param filename the file to parse - * @param result the file with expected result - * @param err the file with error messages: unused - * * Parse a memory generated file * good cases * + * @param filename the file to parse + * @param result the file with expected result + * @param err the file with error messages: unused * @returns 0 in case of success, an error code otherwise */ static int diff --git a/threads.c b/threads.c index bcb29e22..8410168d 100644 --- a/threads.c +++ b/threads.c @@ -48,9 +48,9 @@ static xmlRMutex xmlLibraryLock; /** - * @param mutex the mutex - * * Initialize a mutex. + * + * @param mutex the mutex */ void xmlInitMutex(xmlMutexPtr mutex) @@ -83,9 +83,9 @@ xmlNewMutex(void) } /** - * @param mutex the simple mutex - * * Reclaim resources associated with a mutex. + * + * @param mutex the simple mutex */ void xmlCleanupMutex(xmlMutexPtr mutex) @@ -100,9 +100,9 @@ xmlCleanupMutex(xmlMutexPtr mutex) } /** - * @param tok the simple mutex - * * Free a mutex. + * + * @param tok the simple mutex */ void xmlFreeMutex(xmlMutexPtr tok) @@ -115,9 +115,9 @@ xmlFreeMutex(xmlMutexPtr tok) } /** - * @param tok the simple mutex - * * xmlMutexLock() is used to lock a libxml2 token. + * + * @param tok the simple mutex */ void xmlMutexLock(xmlMutexPtr tok) @@ -137,9 +137,9 @@ xmlMutexLock(xmlMutexPtr tok) } /** - * @param tok the simple mutex - * * xmlMutexUnlock() is used to unlock a libxml2 token. + * + * @param tok the simple mutex */ void xmlMutexUnlock(xmlMutexPtr tok) @@ -154,9 +154,9 @@ xmlMutexUnlock(xmlMutexPtr tok) } /** - * @param tok mutex - * * Initialize the mutex. + * + * @param tok mutex */ void xmlInitRMutex(xmlRMutexPtr tok) { @@ -193,9 +193,9 @@ xmlNewRMutex(void) } /** - * @param tok mutex - * * Cleanup the mutex. + * + * @param tok mutex */ void xmlCleanupRMutex(xmlRMutexPtr tok) { @@ -210,10 +210,10 @@ xmlCleanupRMutex(xmlRMutexPtr tok) { } /** - * @param tok the reentrant mutex - * * xmlRFreeMutex() is used to reclaim resources associated with a * reentrant mutex. + * + * @param tok the reentrant mutex */ void xmlFreeRMutex(xmlRMutexPtr tok) @@ -225,9 +225,9 @@ xmlFreeRMutex(xmlRMutexPtr tok) } /** - * @param tok the reentrant mutex - * * xmlRMutexLock() is used to lock a libxml2 token_r. + * + * @param tok the reentrant mutex */ void xmlRMutexLock(xmlRMutexPtr tok) @@ -257,9 +257,9 @@ xmlRMutexLock(xmlRMutexPtr tok) } /** - * @param tok the reentrant mutex - * * xmlRMutexUnlock() is used to unlock a libxml2 token_r. + * + * @param tok the reentrant mutex */ void xmlRMutexUnlock(xmlRMutexPtr tok ATTRIBUTE_UNUSED) diff --git a/tree.c b/tree.c index 68c2160c..83d5efbf 100644 --- a/tree.c +++ b/tree.c @@ -103,12 +103,11 @@ static int xmlCompressMode = 0; #include /** + * Do an entity lookup in the DTD entity hash table and + * * @param dtd A pointer to the DTD to search * @param name The entity name - * - * Do an entity lookup in the DTD entity hash table and * @returns the corresponding entity, if found. - * * @returns A pointer to the entity structure or NULL if not found. */ static xmlEntityPtr @@ -123,12 +122,11 @@ xmlGetEntityFromDtd(const xmlDtd *dtd, const xmlChar *name) { return(NULL); } /** + * Do an entity lookup in the DTD parameter entity hash table and + * * @param dtd A pointer to the DTD to search * @param name The entity name - * - * Do an entity lookup in the DTD parameter entity hash table and * @returns the corresponding entity, if found. - * * @returns A pointer to the entity structure or NULL if not found. */ static xmlEntityPtr @@ -150,15 +148,14 @@ xmlGetParameterEntityFromDtd(const xmlDtd *dtd, const xmlChar *name) { ************************************************************************/ /** - * @param ncname the Name - * @param prefix the prefix - * @param memory preallocated memory - * @param len preallocated memory length - * * Builds the QName `prefix:ncname` in `memory` if there is enough space * and prefix is not NULL nor empty, otherwise allocate a new string. * If prefix is NULL or empty it returns ncname. * + * @param ncname the Name + * @param prefix the prefix + * @param memory preallocated memory + * @param len preallocated memory length * @returns the new string which must be freed by the caller if different from * `memory` and `ncname` or NULL in case of error */ @@ -195,19 +192,18 @@ xmlBuildQName(const xmlChar *ncname, const xmlChar *prefix, } /** - * @param name the full QName - * @param prefix a xmlChar ** + * parse an XML qualified name string * * @deprecated This function doesn't report malloc failures. * - * parse an XML qualified name string - * * [NS 5] QName ::= (Prefix ':')? LocalPart * * [NS 6] Prefix ::= NCName * * [NS 7] LocalPart ::= NCName * + * @param name the full QName + * @param prefix a xmlChar ** * @returns NULL if the name doesn't have a prefix. Otherwise, returns the * local part, and prefix is updated to get the Prefix. Both the return value * and the prefix must be freed by the caller. @@ -251,11 +247,10 @@ xmlSplitQName2(const xmlChar *name, xmlChar **prefix) { } /** - * @param name the full QName - * @param len an int * - * * parse an XML qualified name string * + * @param name the full QName + * @param len an int * * @returns NULL if it is not a Qualified Name, otherwise, update len * with the length in byte of the prefix and return a pointer * to the start of the name without the prefix @@ -288,14 +283,13 @@ xmlSplitQName3(const xmlChar *name, int *len) { } /** - * @param name the full QName - * @param prefixPtr pointer to resulting prefix - * * Parse a QName. The return value points to the start of the local * name in the input string. If the QName has a prefix, it will be * allocated and stored in `prefixPtr`. This string must be freed by * the caller. If there's no prefix, `prefixPtr` is set to NULL. * + * @param name the full QName + * @param prefixPtr pointer to resulting prefix * @returns the local name or NULL if a memory allocation failed. */ const xmlChar * @@ -342,11 +336,10 @@ xmlSplitQName4(const xmlChar *name, xmlChar **prefixPtr) { #define CUR_SCHAR(s, l) xmlStringCurrentChar(NULL, s, &l) /** - * @param value the value to check - * @param space allow spaces in front and end of the string - * * Check that a value conforms to the lexical space of NCName * + * @param value the value to check + * @param space allow spaces in front and end of the string * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -413,11 +406,10 @@ try_complex: } /** - * @param value the value to check - * @param space allow spaces in front and end of the string - * * Check that a value conforms to the lexical space of QName * + * @param value the value to check + * @param space allow spaces in front and end of the string * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -510,11 +502,10 @@ try_complex: } /** - * @param value the value to check - * @param space allow spaces in front and end of the string - * * Check that a value conforms to the lexical space of Name * + * @param value the value to check + * @param space allow spaces in front and end of the string * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -578,11 +569,10 @@ try_complex: } /** - * @param value the value to check - * @param space allow spaces in front and end of the string - * * Check that a value conforms to the lexical space of NMToken * + * @param value the value to check + * @param space allow spaces in front and end of the string * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -655,10 +645,6 @@ try_complex: ************************************************************************/ /** - * @param node the element carrying the namespace (optional) - * @param href the URI associated - * @param prefix the prefix for the namespace (optional) - * * Create a new namespace. For a default namespace, `prefix` should be * NULL. The namespace URI in `href` is not checked. You should make sure * to pass a valid URI. @@ -668,6 +654,9 @@ try_complex: * the node already has a definition for the prefix or default * namespace. * + * @param node the element carrying the namespace (optional) + * @param href the URI associated + * @param prefix the prefix for the namespace (optional) * @returns a new namespace pointer or NULL if arguments are invalid, * the prefix is already in use or a memory allocation failed. */ @@ -728,11 +717,11 @@ error: } /** - * @param node a node in the document - * @param ns a namespace pointer (optional) - * * Set the namespace of an element or attribute node. Passing a NULL * namespace unsets the namespace. + * + * @param node a node in the document + * @param ns a namespace pointer (optional) */ void xmlSetNs(xmlNodePtr node, xmlNsPtr ns) { @@ -745,9 +734,9 @@ xmlSetNs(xmlNodePtr node, xmlNsPtr ns) { } /** - * @param cur the namespace pointer - * * Free an xmlNs object. + * + * @param cur the namespace pointer */ void xmlFreeNs(xmlNsPtr cur) { @@ -760,9 +749,9 @@ xmlFreeNs(xmlNsPtr cur) { } /** - * @param cur the first namespace pointer - * * Free a list of xmlNs objects. + * + * @param cur the first namespace pointer */ void xmlFreeNsList(xmlNsPtr cur) { @@ -778,11 +767,6 @@ xmlFreeNsList(xmlNsPtr cur) { } /** - * @param doc the document pointer (optional) - * @param name the DTD name (optional) - * @param ExternalID the external ID (optional) - * @param SystemID the system ID (optional) - * * Create a DTD node. * * If a document is provided, it is an error if it already has an @@ -791,6 +775,10 @@ xmlFreeNsList(xmlNsPtr cur) { * * To create an internal subset, use xmlCreateIntSubset(). * + * @param doc the document pointer (optional) + * @param name the DTD name (optional) + * @param ExternalID the external ID (optional) + * @param SystemID the system ID (optional) * @returns a pointer to the new DTD object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -841,10 +829,9 @@ error: } /** - * @param doc the document pointer - * * Get the internal subset of a document. * + * @param doc the document pointer * @returns a pointer to the DTD object or NULL if not found. */ xmlDtdPtr @@ -863,11 +850,6 @@ xmlGetIntSubset(const xmlDoc *doc) { } /** - * @param doc the document pointer (optional) - * @param name the DTD name (optional) - * @param ExternalID the external (PUBLIC) ID (optional) - * @param SystemID the system ID (optional) - * * Create a DTD node. * * If a document is provided and it already has an internal subset, @@ -875,6 +857,10 @@ xmlGetIntSubset(const xmlDoc *doc) { * If the document has no internal subset, it will be set to the * created DTD. * + * @param doc the document pointer (optional) + * @param name the DTD name (optional) + * @param ExternalID the external (PUBLIC) ID (optional) + * @param SystemID the system ID (optional) * @returns a pointer to the new or existing DTD object or NULL if * arguments are invalid or a memory allocation failed. */ @@ -962,10 +948,10 @@ error: } /** - * @param str a string - * * Free a string if it is not owned by the "dict" dictionary in the * current scope + * + * @param str a string */ #define DICT_FREE(str) \ if ((str) && ((!dict) || \ @@ -973,9 +959,9 @@ error: xmlFree((char *)(str)); /** - * @param cur the DTD structure to free up - * * Free a DTD structure. + * + * @param cur the DTD structure to free up */ void xmlFreeDtd(xmlDtdPtr cur) { @@ -1027,10 +1013,9 @@ xmlFreeDtd(xmlDtdPtr cur) { } /** - * @param version XML version string like `"1.0"` (optional) - * * Creates a new XML document. If version is NULL, `"1.0"` is used. * + * @param version XML version string like `"1.0"` (optional) * @returns a new document or NULL if a memory allocation failed. */ xmlDocPtr @@ -1072,9 +1057,9 @@ xmlNewDoc(const xmlChar *version) { } /** - * @param cur pointer to the document - * * Free a document including all children and associated DTDs. + * + * @param cur pointer to the document */ void xmlFreeDoc(xmlDocPtr cur) { @@ -1124,14 +1109,13 @@ xmlFreeDoc(xmlDocPtr cur) { } /** + * See xmlNodeParseContent(). + * * @param doc a document (optional) * @param parent an element or attribute (optional) * @param value an attribute value * @param len maximum length of the attribute value * @param listPtr pointer to the resulting node list (optional) - * - * See xmlNodeParseContent(). - * * @returns 0 on success, -1 if a memory allocation failed. */ static int @@ -1389,10 +1373,6 @@ out: } /** - * @param node an element or attribute - * @param content text content with XML references - * @param len maximum length of content - * * Parse content and replace the node's children with the resulting * node list. * @@ -1402,6 +1382,9 @@ out: * Only references are handled, nested elements, comments or PIs are * not. * + * @param node an element or attribute + * @param content text content with XML references + * @param len maximum length of content * @returns 0 on success, -1 if a memory allocation failed. */ int @@ -1410,14 +1393,13 @@ xmlNodeParseContent(xmlNodePtr node, const xmlChar *content, int len) { } /** - * @param doc a document (optional) - * @param value an attribute value - * @param len maximum length of the attribute value + * See xmlStringGetNodeList(). * * @deprecated Use xmlNodeSetContentLen(). * - * See xmlStringGetNodeList(). - * + * @param doc a document (optional) + * @param value an attribute value + * @param len maximum length of the attribute value * @returns a pointer to the first child or NULL if the value if empty * or a memory allocation failed. */ @@ -1430,20 +1412,19 @@ xmlStringLenGetNodeList(const xmlDoc *doc, const xmlChar *value, int len) { } /** - * @param doc a document (optional) - * @param value an attribute value - * - * @deprecated Use xmlNodeSetContent(). - * * Parse an attribute value and build a node list containing only * text and entity reference nodes. The resulting nodes will be * associated with the document if provided. The document is also * used to look up entities. * + * @deprecated Use xmlNodeSetContent(). + * * The input is not validated. Syntax errors or references to * undeclared entities will be ignored silently with unspecified * results. * + * @param doc a document (optional) + * @param value an attribute value * @returns a pointer to the first child or NULL if the value if empty * or a memory allocation failed. */ @@ -1459,7 +1440,6 @@ xmlStringGetNodeList(const xmlDoc *doc, const xmlChar *value) { * @param doc a document (optional) * @param node a node list * @param escMode escape mode (0 = no, 1 = elem, 2 = attr, 3 = raw) - * * @returns a pointer to the string. */ static xmlChar * @@ -1529,10 +1509,6 @@ error: } /** - * @param doc a document (optional) - * @param list a node list of attribute children - * @param inLine whether entity references are substituted - * * Serializes attribute children (text and entity reference nodes) * into a string. * @@ -1541,6 +1517,9 @@ error: * like `&` as well as non-ASCII chars will be escaped. See * xmlNodeListGetRawString() for an alternative option. * + * @param doc a document (optional) + * @param list a node list of attribute children + * @param inLine whether entity references are substituted * @returns a string or NULL if a memory allocation failed. */ xmlChar * @@ -1566,10 +1545,6 @@ xmlNodeListGetString(xmlDocPtr doc, const xmlNode *list, int inLine) } /** - * @param doc a document (optional) - * @param list a node list of attribute children - * @param inLine whether entity references are substituted - * * Serializes attribute children (text and entity reference nodes) * into a string. * @@ -1577,6 +1552,9 @@ xmlNodeListGetString(xmlDocPtr doc, const xmlNode *list, int inLine) * Otherwise, entity references will be kept and special characters * like `&` will be escaped. * + * @param doc a document (optional) + * @param list a node list of attribute children + * @param inLine whether entity references are substituted * @returns a string or NULL if a memory allocation failed. */ xmlChar * @@ -1690,10 +1668,6 @@ error: } /** - * @param node the parent node (optional) - * @param name the name of the attribute - * @param value the value of the attribute (optional) - * * Create an attribute node. * * If provided, `value` should be a raw, unescaped string. @@ -1702,6 +1676,9 @@ error: * checking for duplicate names. It is an error if `node` is not an * element. * + * @param node the parent node (optional) + * @param name the name of the attribute + * @param value the value of the attribute (optional) * @returns a pointer to the attribute or NULL if arguments are invalid * or a memory allocation failed. */ @@ -1716,11 +1693,6 @@ xmlNewProp(xmlNodePtr node, const xmlChar *name, const xmlChar *value) { } /** - * @param node the parent node (optional) - * @param ns the namespace (optional) - * @param name the local name of the attribute - * @param value the value of the attribute (optional) - * * Create an attribute object. * * If provided, `value` should be a raw, unescaped string. @@ -1729,6 +1701,10 @@ xmlNewProp(xmlNodePtr node, const xmlChar *name, const xmlChar *value) { * checking for duplicate names. It is an error if `node` is not an * element. * + * @param node the parent node (optional) + * @param ns the namespace (optional) + * @param name the local name of the attribute + * @param value the value of the attribute (optional) * @returns a pointer to the attribute or NULL if arguments are invalid * or a memory allocation failed. */ @@ -1744,15 +1720,14 @@ xmlNewNsProp(xmlNodePtr node, xmlNsPtr ns, const xmlChar *name, } /** - * @param node the parent node (optional) - * @param ns the namespace (optional) - * @param name the local name of the attribute - * @param value the value of the attribute (optional) - * * Like xmlNewNsProp(), but the `name` string will be used directly * without making a copy. Takes ownership of `name` which will also * be freed on error. * + * @param node the parent node (optional) + * @param ns the namespace (optional) + * @param name the local name of the attribute + * @param value the value of the attribute (optional) * @returns a pointer to the attribute or NULL if arguments are invalid * or a memory allocation failed. */ @@ -1768,10 +1743,6 @@ xmlNewNsPropEatName(xmlNodePtr node, xmlNsPtr ns, xmlChar *name, } /** - * @param doc the target document (optional) - * @param name the name of the attribute - * @param value attribute value with XML references (optional) - * * Create an attribute object. * * If provided, `value` is expected to be a valid XML attribute value @@ -1779,6 +1750,9 @@ xmlNewNsPropEatName(xmlNodePtr node, xmlNsPtr ns, xmlChar *name, * and references to undeclared entities are ignored silently. * If you want to pass a raw string, see xmlNewProp(). * + * @param doc the target document (optional) + * @param name the name of the attribute + * @param value attribute value with XML references (optional) * @returns a pointer to the attribute or NULL if arguments are invalid * or a memory allocation failed. */ @@ -1821,9 +1795,9 @@ error: } /** - * @param cur the first attribute in the list - * * Free an attribute list including all children. + * + * @param cur the first attribute in the list */ void xmlFreePropList(xmlAttrPtr cur) { @@ -1837,9 +1811,9 @@ xmlFreePropList(xmlAttrPtr cur) { } /** - * @param cur an attribute - * * Free an attribute including all children. + * + * @param cur an attribute */ void xmlFreeProp(xmlAttrPtr cur) { @@ -1861,14 +1835,13 @@ xmlFreeProp(xmlAttrPtr cur) { } /** - * @param cur an attribute - * * Unlink and free an attribute including all children. * * Note this doesn't work for namespace declarations. * * The attribute must have a non-NULL parent pointer. * + * @param cur an attribute * @returns 0 on success or -1 if the attribute was not found or * arguments are invalid. */ @@ -1903,12 +1876,11 @@ xmlRemoveProp(xmlAttrPtr cur) { } /** + * Create a processing instruction object. + * * @param doc the target document (optional) * @param name the processing instruction target * @param content the PI content (optional) - * - * Create a processing instruction object. - * * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -1952,13 +1924,12 @@ error: } /** - * @param name the processing instruction target - * @param content the PI content (optional) - * * Create a processing instruction node. * * Use of this function is DISCOURAGED in favor of xmlNewDocPI(). * + * @param name the processing instruction target + * @param content the PI content (optional) * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -1968,13 +1939,12 @@ xmlNewPI(const xmlChar *name, const xmlChar *content) { } /** - * @param ns namespace (optional) - * @param name the node name - * * Create an element node. * * Use of this function is DISCOURAGED in favor of xmlNewDocNode(). * + * @param ns namespace (optional) + * @param name the node name * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -1984,9 +1954,6 @@ xmlNewNode(xmlNsPtr ns, const xmlChar *name) { } /** - * @param ns namespace (optional) - * @param name the node name - * * Create an element node. * * Use of this function is DISCOURAGED in favor of xmlNewDocNodeEatName(). @@ -1995,6 +1962,8 @@ xmlNewNode(xmlNsPtr ns, const xmlChar *name) { * without making a copy. Takes ownership of `name` which will also * be freed on error. * + * @param ns namespace (optional) + * @param name the node name * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -2033,11 +2002,6 @@ xmlNewElem(xmlDocPtr doc, xmlNsPtr ns, const xmlChar *name, } /** - * @param doc the target document - * @param ns namespace (optional) - * @param name the node name - * @param content text content with XML references (optional) - * * Create an element node. * * If provided, `content` is expected to be a valid XML attribute value @@ -2054,6 +2018,10 @@ xmlNewElem(xmlDocPtr doc, xmlNsPtr ns, const xmlChar *name, * tree. Note that a document only owns nodes reachable from the root * node. Unlinked subtrees must be freed manually. * + * @param doc the target document + * @param ns namespace (optional) + * @param name the node name + * @param content text content with XML references (optional) * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -2088,17 +2056,16 @@ xmlNewDocNode(xmlDocPtr doc, xmlNsPtr ns, } /** - * @param doc the target document - * @param ns namespace (optional) - * @param name the node name - * @param content text content with XML references (optional) - * * Create an element node. * * Like xmlNewDocNode(), but the `name` string will be used directly * without making a copy. Takes ownership of `name` which will also * be freed on error. * + * @param doc the target document + * @param ns namespace (optional) + * @param name the node name + * @param content text content with XML references (optional) * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -2124,15 +2091,14 @@ xmlNewDocNodeEatName(xmlDocPtr doc, xmlNsPtr ns, } /** - * @param doc the target document - * @param ns namespace (optional) - * @param name the node name - * @param content raw text content (optional) - * * Create an element node. * * If provided, `value` should be a raw, unescaped string. * + * @param doc the target document + * @param ns namespace (optional) + * @param name the node name + * @param content raw text content (optional) * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -2162,10 +2128,9 @@ xmlNewDocRawNode(xmlDocPtr doc, xmlNsPtr ns, } /** - * @param doc the target document (optional) - * * Create a document fragment node. * + * @param doc the target document (optional) * @returns a pointer to the new node object or NULL if a memory * allocation failed. */ @@ -2190,12 +2155,11 @@ xmlNewDocFragment(xmlDocPtr doc) { } /** - * @param content raw text content (optional) - * * Create a text node. * * Use of this function is DISCOURAGED in favor of xmlNewDocText(). * + * @param content raw text content (optional) * @returns a pointer to the new node object or NULL if a memory * allocation failed. */ @@ -2229,11 +2193,6 @@ error: } /** - * @param parent the parent node - * @param ns a namespace (optional) - * @param name the name of the child - * @param content raw text content of the child (optional) - * * Create a new child element and append it to a parent element. * * If `ns` is NULL, the newly created element inherits the namespace @@ -2242,6 +2201,10 @@ error: * If `content` is provided, a text node will be added to the child * element, see xmlNewDocRawNode(). * + * @param parent the parent node + * @param ns a namespace (optional) + * @param name the name of the child + * @param content raw text content of the child (optional) * @returns a pointer to the new node object or NULL if arguments * are invalid or a memory allocation failed. */ @@ -2290,14 +2253,13 @@ xmlNewTextChild(xmlNodePtr parent, xmlNsPtr ns, } /** - * @param doc the target document (optional) - * @param name the entity name - * * Create an empty entity reference node. This function doesn't attempt * to look up the entity in `doc`. * * `name` is consumed. * + * @param doc the target document (optional) + * @param name the entity name * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -2325,9 +2287,6 @@ xmlNewEntityRef(xmlDocPtr doc, xmlChar *name) { } /** - * @param doc the target document (optional) - * @param name the entity name - * * This function is MISNAMED. It doesn't create a character reference * but an entity reference. * @@ -2336,6 +2295,8 @@ xmlNewEntityRef(xmlDocPtr doc, xmlChar *name) { * * Entity names like `&entity;` are handled as well. * + * @param doc the target document (optional) + * @param name the entity name * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -2363,14 +2324,13 @@ xmlNewCharRef(xmlDocPtr doc, const xmlChar *name) { } /** - * @param doc the target document (optional) - * @param name the entity name - * * Create a new entity reference node, linking the result with the * entity in `doc` if found. * * Entity names like `&entity;` are handled as well. * + * @param doc the target document (optional) + * @param name the entity name * @returns a pointer to the new node object or NULL if arguments are * invalid or a memory allocation failed. */ @@ -2427,11 +2387,10 @@ error: } /** - * @param doc the target document - * @param content raw text content (optional) - * * Create a new text node. * + * @param doc the target document + * @param content raw text content (optional) * @returns a pointer to the new node object or NULL if a memory * allocation failed. */ @@ -2445,11 +2404,10 @@ xmlNewDocText(const xmlDoc *doc, const xmlChar *content) { } /** - * @param content raw text content (optional) - * @param len size of text content - * * Use of this function is DISCOURAGED in favor of xmlNewDocTextLen(). * + * @param content raw text content (optional) + * @param len size of text content * @returns a pointer to the new node object or NULL if a memory * allocation failed. */ @@ -2481,12 +2439,11 @@ xmlNewTextLen(const xmlChar *content, int len) { } /** + * Create a new text node. + * * @param doc the target document * @param content raw text content (optional) * @param len size of text content - * - * Create a new text node. - * * @returns a pointer to the new node object or NULL if a memory * allocation failed. */ @@ -2500,12 +2457,11 @@ xmlNewDocTextLen(xmlDocPtr doc, const xmlChar *content, int len) { } /** - * @param content the comment content (optional) - * * Use of this function is DISCOURAGED in favor of xmlNewDocComment(). * * Create a comment node. * + * @param content the comment content (optional) * @returns a pointer to the new node object or NULL if a memory * allocation failed. */ @@ -2539,12 +2495,11 @@ error: } /** + * Create a CDATA section node. + * * @param doc the target document (optional) * @param content raw text content (optional) * @param len size of text content - * - * Create a CDATA section node. - * * @returns a pointer to the new node object or NULL if a memory * allocation failed. */ @@ -2576,11 +2531,10 @@ xmlNewCDataBlock(xmlDocPtr doc, const xmlChar *content, int len) { } /** - * @param doc the document - * @param content the comment content - * * Create a comment node. * + * @param doc the document + * @param content the comment content * @returns a pointer to the new node object or NULL if a memory * allocation failed. */ @@ -2740,9 +2694,6 @@ xmlNodeSetDoc(xmlNodePtr node, xmlDocPtr doc) { } /** - * @param tree root of a subtree - * @param doc new document - * * This is an internal function which shouldn't be used. It is * invoked by functions like xmlAddChild(), xmlAddSibling() or * xmlReplaceNode(). `tree` must be the root node of an unlinked @@ -2753,6 +2704,8 @@ xmlNodeSetDoc(xmlNodePtr node, xmlDocPtr doc) { * Also copy strings from the old document's dictionary and * remove ID attributes from the old ID table. * + * @param tree root of a subtree + * @param doc new document * @returns 0 on success. If a memory allocation fails, returns -1. * The whole tree will be updated on failure but some strings * may be lost. @@ -2795,13 +2748,12 @@ xmlSetTreeDoc(xmlNodePtr tree, xmlDocPtr doc) { } /** - * @param list a node list - * @param doc new document - * * Associate all subtrees in `list` with a new document. * * Internal function, see xmlSetTreeDoc(). * + * @param list a node list + * @param doc new document * @returns 0 on success. If a memory allocation fails, returns -1. * All subtrees will be updated on failure but some strings * may be lost. @@ -2827,11 +2779,6 @@ xmlSetListDoc(xmlNodePtr list, xmlDocPtr doc) { } /** - * @param parent the parent node - * @param ns a namespace (optional) - * @param name the name of the child - * @param content text content with XML references (optional) - * * Create a new child element and append it to a parent element. * * If `ns` is NULL, the newly created element inherits the namespace @@ -2842,6 +2789,10 @@ xmlSetListDoc(xmlNodePtr list, xmlDocPtr doc) { * and entity reference node will be added to the child element, * see xmlNewDocNode(). * + * @param parent the parent node + * @param ns a namespace (optional) + * @param name the name of the child + * @param content text content with XML references (optional) * @returns a pointer to the new node object or NULL if arguments * are invalid or a memory allocation failed. */ @@ -3050,9 +3001,6 @@ xmlInsertNode(xmlDocPtr doc, xmlNodePtr cur, xmlNodePtr parent, } /** - * @param prev the target node - * @param cur the new node - * * Unlinks `cur` and inserts it as next sibling after `prev`. * * Unlike xmlAddChild() this function does not merge text nodes. @@ -3063,6 +3011,8 @@ xmlInsertNode(xmlDocPtr doc, xmlNodePtr cur, xmlNodePtr parent, * * See the notes in xmlAddChild(). * + * @param prev the target node + * @param cur the new node * @returns `cur` or a sibling if `cur` was merged. Returns NULL * if arguments are invalid or a memory allocation failed. */ @@ -3080,9 +3030,6 @@ xmlAddNextSibling(xmlNodePtr prev, xmlNodePtr cur) { } /** - * @param next the target node - * @param cur the new node - * * Unlinks `cur` and inserts it as previous sibling before `next`. * * Unlike xmlAddChild() this function does not merge text nodes. @@ -3093,6 +3040,8 @@ xmlAddNextSibling(xmlNodePtr prev, xmlNodePtr cur) { * * See the notes in xmlAddChild(). * + * @param next the target node + * @param cur the new node * @returns `cur` or a sibling if `cur` was merged. Returns NULL * if arguments are invalid or a memory allocation failed. */ @@ -3110,9 +3059,6 @@ xmlAddPrevSibling(xmlNodePtr next, xmlNodePtr cur) { } /** - * @param node the target node - * @param cur the new node - * * Unlinks `cur` and inserts it as last sibling of `node`. * * If `cur` is a text node, it may be merged with an adjacent text @@ -3125,6 +3071,8 @@ xmlAddPrevSibling(xmlNodePtr next, xmlNodePtr cur) { * * See the notes in xmlAddChild(). * + * @param node the target node + * @param cur the new node * @returns `cur` or a sibling if `cur` was merged. Returns NULL * if arguments are invalid or a memory allocation failed. */ @@ -3154,13 +3102,12 @@ xmlAddSibling(xmlNodePtr node, xmlNodePtr cur) { } /** - * @param parent the parent node - * @param cur the first node in the list - * * Append a node list to another node. * * See xmlAddChild(). * + * @param parent the parent node + * @param cur the first node in the list * @returns the last child or NULL in case of error. */ xmlNodePtr @@ -3230,9 +3177,6 @@ xmlAddChildList(xmlNodePtr parent, xmlNodePtr cur) { } /** - * @param parent the parent node - * @param cur the child node - * * Unlink `cur` and append it to the children of `parent`. * * If `cur` is a text node, it may be merged with an adjacent text @@ -3268,6 +3212,8 @@ xmlAddChildList(xmlNodePtr parent, xmlNodePtr cur) { * * Moving DTDs between documents isn't supported. * + * @param parent the parent node + * @param cur the child node * @returns `cur` or a sibling if `cur` was merged. Returns NULL * if arguments are invalid or a memory allocation failed. */ @@ -3308,10 +3254,9 @@ xmlAddChild(xmlNodePtr parent, xmlNodePtr cur) { } /** - * @param parent the parent node - * * Find the last child of a node. * + * @param parent the parent node * @returns the last child or NULL if parent has no children. */ xmlNodePtr @@ -3327,12 +3272,11 @@ xmlGetLastChild(const xmlNode *parent) { */ /** - * @param parent the parent node - * * Count the number of child nodes which are elements. * * Note that entity references are not expanded. * + * @param parent the parent node * @returns the number of element children or 0 if arguments are * invalid. */ @@ -3363,12 +3307,11 @@ xmlChildElementCount(xmlNodePtr parent) { } /** - * @param parent the parent node - * * Find the first child node which is an element. * * Note that entity references are not expanded. * + * @param parent the parent node * @returns the first element or NULL if parent has no children. */ xmlNodePtr @@ -3397,12 +3340,11 @@ xmlFirstElementChild(xmlNodePtr parent) { } /** - * @param parent the parent node - * * Find the last child node which is an element. * * Note that entity references are not expanded. * + * @param parent the parent node * @returns the last element or NULL if parent has no children. */ xmlNodePtr @@ -3431,12 +3373,11 @@ xmlLastElementChild(xmlNodePtr parent) { } /** - * @param node the current node - * * Find the closest preceding sibling which is a element. * * Note that entity references are not expanded. * + * @param node the current node * @returns the sibling or NULL if no sibling was found. */ xmlNodePtr @@ -3466,12 +3407,11 @@ xmlPreviousElementSibling(xmlNodePtr node) { } /** - * @param node the current node - * * Find the closest following sibling which is a element. * * Note that entity references are not expanded. * + * @param node the current node * @returns the sibling or NULL if no sibling was found. */ xmlNodePtr @@ -3502,9 +3442,9 @@ xmlNextElementSibling(xmlNodePtr node) { } /** - * @param cur the first node in the list - * * Free a node list including all children. + * + * @param cur the first node in the list */ void xmlFreeNodeList(xmlNodePtr cur) { @@ -3589,12 +3529,11 @@ xmlFreeNodeList(xmlNodePtr cur) { } /** - * @param cur the node - * * Free a node including all the children. * * This doesn't unlink the node from the tree. Call xmlUnlinkNode() first * unless `cur` is a root node. + * @param cur the node */ void xmlFreeNode(xmlNodePtr cur) { @@ -3656,12 +3595,11 @@ xmlFreeNode(xmlNodePtr cur) { } /** - * @param cur the node - * * Unlink a node from its tree. * * This function only unlinks the node from the tree. It doesn't * clear references to DTD nodes. + * @param cur the node */ static void xmlUnlinkNodeInternal(xmlNodePtr cur) { @@ -3689,12 +3627,11 @@ xmlUnlinkNodeInternal(xmlNodePtr cur) { } /** - * @param cur the node - * * Unlink a node from its tree. * * The node is not freed. Unless it is reinserted, it must be managed * manually and freed eventually by calling xmlFreeNode(). + * @param cur the node */ void xmlUnlinkNode(xmlNodePtr cur) { @@ -3722,9 +3659,6 @@ xmlUnlinkNode(xmlNodePtr cur) { } /** - * @param old the old node - * @param cur the node (optional) - * * Unlink the old node. If `cur` is provided, it is unlinked and * inserted in place of `old`. * @@ -3735,6 +3669,8 @@ xmlUnlinkNode(xmlNodePtr cur) { * * See the notes in xmlAddChild(). * + * @param old the old node + * @param cur the node (optional) * @returns `old` or NULL if arguments are invalid or a memory * allocation failed. */ @@ -3789,10 +3725,9 @@ xmlReplaceNode(xmlNodePtr old, xmlNodePtr cur) { ************************************************************************/ /** - * @param cur the namespace - * * Copy a namespace. * + * @param cur the namespace * @returns the copied namespace or NULL if a memory allocation * failed. */ @@ -3812,10 +3747,9 @@ xmlCopyNamespace(xmlNsPtr cur) { } /** - * @param cur the first namespace - * * Copy a namespace list. * + * @param cur the first namespace * @returns the head of the copied list or NULL if a memory * allocation failed. */ @@ -3962,15 +3896,14 @@ error: } /** - * @param target the element where the attribute will be grafted - * @param cur the attribute - * * Create a copy of the attribute. This function sets the parent * pointer of the copy to `target` but doesn't set the attribute on * the target element. Users should consider to set the attribute * by calling xmlAddChild() afterwards or reset the parent pointer to * NULL. * + * @param target the element where the attribute will be grafted + * @param cur the attribute * @returns the copied attribute or NULL if a memory allocation * failed. */ @@ -3980,13 +3913,12 @@ xmlCopyProp(xmlNodePtr target, xmlAttrPtr cur) { } /** - * @param target the element where the attributes will be grafted - * @param cur the first attribute - * * Create a copy of an attribute list. This function sets the * parent pointers of the copied attributes to `target` but doesn't * set the attributes on the target element. * + * @param target the element where the attributes will be grafted + * @param cur the first attribute * @returns the head of the copied list or NULL if a memory * allocation failed. */ @@ -4035,13 +3967,12 @@ xmlCopyPropList(xmlNodePtr target, xmlAttrPtr cur) { */ /** + * Copy a node. + * * @param node source node * @param doc target document * @param parent target parent * @param extended flags - * - * Copy a node. - * * @returns the copy or NULL if a memory allocation failed. */ xmlNodePtr @@ -4229,14 +4160,13 @@ error: } /** - * @param node node to copy - * @param doc target document - * @param parent target node (optional) - * * Copy a node list. If `parent` is provided, sets the parent pointer * of the copied nodes, but doesn't update the children and last * pointer of `parent`. * + * @param node node to copy + * @param doc target document + * @param parent target node (optional) * @returns a the copy or NULL in case of error. */ xmlNodePtr @@ -4314,9 +4244,6 @@ error: } /** - * @param node the node - * @param extended mode of operation - * * Copy a node. * * If `extended` is 0, make a shallow copy. @@ -4329,6 +4256,8 @@ error: * * Use of this function is DISCOURAGED in favor of xmlDocCopyNode(). * + * @param node the node + * @param extended mode of operation * @returns the copied node or NULL if a memory allocation failed. */ xmlNodePtr @@ -4340,10 +4269,6 @@ xmlCopyNode(xmlNodePtr node, int extended) { } /** - * @param node the node - * @param doc the document - * @param extended mode of operation - * * Copy a node into another document. * * If `extended` is 0, make a shallow copy. @@ -4354,6 +4279,9 @@ xmlCopyNode(xmlNodePtr node, int extended) { * If `extended` is 2, make a shallow copy including properties and * namespaces of elements. * + * @param node the node + * @param doc the document + * @param extended mode of operation * @returns the copied node or NULL if a memory allocation failed. */ xmlNodePtr @@ -4365,11 +4293,10 @@ xmlDocCopyNode(xmlNodePtr node, xmlDocPtr doc, int extended) { } /** - * @param doc the target document - * @param node the first node in the list. - * * Copy a node list and all children into a new document. * + * @param doc the target document + * @param node the first node in the list. * @returns the head of the copied list or NULL if a memory * allocation failed. */ @@ -4379,12 +4306,11 @@ xmlNodePtr xmlDocCopyNodeList(xmlDocPtr doc, xmlNodePtr node) { } /** - * @param node the first node in the list. - * * Copy a node list and all children. * * Use of this function is DISCOURAGED in favor of xmlDocCopyNodeList(). * + * @param node the first node in the list. * @returns the head of the copied list or NULL if a memory * allocation failed. */ @@ -4394,10 +4320,9 @@ xmlNodePtr xmlCopyNodeList(xmlNodePtr node) { } /** - * @param dtd the DTD - * * Copy a DTD. * + * @param dtd the DTD * @returns the copied DTD or NULL if a memory allocation failed. */ xmlDtdPtr @@ -4499,12 +4424,11 @@ error: } /** - * @param doc the document - * @param recursive if not zero do a recursive copy. - * * Copy a document. If recursive, the content tree will * be copied too as well as DTD, namespaces and entities. * + * @param doc the document + * @param recursive if not zero do a recursive copy. * @returns the copied document or NULL if a memory allocation * failed. */ @@ -4579,13 +4503,12 @@ error: ************************************************************************/ /** - * @param node valid node - * @param depth used to limit any risk of recursion - * * Get line number of `node`. Try to work around the limitation of * line numbers being stored as 16 bits ints. Requires xmlParserOption * XML_PARSE_BIG_LINES to be set when parsing. * + * @param node valid node + * @param depth used to limit any risk of recursion * @returns the line number if successful, -1 otherwise */ static long @@ -4629,12 +4552,11 @@ xmlGetLineNoInternal(const xmlNode *node, int depth) } /** - * @param node valid node - * * Get line number of `node`. Try to work around the limitation of * line numbers being stored as 16 bits ints. Requires xmlParserOption * XML_PARSE_BIG_LINES to be set when parsing. * + * @param node valid node * @returns the line number if successful, -1 otherwise */ long @@ -4644,10 +4566,9 @@ xmlGetLineNo(const xmlNode *node) } /** - * @param node a node - * * Build a structure based Path for the given node * + * @param node a node * @returns the new path or NULL in case of error. The caller must free * the returned string */ @@ -4898,11 +4819,10 @@ xmlGetNodePath(const xmlNode *node) } /** - * @param doc the document - * * Get the root element of the document (`doc->children` is a list * containing possibly comments, PIs, etc ...). * + * @param doc the document * @returns the root element or NULL if no element was found. */ xmlNodePtr @@ -4920,9 +4840,6 @@ xmlDocGetRootElement(const xmlDoc *doc) { } /** - * @param doc the document - * @param root the new document root element - * * If `root` is NULL no action is taken. To remove a node from a * document, use xmlUnlinkNode() instead. * @@ -4931,6 +4848,8 @@ xmlDocGetRootElement(const xmlDoc *doc) { * * `root` must be an element node. It is unlinked before insertion. * + * @param doc the document + * @param root the new document root element * @returns the unlinked old root element or NULL if the document * didn't have a root element or a memory allocation failed. */ @@ -4967,12 +4886,11 @@ xmlDocSetRootElement(xmlDocPtr doc, xmlNodePtr root) { } /** - * @param cur the node being changed - * @param lang the language description - * * Set the language of a node, i.e. the values of the `xml:lang` * attribute. * + * @param cur the node being changed + * @param lang the language description * @returns 0 on success, 1 if arguments are invalid, -1 if a * memory allocation failed. */ @@ -4996,11 +4914,10 @@ xmlNodeSetLang(xmlNodePtr cur, const xmlChar *lang) { } /** - * @param cur the node being checked - * * Searches the language of a node, i.e. the values of the `xml:lang` * attribute or the one carried by the nearest ancestor. * + * @param cur the node being checked * @returns a pointer to the lang value, or NULL if not found * It's up to the caller to free the memory with xmlFree(). */ @@ -5028,12 +4945,11 @@ xmlNodeGetLang(const xmlNode *cur) { /** - * @param cur the node being changed - * @param val the xml:space value ("0": default, 1: "preserve") - * * Set (or reset) the space preserving behaviour of a node, i.e. the * value of the `xml:space` attribute. * + * @param cur the node being changed + * @param val the xml:space value ("0": default, 1: "preserve") * @returns 0 on success, 1 if arguments are invalid, -1 if a * memory allocation failed. */ @@ -5064,12 +4980,11 @@ xmlNodeSetSpacePreserve(xmlNodePtr cur, int val) { } /** - * @param cur the node being checked - * * Searches the space preserving behaviour of a node, i.e. the values * of the `xml:space` attribute or the one carried by the nearest * ancestor. * + * @param cur the node being checked * @returns -1 if xml:space is not inherited, 0 if "default", 1 if "preserve" */ int @@ -5104,10 +5019,10 @@ xmlNodeGetSpacePreserve(const xmlNode *cur) { } /** + * Set (or reset) the name of a node. + * * @param cur the node being changed * @param name the new tag name - * - * Set (or reset) the name of a node. */ void xmlNodeSetName(xmlNodePtr cur, const xmlChar *name) { @@ -5149,12 +5064,11 @@ xmlNodeSetName(xmlNodePtr cur, const xmlChar *name) { } /** - * @param cur the node being changed - * @param uri the new base URI - * * Set (or reset) the base URI of a node, i.e. the value of the * `xml:base` attribute. * + * @param cur the node being changed + * @param uri the new base URI * @returns 0 on success, -1 on error. */ int @@ -5203,10 +5117,6 @@ xmlNodeSetBase(xmlNodePtr cur, const xmlChar* uri) { } /** - * @param doc the document the node pertains to - * @param cur the node being checked - * @param baseOut pointer to base - * * Searches for the base URI. The code should work on both XML * and HTML document even if base mechanisms are completely different. * It returns the base as defined in RFC 2396 sections "5.1.1. Base @@ -5216,6 +5126,9 @@ xmlNodeSetBase(xmlNodePtr cur, const xmlChar* uri) { * * @since 2.13.0 * + * @param doc the document the node pertains to + * @param cur the node being checked + * @param baseOut pointer to base * @returns 0 in case of success, 1 if a URI or argument is invalid, -1 if a * memory allocation failed. */ @@ -5320,12 +5233,11 @@ found: } /** - * @param doc the document the node pertains to - * @param cur the node being checked - * * See xmlNodeGetBaseSafe(). This function doesn't allow to distinguish * memory allocation failures from a non-existing base. * + * @param doc the document the node pertains to + * @param cur the node being checked * @returns a pointer to the base URL, or NULL if not found * It's up to the caller to free the memory with xmlFree(). */ @@ -5338,9 +5250,6 @@ xmlNodeGetBase(const xmlDoc *doc, const xmlNode *cur) { } /** - * @param buffer a buffer - * @param cur the node being read - * * Append the string value of a node to `buffer`. For text nodes, * the string value is the text content. Otherwise, the string value * is the concatenation of the string values of the node's @@ -5348,6 +5257,8 @@ xmlNodeGetBase(const xmlDoc *doc, const xmlNode *cur) { * * Entity references are substituted. * + * @param buffer a buffer + * @param cur the node being read * @returns 0 in case of success and -1 in case of error. */ int @@ -5429,9 +5340,6 @@ xmlBufGetChildContent(xmlBufPtr buf, const xmlNode *tree) { } /** - * @param buf a buffer xmlBufPtr - * @param cur the node being read - * * Append the string value of a node to `buf`. For text nodes, * the string value is the text content. Otherwise, the string value * is the concatenation of the string values of the node's @@ -5439,6 +5347,8 @@ xmlBufGetChildContent(xmlBufPtr buf, const xmlNode *tree) { * * Entity references are substituted. * + * @param buf a buffer xmlBufPtr + * @param cur the node being read * @returns 0 in case of success and -1 in case of error. */ int @@ -5480,8 +5390,6 @@ xmlBufGetNodeContent(xmlBufPtr buf, const xmlNode *cur) } /** - * @param cur the node being read - * * Returns the string value of a node. For text nodes, the string * value is the text content. Otherwise, the string value is the * concatenation of the string values of the node's descendants. @@ -5490,6 +5398,7 @@ xmlBufGetNodeContent(xmlBufPtr buf, const xmlNode *cur) * * It's up to the caller to free the result with xmlFree(). * + * @param cur the node being read * @returns a new string or NULL if arguments are invalid or a * memory allocation failed. */ @@ -5595,9 +5504,6 @@ xmlNodeSetContentInternal(xmlNodePtr cur, const xmlChar *content, int len) { } /** - * @param cur the node being modified - * @param content the new value of the content - * * Replace the text content of a node. * * Sets the raw text content of text, CDATA, comment or PI nodes. @@ -5614,6 +5520,8 @@ xmlNodeSetContentInternal(xmlNodePtr cur, const xmlChar *content, int len) { * `xmlNodeAddContent(node, content)`. Unlike this function, * xmlNodeAddContent() accepts raw text. * + * @param cur the node being modified + * @param content the new value of the content * @returns 0 on success, 1 on error, -1 if a memory allocation failed. */ int @@ -5622,12 +5530,11 @@ xmlNodeSetContent(xmlNodePtr cur, const xmlChar *content) { } /** + * See xmlNodeSetContent(). + * * @param cur the node being modified * @param content the new value of the content * @param len the size of `content` - * - * See xmlNodeSetContent(). - * * @returns 0 on success, 1 on error, -1 if a memory allocation failed. */ int @@ -5636,16 +5543,15 @@ xmlNodeSetContentLen(xmlNodePtr cur, const xmlChar *content, int len) { } /** - * @param cur the node being modified - * @param content extra content - * @param len the size of `content` - * * Append the extra substring to the node content. * * NOTE: In contrast to xmlNodeSetContentLen(), `content` is supposed * to be raw text, so unescaped XML special chars are allowed, entity * references are not supported. * + * @param cur the node being modified + * @param content extra content + * @param len the size of `content` * @returns 0 on success, 1 on error, -1 if a memory allocation failed. */ int @@ -5685,15 +5591,14 @@ xmlNodeAddContentLen(xmlNodePtr cur, const xmlChar *content, int len) { } /** - * @param cur the node being modified - * @param content extra content - * * Append the extra substring to the node content. * * NOTE: In contrast to xmlNodeSetContent(), `content` is supposed * to be raw text, so unescaped XML special chars are allowed, entity * references are not supported. * + * @param cur the node being modified + * @param content extra content * @returns 0 on success, 1 on error, -1 if a memory allocation failed. */ int @@ -5702,13 +5607,12 @@ xmlNodeAddContent(xmlNodePtr cur, const xmlChar *content) { } /** - * @param first the first text node - * @param second the second text node being merged - * * Merge the second text node into the first. If `first` is NULL, * `second` is returned. Otherwise, the second node is unlinked and * freed. * + * @param first the first text node + * @param second the second text node being merged * @returns the first text node augmented or NULL in case of error. */ xmlNodePtr @@ -5733,16 +5637,15 @@ xmlTextMerge(xmlNodePtr first, xmlNodePtr second) { } /** - * @param doc the document - * @param node the current node - * @param out the returned namespace array - * * Find all in-scope namespaces of a node. `out` returns a NULL * terminated array of namespace pointers that must be freed by * the caller. * * @since 2.13.0 * + * @param doc the document + * @param node the current node + * @param out the returned namespace array * @returns 0 on success, 1 if no namespaces were found, -1 if a * memory allocation failed. */ @@ -5810,13 +5713,12 @@ xmlGetNsListSafe(const xmlDoc *doc ATTRIBUTE_UNUSED, const xmlNode *node, } /** - * @param doc the document - * @param node the current node - * * Find all in-scope namespaces of a node. * * Use xmlGetNsListSafe() for better error reporting. * + * @param doc the document + * @param node the current node * @returns a NULL terminated array of namespace pointers that must * be freed by the caller or NULL if no namespaces were found or * a memory allocation failed. @@ -5877,12 +5779,11 @@ xmlTreeEnsureXMLDecl(xmlDocPtr doc) } /** + * Search a namespace with `prefix` in scope of `node`. + * * @param node a node * @param prefix a namespace prefix * @param out pointer to resulting namespace - * - * Search a namespace with `prefix` in scope of `node`. - * * @returns 0 on success, -1 if a memory allocation failed, 1 on * other errors. */ @@ -5959,10 +5860,6 @@ xmlSearchNsSafe(xmlNodePtr node, const xmlChar *prefix, } /** - * @param doc the document - * @param node the current node - * @param nameSpace the namespace prefix - * * Search for a namespace registered under a given prefix for a document. * Recurse on the parents until it finds the defined namespace * or return NULL otherwise. @@ -5971,6 +5868,9 @@ xmlSearchNsSafe(xmlNodePtr node, const xmlChar *prefix, * * Namespace search doesn't cross entity boundaries. * + * @param doc the document + * @param node the current node + * @param nameSpace the namespace prefix * @returns the namespace pointer or NULL if no namespace was found or * a memory allocation failed. Allocations can only fail if the `xml` * namespace is queried. @@ -5985,14 +5885,13 @@ xmlSearchNs(xmlDocPtr doc ATTRIBUTE_UNUSED, xmlNodePtr node, } /** + * Verify that the given namespace held on `ancestor` is still in scope + * on node. + * * @param doc the document * @param node the current node * @param ancestor the ancestor carrying the namespace * @param prefix the namespace prefix - * - * Verify that the given namespace held on `ancestor` is still in scope - * on node. - * * @returns 1 if true, 0 if false and -1 in case of error. */ static int @@ -6026,12 +5925,11 @@ xmlNsInScope(xmlDocPtr doc ATTRIBUTE_UNUSED, xmlNodePtr node, } /** + * Search for a namespace matching `URI` in scope of `node`. + * * @param node a node * @param href a namespace URI * @param out pointer to resulting namespace - * - * Search for a namespace matching `URI` in scope of `node`. - * * @returns 0 on success, -1 if a memory allocation failed, 1 on * other errors. */ @@ -6117,13 +6015,12 @@ xmlSearchNsByHrefSafe(xmlNodePtr node, const xmlChar *href, } /** - * @param doc the document - * @param node the current node - * @param href the namespace value - * * Search for a namespace aliasing a given URI. Recurse on the parents * until the namespace is found or return NULL otherwise. * + * @param doc the document + * @param node the current node + * @param href the namespace value * @returns the namespace pointer or NULL if no namespace was found or * a memory allocation failed. Allocations can only fail if the `xml` * namespace is queried. @@ -6138,15 +6035,14 @@ xmlSearchNsByHref(xmlDocPtr doc ATTRIBUTE_UNUSED, xmlNodePtr node, } /** - * @param tree a node expected to hold the new namespace - * @param ns the original namespace - * * This function tries to locate a namespace definition in a tree * ancestors, or create a new namespace definition node similar to * `ns` trying to reuse the same prefix. However if the given prefix is * null (default namespace) or reused within the subtree defined by * `tree` or on one of its ancestors then a new prefix is generated. * + * @param tree a node expected to hold the new namespace + * @param ns the original namespace * @returns the (new) namespace definition or NULL in case of error */ static xmlNsPtr @@ -6226,9 +6122,6 @@ xmlGrowNsCache(xmlNsCache **cache, int *capacity) { } /** - * @param doc the document - * @param tree a node defining the subtree to reconciliate - * * This function checks that all the namespaces declared within the given * tree are properly declared. This is needed for example after copy or cut * and then paste operations. The subtree may still hold pointers to @@ -6237,6 +6130,8 @@ xmlGrowNsCache(xmlNsCache **cache, int *capacity) { * the new environment. If not possible the new namespaces are redeclared * on `tree` at the top of the given subtree. * + * @param doc the document + * @param tree a node defining the subtree to reconciliate * @returns 0 on success or -1 in case of error. */ int @@ -6502,14 +6397,13 @@ xmlGetPropNodeValueInternal(const xmlAttr *prop) } /** - * @param node the element - * @param name the attribute name - * * Search for an attribute of an element. * * This function also looks in DTD attribute declaration for \#FIXED or * default declaration values. * + * @param node the element + * @param name the attribute name * @returns the attribute or the attribute declaration or NULL if * neither was found. Also returns NULL if a memory allocation failed, * making this function unreliable. @@ -6553,10 +6447,6 @@ xmlHasProp(const xmlNode *node, const xmlChar *name) { } /** - * @param node the element - * @param name the attribute name - * @param nameSpace the URI of the namespace - * * Search for an attribute of an element. * * The attribute has to match the specified namespace. A namespace of @@ -6565,6 +6455,9 @@ xmlHasProp(const xmlNode *node, const xmlChar *name) { * This function also looks in DTD attribute declaration for \#FIXED or * default declaration values. * + * @param node the element + * @param name the attribute name + * @param nameSpace the URI of the namespace * @returns the attribute or the attribute declaration or NULL if * neither was found. Also returns NULL if a memory allocation failed * making this function unreliable. @@ -6576,11 +6469,6 @@ xmlHasNsProp(const xmlNode *node, const xmlChar *name, const xmlChar *nameSpace) } /** - * @param node the element - * @param name the attribute name - * @param nsUri the URI of the namespace - * @param out the returned string - * * Look up the value of an element's attribute. * * The attribute has to match the specified namespace. A namespace of @@ -6591,6 +6479,10 @@ xmlHasNsProp(const xmlNode *node, const xmlChar *name, const xmlChar *nameSpace) * * @since 2.13.0 * + * @param node the element + * @param name the attribute name + * @param nsUri the URI of the namespace + * @param out the returned string * @returns 0 on success, 1 if no attribute was found, -1 if a * memory allocation failed. */ @@ -6614,9 +6506,6 @@ xmlNodeGetAttrValue(const xmlNode *node, const xmlChar *name, } /** - * @param node the element - * @param name the attribute name - * * Look up the value of an element's attribute. * * Entities are substituted. The returned value must be freed by the @@ -6631,6 +6520,8 @@ xmlNodeGetAttrValue(const xmlNode *node, const xmlChar *name, * NOTE: This function doesn't allow to distinguish malloc failures from * missing attributes. * + * @param node the element + * @param name the attribute name * @returns the attribute value or NULL if not found or a memory allocation * failed. */ @@ -6645,9 +6536,6 @@ xmlGetProp(const xmlNode *node, const xmlChar *name) { } /** - * @param node the element - * @param name the attribute name - * * Look up the value of an element's attribute. * * Entities are substituted. The returned value must be freed by the @@ -6662,6 +6550,8 @@ xmlGetProp(const xmlNode *node, const xmlChar *name) { * NOTE: This function doesn't allow to distinguish malloc failures from * missing attributes. It's more robust to use xmlNodeGetAttrValue(). * + * @param node the element + * @param name the attribute name * @returns the attribute value or NULL if not found or a memory allocation * failed. */ @@ -6676,10 +6566,6 @@ xmlGetNoNsProp(const xmlNode *node, const xmlChar *name) { } /** - * @param node the element - * @param name the attribute name - * @param nameSpace the URI of the namespace - * * Look up the value of an element's attribute. * * The attribute has to match the specified namespace. A namespace of @@ -6694,6 +6580,9 @@ xmlGetNoNsProp(const xmlNode *node, const xmlChar *name) { * NOTE: This function doesn't allow to distinguish malloc failures from * missing attributes. It's more robust to use xmlNodeGetAttrValue(). * + * @param node the element + * @param name the attribute name + * @param nameSpace the URI of the namespace * @returns the attribute value or NULL if not found or a memory allocation * failed. */ @@ -6708,12 +6597,11 @@ xmlGetNsProp(const xmlNode *node, const xmlChar *name, const xmlChar *nameSpace) } /** - * @param node the element - * @param name the attribute name - * * Remove an attribute of an element. * This handles only attributes in no namespace. * + * @param node the element + * @param name the attribute name * @returns 0 if successful, -1 if not found */ int @@ -6729,12 +6617,11 @@ xmlUnsetProp(xmlNodePtr node, const xmlChar *name) { } /** + * Remove an attribute of an element. + * * @param node the element * @param ns the namespace definition * @param name the attribute name - * - * Remove an attribute of an element. - * * @returns 0 if successful, -1 if not found */ int @@ -6751,14 +6638,13 @@ xmlUnsetNsProp(xmlNodePtr node, xmlNsPtr ns, const xmlChar *name) { } /** - * @param node the node - * @param name the attribute name (a QName) - * @param value the attribute value - * * Set (or reset) an element's attribute. If `name` has a prefix, * the corresponding namespace will be used. It is an error if * there's no such binding for the prefix in scope. * + * @param node the node + * @param name the attribute name (a QName) + * @param value the attribute value * @returns the attribute pointer. */ xmlAttrPtr @@ -6791,15 +6677,14 @@ xmlSetProp(xmlNodePtr node, const xmlChar *name, const xmlChar *value) { } /** - * @param node the node - * @param ns the namespace definition - * @param name the attribute name - * @param value the attribute value - * * Set (or reset) an element's attribute. * * The namespace must be in scope. * + * @param node the node + * @param ns the namespace definition + * @param name the attribute name + * @param value the attribute value * @returns the attribute pointer. */ xmlAttrPtr @@ -6861,10 +6746,9 @@ xmlSetNsProp(xmlNodePtr node, xmlNsPtr ns, const xmlChar *name, } /** - * @param node the node - * * Check whether the node is a text node. * + * @param node the node * @returns 1 if yes, 0 if no */ int @@ -6876,11 +6760,10 @@ xmlNodeIsText(const xmlNode *node) { } /** - * @param node the node - * * Checks whether this node is an empty or whitespace-only * (and possibly ignorable) text node. * + * @param node the node * @returns 1 if yes, 0 if no */ int @@ -6902,14 +6785,13 @@ xmlIsBlankNode(const xmlNode *node) { } /** - * @param node the node - * @param content the content - * @param len `content` length - * * Concat the given string at the end of the existing node content. * * If `len` is -1, the string length will be calculated. * + * @param node the node + * @param content the content + * @param len `content` length * @returns -1 in case of error, 0 otherwise */ @@ -6928,10 +6810,9 @@ xmlTextConcat(xmlNodePtr node, const xmlChar *content, int len) { } /** - * @param doc the document - * * Get the compression level of a document, ZLIB based. * + * @param doc the document * @returns 0 (uncompressed) to 9 (max compression) */ int @@ -6941,12 +6822,11 @@ xmlGetDocCompressMode (const xmlDoc *doc) { } /** - * @param doc the document - * @param mode the compression ratio - * * Set the compression level of a document, ZLIB based. * * Correct values: 0 (uncompressed) to 9 (max compression) + * @param doc the document + * @param mode the compression ratio */ void xmlSetDocCompressMode (xmlDocPtr doc, int mode) { @@ -6957,10 +6837,10 @@ xmlSetDocCompressMode (xmlDocPtr doc, int mode) { } /** - * @deprecated Use xmlGetDocCompressMode() - * * Get the global compression level, ZLIB based. * + * @deprecated Use xmlGetDocCompressMode() + * * @returns 0 (uncompressed) to 9 (max compression) */ int @@ -6970,13 +6850,12 @@ xmlGetCompressMode(void) } /** - * @param mode the compression ratio + * Set the global compression level, ZLIB based. * * @deprecated Use xmlSetDocCompressMode() * - * Set the global compression level, ZLIB based. - * * Correct values: 0 (uncompressed) to 9 (max compression) + * @param mode the compression ratio */ void xmlSetCompressMode(int mode) { @@ -7028,9 +6907,9 @@ struct xmlNsMap { (m)->pool = i; /** - * @param nsmap the ns-map - * * Frees the ns-map + * + * @param nsmap the ns-map */ static void xmlDOMWrapNsMapFree(xmlNsMapPtr nsmap) @@ -7055,14 +6934,13 @@ xmlDOMWrapNsMapFree(xmlNsMapPtr nsmap) } /** + * Adds an ns-mapping item. + * * @param nsmap the ns-map * @param position position * @param oldNs the old ns-struct * @param newNs the new ns-struct * @param depth depth and ns-kind information - * - * Adds an ns-mapping item. - * * @returns the added item. */ static xmlNsMapItemPtr @@ -7136,13 +7014,12 @@ xmlDOMWrapNsMapAddItem(xmlNsMapPtr *nsmap, int position, } /** - * @param doc the doc - * @param nsName the namespace name - * @param prefix the prefix - * * Creates or reuses an xmlNs struct on doc->oldNs with * the given prefix and namespace name. * + * @param doc the doc + * @param nsName the namespace name + * @param prefix the prefix * @returns the acquired ns struct or NULL in case of an API * or internal error. */ @@ -7198,9 +7075,9 @@ xmlDOMWrapNewCtxt(void) } /** - * @param ctxt the DOM-wrapper context - * * Frees the DOM-wrapper context. + * + * @param ctxt the DOM-wrapper context */ void xmlDOMWrapFreeCtxt(xmlDOMWrapCtxtPtr ctxt) @@ -7216,11 +7093,10 @@ xmlDOMWrapFreeCtxt(xmlDOMWrapCtxtPtr ctxt) } /** - * @param nsList a list of ns-structs - * @param prefix the searched prefix - * * Searches for a ns-decl with the given prefix in `nsList`. * + * @param nsList a list of ns-structs + * @param prefix the searched prefix * @returns the ns-decl if found, NULL if not found and on * API errors. */ @@ -7244,11 +7120,10 @@ xmlTreeNSListLookupByPrefix(xmlNsPtr nsList, const xmlChar *prefix) } /** - * @param map the namespace map - * @param node the node to start with - * * Puts in-scope namespaces into the ns-map. * + * @param map the namespace map + * @param node the node to start with * @returns 0 on success, -1 on API or internal errors. */ static int @@ -7334,11 +7209,6 @@ xmlDOMWrapNSNormAddNsMapItem2(xmlNsPtr **list, int *size, int *number, } /** - * @param ctxt a DOM wrapper context - * @param doc the doc - * @param node the node to be removed. - * @param options set of options, unused at the moment - * * Unlinks the given node from its owner. * This will substitute ns-references to node->nsDef for * ns-references to doc->oldNs, thus ensuring the removed @@ -7346,6 +7216,10 @@ xmlDOMWrapNSNormAddNsMapItem2(xmlNsPtr **list, int *size, int *number, * * NOTE: This function was not intensively tested. * + * @param ctxt a DOM wrapper context + * @param doc the doc + * @param node the node to be removed. + * @param options set of options, unused at the moment * @returns 0 on success, 1 if the node is not supported, * -1 on API and internal errors. */ @@ -7472,16 +7346,15 @@ next_sibling: } /** + * Dynamically searches for a ns-declaration which matches + * the given `nsName` in the ancestor-or-self axis of `node`. + * * @param doc the document * @param node the start node * @param nsName the searched namespace name * @param retNs the resulting ns-decl * @param prefixed if the found ns-decl must have a prefix * (for attributes) - * - * Dynamically searches for a ns-declaration which matches - * the given `nsName` in the ancestor-or-self axis of `node`. - * * @returns 1 if a ns-decl was found, 0 if not and -1 on API * and internal errors. */ @@ -7574,14 +7447,13 @@ xmlSearchNsByNamespaceStrict(xmlDocPtr doc, xmlNodePtr node, } /** + * Dynamically searches for a ns-declaration which matches + * the given `nsName` in the ancestor-or-self axis of `node`. + * * @param doc the document * @param node the start node * @param prefix the searched namespace prefix * @param retNs the resulting ns-decl - * - * Dynamically searches for a ns-declaration which matches - * the given `nsName` in the ancestor-or-self axis of `node`. - * * @returns 1 if a ns-decl was found, 0 if not and -1 on API * and internal errors. */ @@ -7635,17 +7507,16 @@ xmlSearchNsByPrefixStrict(xmlDocPtr doc, xmlNodePtr node, } /** + * Declares a new namespace on `elem`. It tries to use the + * given `prefix`. If a ns-decl with the given prefix is already existent + * on `elem`, it will generate an other prefix. + * * @param doc the doc * @param elem the element-node to declare on * @param nsName the namespace-name of the ns-decl * @param prefix the preferred prefix of the ns-decl * @param checkShadow ensure that the new ns-decl doesn't shadow * ancestor ns-decls - * - * Declares a new namespace on `elem`. It tries to use the - * given `prefix`. If a ns-decl with the given prefix is already existent - * on `elem`, it will generate an other prefix. - * * @returns 1 if a ns-decl was found, 0 if not and -1 on API * and internal errors. */ @@ -7710,6 +7581,12 @@ ns_next_prefix: } /** + * Searches for a matching ns-name in the ns-decls of `nsMap`, if not + * found it will either declare it on `elem`, or store it in `doc->oldNs`. + * If a new ns-decl needs to be declared on `elem`, it tries to use the + * `ns->prefix` for it, if this prefix is already in use on `elem`, it will + * change the prefix or the new ns-decl. + * * @param doc the doc * @param elem the element-node to declare namespaces on * @param ns the ns-struct to use for the search @@ -7719,13 +7596,6 @@ ns_next_prefix: * @param ancestorsOnly search in ancestor ns-decls only * @param prefixed if the searched ns-decl must have a prefix * (for attributes) - * - * Searches for a matching ns-name in the ns-decls of `nsMap`, if not - * found it will either declare it on `elem`, or store it in `doc->oldNs`. - * If a new ns-decl needs to be declared on `elem`, it tries to use the - * `ns->prefix` for it, if this prefix is already in use on `elem`, it will - * change the prefix or the new ns-decl. - * * @returns 0 if succeeded, -1 otherwise and on API/internal errors. */ static int @@ -7852,10 +7722,6 @@ typedef enum { } xmlDOMReconcileNSOptions; /** - * @param ctxt DOM wrapper context, unused at the moment - * @param elem the element-node - * @param options option flags - * * Ensures that ns-references point to ns-decls hold on element-nodes. * Ensures that the tree is namespace wellformed by creating additional * ns-decls where needed. Note that, since prefixes of already existent @@ -7864,6 +7730,9 @@ typedef enum { * * NOTE: This function was not intensively tested. * + * @param ctxt DOM wrapper context, unused at the moment + * @param elem the element-node + * @param options option flags * @returns 0 if succeeded, -1 otherwise and on API/internal errors. */ int @@ -8105,13 +7974,6 @@ next_sibling: } /** - * @param ctxt the optional context for custom processing - * @param sourceDoc the optional sourceDoc - * @param node the element-node to start with - * @param destDoc the destination doc for adoption - * @param destParent the optional new parent of `node` in `destDoc` - * @param options option flags - * * Ensures that ns-references point to `destDoc`: either to * `elements->nsDef` entries if `destParent` is given, or to * `destDoc->oldNs` otherwise. @@ -8124,6 +7986,12 @@ next_sibling: * * NOTE: This function was not intensively tested. * + * @param ctxt the optional context for custom processing + * @param sourceDoc the optional sourceDoc + * @param node the element-node to start with + * @param destDoc the destination doc for adoption + * @param destParent the optional new parent of `node` in `destDoc` + * @param options option flags * @returns 0 if succeeded, -1 otherwise and on API/internal errors. */ static int @@ -8386,15 +8254,6 @@ leave_node: } /** - * @param ctxt the optional context for custom processing - * @param sourceDoc the optional sourceDoc - * @param node the node to start with - * @param resNode the clone of the given `node` - * @param destDoc the destination doc - * @param destParent the optional new parent of `node` in `destDoc` - * @param deep descend into child if set - * @param options option flags - * * References of out-of scope ns-decls are remapped to point to `destDoc`. * If `destParent` is given, then nsDef entries on element-nodes are used. * If *no* `destParent` is given, then `destDoc->oldNs` entries are used. @@ -8407,6 +8266,14 @@ leave_node: * shadowed by this process, it could break QNames in attribute * values or element content. * + * @param ctxt the optional context for custom processing + * @param sourceDoc the optional sourceDoc + * @param node the node to start with + * @param resNode the clone of the given `node` + * @param destDoc the destination doc + * @param destParent the optional new parent of `node` in `destDoc` + * @param deep descend into child if set + * @param options option flags * @returns 0 if the operation succeeded, * 1 if a node of unsupported (or not yet supported) type was given, * -1 on API/internal errors. @@ -8924,18 +8791,17 @@ exit: } /** + * `attr` is adopted by `destDoc`. + * Ensures that ns-references point to `destDoc`: either to + * `elements->nsDef` entries if `destParent` is given, or to + * `destDoc->oldNs` otherwise. + * * @param ctxt the optional context for custom processing * @param sourceDoc unused * @param attr the attribute-node to be adopted * @param destDoc the destination doc for adoption * @param destParent the optional new parent of `attr` in `destDoc` * @param options option flags (unused) - * - * `attr` is adopted by `destDoc`. - * Ensures that ns-references point to `destDoc`: either to - * `elements->nsDef` entries if `destParent` is given, or to - * `destDoc->oldNs` otherwise. - * * @returns 0 if succeeded, -1 otherwise and on API/internal errors. */ static int @@ -8991,13 +8857,6 @@ xmlDOMWrapAdoptAttr(xmlDOMWrapCtxtPtr ctxt, } /** - * @param ctxt the optional context for custom processing - * @param sourceDoc the optional sourceDoc - * @param node the node to start with - * @param destDoc the destination doc - * @param destParent the optional new parent of `node` in `destDoc` - * @param options option flags - * * References of out-of scope ns-decls are remapped to point to `destDoc`: * If `destParent` is given, then nsDef entries on element-nodes are used. * If *no* `destParent` is given, then `destDoc->oldNs` entries are used @@ -9012,6 +8871,12 @@ xmlDOMWrapAdoptAttr(xmlDOMWrapCtxtPtr ctxt, * * NOTE: This function was not intensively tested. * + * @param ctxt the optional context for custom processing + * @param sourceDoc the optional sourceDoc + * @param node the node to start with + * @param destDoc the destination doc + * @param destParent the optional new parent of `node` in `destDoc` + * @param options option flags * @returns 0 if the operation succeeded, * 1 if a node of unsupported type was given, * 2 if a node of not yet supported type was given and @@ -9102,11 +8967,10 @@ xmlDOMWrapAdoptNode(xmlDOMWrapCtxtPtr ctxt, "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" /** - * @param systemID the system identifier - * @param publicID the public identifier - * * Try to find if the document correspond to an XHTML DTD * + * @param systemID the system identifier + * @param publicID the public identifier * @returns 1 if true, 0 if not and -1 in case of error */ int @@ -9133,12 +8997,11 @@ xmlIsXHTML(const xmlChar *systemID, const xmlChar *publicID) { ************************************************************************/ /** - * @param func function pointer to the new RegisterNodeFunc + * Registers a callback for node creation * * @deprecated don't use * - * Registers a callback for node creation - * + * @param func function pointer to the new RegisterNodeFunc * @returns the old value of the registration function */ xmlRegisterNodeFunc @@ -9152,12 +9015,11 @@ xmlRegisterNodeDefault(xmlRegisterNodeFunc func) } /** - * @param func function pointer to the new DeregisterNodeFunc + * Registers a callback for node destruction * * @deprecated don't use * - * Registers a callback for node destruction - * + * @param func function pointer to the new DeregisterNodeFunc * @returns the previous value of the deregistration function */ xmlDeregisterNodeFunc diff --git a/uri.c b/uri.c index ee3efbd6..c2ae1f26 100644 --- a/uri.c +++ b/uri.c @@ -212,13 +212,12 @@ xmlIsUnreserved(xmlURIPtr uri, const char *cur) { } /** - * @param uri pointer to an URI structure - * @param str pointer to the string to analyze - * * Parse an URI scheme * * ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) * + * @param uri pointer to an URI structure + * @param str pointer to the string to analyze * @returns 0 or the error code */ static int @@ -251,9 +250,6 @@ xmlParse3986Scheme(xmlURIPtr uri, const char **str) { } /** - * @param uri pointer to an URI structure - * @param str pointer to the string to analyze - * * Parse the query part of an URI * * fragment = *( pchar / "/" / "?" ) @@ -262,6 +258,8 @@ xmlParse3986Scheme(xmlURIPtr uri, const char **str) { * xpointer scheme selection, so we are allowing it here to not break * for example all the DocBook processing chains. * + * @param uri pointer to an URI structure + * @param str pointer to the string to analyze * @returns 0 or the error code */ static int @@ -289,13 +287,12 @@ xmlParse3986Fragment(xmlURIPtr uri, const char **str) } /** - * @param uri pointer to an URI structure - * @param str pointer to the string to analyze - * * Parse the query part of an URI * * query = *uric * + * @param uri pointer to an URI structure + * @param str pointer to the string to analyze * @returns 0 or the error code */ static int @@ -331,14 +328,13 @@ xmlParse3986Query(xmlURIPtr uri, const char **str) } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse a port part and fills in the appropriate fields * of the `uri` structure * * port = *DIGIT * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -369,14 +365,13 @@ xmlParse3986Port(xmlURIPtr uri, const char **str) } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an user information part and fills in the appropriate fields * of the `uri` structure * * userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -405,8 +400,6 @@ xmlParse3986Userinfo(xmlURIPtr uri, const char **str) } /** - * @param str the string to analyze - * * dec-octet = DIGIT ; 0-9 * / %x31-39 DIGIT ; 10-99 * / "1" 2DIGIT ; 100-199 @@ -415,6 +408,7 @@ xmlParse3986Userinfo(xmlURIPtr uri, const char **str) * * Skip a dec-octet. * + * @param str the string to analyze * @returns 0 if found and skipped, 1 otherwise */ static int @@ -441,9 +435,6 @@ xmlParse3986DecOctet(const char **str) { return(0); } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an host part and fills in the appropriate fields * of the `uri` structure * @@ -452,6 +443,8 @@ xmlParse3986DecOctet(const char **str) { * IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet * reg-name = *( unreserved / pct-encoded / sub-delims ) * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -522,14 +515,13 @@ found: } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an authority part and fills in the appropriate fields * of the `uri` structure * * authority = [ userinfo "@" ] host [ ":" port ] * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -561,11 +553,6 @@ xmlParse3986Authority(xmlURIPtr uri, const char **str) } /** - * @param uri the URI - * @param str the string to analyze - * @param forbid an optional forbidden character - * @param empty allow an empty segment - * * Parse a segment and fills in the appropriate fields * of the `uri` structure * @@ -574,6 +561,10 @@ xmlParse3986Authority(xmlURIPtr uri, const char **str) * segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" ) * ; non-zero-length segment without any colon ":" * + * @param uri the URI + * @param str the string to analyze + * @param forbid an optional forbidden character + * @param empty allow an empty segment * @returns 0 or the error code */ static int @@ -604,14 +595,13 @@ xmlParse3986Segment(xmlURIPtr uri, const char **str, char forbid, int empty) } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an path absolute or empty and fills in the appropriate fields * of the `uri` structure * * path-abempty = *( "/" segment ) * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -645,14 +635,13 @@ xmlParse3986PathAbEmpty(xmlURIPtr uri, const char **str) } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an path absolute and fills in the appropriate fields * of the `uri` structure * * path-absolute = "/" [ segment-nz *( "/" segment ) ] * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -692,14 +681,13 @@ xmlParse3986PathAbsolute(xmlURIPtr uri, const char **str) } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an path without root and fills in the appropriate fields * of the `uri` structure * * path-rootless = segment-nz *( "/" segment ) * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -735,14 +723,13 @@ xmlParse3986PathRootless(xmlURIPtr uri, const char **str) } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an path which is not a scheme and fills in the appropriate fields * of the `uri` structure * * path-noscheme = segment-nz-nc *( "/" segment ) * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -778,9 +765,6 @@ xmlParse3986PathNoScheme(xmlURIPtr uri, const char **str) } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an hierarchical part and fills in the appropriate fields * of the `uri` structure * @@ -789,6 +773,8 @@ xmlParse3986PathNoScheme(xmlURIPtr uri, const char **str) * / path-rootless * / path-empty * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -830,9 +816,6 @@ xmlParse3986HierPart(xmlURIPtr uri, const char **str) } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an URI string and fills in the appropriate fields * of the `uri` structure * @@ -842,6 +825,8 @@ xmlParse3986HierPart(xmlURIPtr uri, const char **str) * / path-noscheme * / path-empty * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -887,14 +872,13 @@ xmlParse3986RelativeRef(xmlURIPtr uri, const char *str) { /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an URI string and fills in the appropriate fields * of the `uri` structure * * scheme ":" hier-part [ "?" query ] [ "\#" fragment ] * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -927,14 +911,13 @@ xmlParse3986URI(xmlURIPtr uri, const char *str) { } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an URI reference string and fills in the appropriate fields * of the `uri` structure * * URI-reference = URI / relative-ref * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ static int @@ -964,15 +947,14 @@ xmlParse3986URIReference(xmlURIPtr uri, const char *str) { } /** - * @param str the URI string to analyze - * @param uriOut optional pointer to parsed URI - * * Parse an URI based on RFC 3986 * * URI-reference = [ absoluteURI | relativeURI ] [ "\#" fragment ] * * @since 2.13.0 * + * @param str the URI string to analyze + * @param uriOut optional pointer to parsed URI * @returns 0 on success, an error code (typically 1) if the URI is invalid * or -1 if a memory allocation failed. */ @@ -1002,12 +984,11 @@ xmlParseURISafe(const char *str, xmlURIPtr *uriOut) { } /** - * @param str the URI string to analyze - * * Parse an URI based on RFC 3986 * * URI-reference = [ absoluteURI | relativeURI ] [ "\#" fragment ] * + * @param str the URI string to analyze * @returns a newly built xmlURIPtr or NULL in case of error */ xmlURIPtr @@ -1018,14 +999,13 @@ xmlParseURI(const char *str) { } /** - * @param uri pointer to an URI structure - * @param str the string to analyze - * * Parse an URI reference string based on RFC 3986 and fills in the * appropriate fields of the `uri` structure * * URI-reference = URI / relative-ref * + * @param uri pointer to an URI structure + * @param str the string to analyze * @returns 0 or the error code */ int @@ -1034,13 +1014,12 @@ xmlParseURIReference(xmlURIPtr uri, const char *str) { } /** - * @param str the URI string to analyze - * @param raw if 1 unescaping of URI pieces are disabled - * * Parse an URI but allows to keep intact the original fragments. * * URI-reference = URI / relative-ref * + * @param str the URI string to analyze + * @param raw if 1 unescaping of URI pieces are disabled * @returns a newly built xmlURIPtr or NULL in case of error */ xmlURIPtr @@ -1107,10 +1086,9 @@ xmlSaveUriRealloc(xmlChar *ret, int *max) { } /** - * @param uri pointer to an xmlURI - * * Save the URI as an escaped string * + * @param uri pointer to an xmlURI * @returns a new string (to be deallocated by caller) */ xmlChar * @@ -1380,10 +1358,10 @@ mem_error: } /** + * Prints the URI in the stream `stream`. + * * @param stream a FILE* for the output * @param uri pointer to an xmlURI - * - * Prints the URI in the stream `stream`. */ void xmlPrintURI(FILE *stream, xmlURIPtr uri) { @@ -1397,9 +1375,9 @@ xmlPrintURI(FILE *stream, xmlURIPtr uri) { } /** - * @param uri pointer to an xmlURI - * * Make sure the xmlURI struct is free of content + * + * @param uri pointer to an xmlURI */ static void xmlCleanURI(xmlURIPtr uri) { @@ -1426,9 +1404,9 @@ xmlCleanURI(xmlURIPtr uri) { } /** - * @param uri pointer to an xmlURI - * * Free up the xmlURI struct + * + * @param uri pointer to an xmlURI */ void xmlFreeURI(xmlURIPtr uri) { @@ -1468,11 +1446,10 @@ xmlIsPathSeparator(int c, int isFile) { } /** - * @param path pointer to the path string - * @param isFile true for filesystem paths, false for URIs - * * Normalize a filesystem path or URI. * + * @param path pointer to the path string + * @param isFile true for filesystem paths, false for URIs * @returns 0 or an error code */ static int @@ -1566,13 +1543,12 @@ xmlNormalizePath(char *path, int isFile) { } /** - * @param path pointer to the path string - * * Applies the 5 normalization steps to a path string--that is, RFC 2396 * Section 5.2, steps 6.c through 6.g. * * Normalization occurs directly on the string, no new allocation is done * + * @param path pointer to the path string * @returns 0 or an error code */ int @@ -1589,15 +1565,14 @@ static int is_hex(char c) { } /** - * @param str the string to unescape - * @param len the length in bytes to unescape (or <= 0 to indicate full string) - * @param target optional destination buffer - * * Unescaping routine, but does not check that the string is an URI. The * output is a direct unsigned char translation of %XX values (no encoding) * Note that the length of the result can only be smaller or same size as * the input string. * + * @param str the string to unescape + * @param len the length in bytes to unescape (or <= 0 to indicate full string) + * @param target optional destination buffer * @returns a copy of the string, but unescaped, will return NULL only in case * of error */ @@ -1650,13 +1625,12 @@ xmlURIUnescapeString(const char *str, int len, char *target) { } /** - * @param str string to escape - * @param list exception list string of chars not to escape - * * This routine escapes a string to hex, ignoring unreserved characters * a-z, A-Z, 0-9, "-._~", a few sub-delims "!*'()", the gen-delim "@" * (why?) and the characters in the exception list. * + * @param str string to escape + * @param list exception list string of chars not to escape * @returns a new escaped string or NULL in case of error. */ xmlChar * @@ -1722,18 +1696,16 @@ xmlURIEscapeStr(const xmlChar *str, const xmlChar *list) { } /** - * @param str the string of the URI to escape - * * Escaping routine, does not do validity checks ! * It will try to escape the chars needing this, but this is heuristic * based it's impossible to be sure. * - * @returns an copy of the string, but escaped - * * 25 May 2001 * Uses xmlParseURI() and xmlURIEscapeStr() to try to escape correctly * according to RFC2396. * - Carl Douglas + * @param str the string of the URI to escape + * @returns an copy of the string, but escaped */ xmlChar * xmlURIEscape(const xmlChar * str) @@ -1877,12 +1849,11 @@ xmlIsAbsolutePath(const xmlChar *path) { } /** + * Resolves a filesystem path from a base path. + * * @param escRef the filesystem path * @param base the base value * @param out pointer to result URI - * - * Resolves a filesystem path from a base path. - * * @returns 0 on success, -1 if a memory allocation failed or an error * code if URI or base are invalid. */ @@ -1980,10 +1951,6 @@ err_memory: } /** - * @param URI the URI instance found in the document - * @param base the base value - * @param valPtr pointer to result URI - * * Computes he final URI of the reference done by checking that * the given URI is valid, and building the final URI using the * base URI. This is processed according to section 5.2 of the @@ -1993,6 +1960,9 @@ err_memory: * * @since 2.13.0 * + * @param URI the URI instance found in the document + * @param base the base value + * @param valPtr pointer to result URI * @returns 0 on success, -1 if a memory allocation failed or an error * code if URI or base are invalid. */ @@ -2348,9 +2318,6 @@ done: } /** - * @param URI the URI instance found in the document - * @param base the base value - * * Computes he final URI of the reference done by checking that * the given URI is valid, and building the final URI using the * base URI. This is processed according to section 5.2 of the @@ -2358,6 +2325,8 @@ done: * * 5.2. Resolving Relative References to Absolute Form * + * @param URI the URI instance found in the document + * @param base the base value * @returns a new URI string (to be freed by the caller) or NULL in case * of error. */ @@ -2493,10 +2462,6 @@ done: } /** - * @param URI the URI reference under consideration - * @param base the base value - * @param valPtr pointer to result URI - * * Expresses the URI of the reference in terms relative to the * base. Some examples of this operation include: * @@ -2514,6 +2479,9 @@ done: * * @since 2.13.0 * + * @param URI the URI reference under consideration + * @param base the base value + * @param valPtr pointer to result URI * @returns 0 on success, -1 if a memory allocation failed or an error * code if URI or base are invalid. */ @@ -2753,8 +2721,6 @@ xmlBuildRelativeURI(const xmlChar * URI, const xmlChar * base) } /** - * @param path the resource locator in a filesystem notation - * * Prepares a path. * * If the path contains the substring "://", it is considered a @@ -2768,6 +2734,7 @@ xmlBuildRelativeURI(const xmlChar * URI, const xmlChar * base) * by the returned string. If there is insufficient memory available, or the * argument is NULL, the function returns NULL. * + * @param path the resource locator in a filesystem notation * @returns the escaped path. */ xmlChar * @@ -2796,10 +2763,9 @@ xmlCanonicPath(const xmlChar *path) } /** - * @param path the resource locator in a filesystem notation - * * Constructs an URI expressing the existing path * + * @param path the resource locator in a filesystem notation * @returns a new URI, or a duplicate of the path parameter if the * construction fails. The caller is responsible for freeing the memory * occupied by the returned string. If there is insufficient memory available, diff --git a/valid.c b/valid.c index e9b347ba..e20c93b3 100644 --- a/valid.c +++ b/valid.c @@ -45,9 +45,9 @@ xmlValidateAttributeValueInternal(xmlDocPtr doc, xmlAttributeType type, ************************************************************************/ /** - * @param ctxt an XML validation parser context - * * Handle an out of memory error + * + * @param ctxt an XML validation parser context */ static void xmlVErrMemory(xmlValidCtxtPtr ctxt) @@ -103,12 +103,12 @@ xmlDoErrValid(xmlValidCtxtPtr ctxt, xmlNodePtr node, } /** + * Handle a validation error + * * @param ctxt an XML validation parser context * @param error the error number * @param msg the error message * @param extra extra information - * - * Handle a validation error */ static void LIBXML_ATTR_FORMAT(3,0) xmlErrValid(xmlValidCtxtPtr ctxt, xmlParserErrors error, @@ -120,6 +120,8 @@ xmlErrValid(xmlValidCtxtPtr ctxt, xmlParserErrors error, #ifdef LIBXML_VALID_ENABLED /** + * Handle a validation error, provide contextual information + * * @param ctxt an XML validation parser context * @param node the node raising the error * @param error the error number @@ -127,8 +129,6 @@ xmlErrValid(xmlValidCtxtPtr ctxt, xmlParserErrors error, * @param str1 extra information * @param str2 extra information * @param str3 extra information - * - * Handle a validation error, provide contextual information */ static void LIBXML_ATTR_FORMAT(4,0) xmlErrValidNode(xmlValidCtxtPtr ctxt, @@ -141,6 +141,8 @@ xmlErrValidNode(xmlValidCtxtPtr ctxt, } /** + * Handle a validation error, provide contextual information + * * @param ctxt an XML validation parser context * @param node the node raising the error * @param error the error number @@ -148,8 +150,6 @@ xmlErrValidNode(xmlValidCtxtPtr ctxt, * @param str1 extra information * @param int2 extra information * @param str3 extra information - * - * Handle a validation error, provide contextual information */ static void LIBXML_ATTR_FORMAT(4,0) xmlErrValidNodeNr(xmlValidCtxtPtr ctxt, @@ -162,6 +162,8 @@ xmlErrValidNodeNr(xmlValidCtxtPtr ctxt, } /** + * Handle a validation error, provide contextual information + * * @param ctxt an XML validation parser context * @param node the node raising the error * @param error the error number @@ -169,8 +171,6 @@ xmlErrValidNodeNr(xmlValidCtxtPtr ctxt, * @param str1 extra information * @param str2 extra information * @param str3 extra information - * - * Handle a validation error, provide contextual information */ static void LIBXML_ATTR_FORMAT(4,0) xmlErrValidWarning(xmlValidCtxtPtr ctxt, @@ -417,12 +417,11 @@ nodeVPop(xmlValidCtxtPtr ctxt) ************************************************************************/ /** + * Generate the automata sequence needed for that type + * * @param content the content model * @param ctxt the schema parser context * @param name the element name whose content is being built - * - * Generate the automata sequence needed for that type - * * @returns 1 if successful or 0 in case of error. */ static int @@ -574,14 +573,13 @@ xmlValidBuildAContentModel(xmlElementContentPtr content, return(1); } /** - * @param ctxt a validation context - * @param elem an element declaration node - * - * @deprecated Internal function, don't use. - * * (Re)Build the automata associated to the content model of this * element * + * @deprecated Internal function, don't use. + * + * @param ctxt a validation context + * @param elem an element declaration node * @returns 1 in case of success, 0 in case of error */ int @@ -665,9 +663,9 @@ xmlValidCtxtPtr xmlNewValidCtxt(void) { } /** - * @param cur the validation context to free - * * Free a validation context structure. + * + * @param cur the validation context to free */ void xmlFreeValidCtxt(xmlValidCtxtPtr cur) { @@ -683,14 +681,13 @@ xmlFreeValidCtxt(xmlValidCtxtPtr cur) { #endif /* LIBXML_VALID_ENABLED */ /** - * @param doc the document - * @param name the subelement name or NULL - * @param type the type of element content decl + * Allocate an element content structure for the document. * * @deprecated Internal function, don't use. * - * Allocate an element content structure for the document. - * + * @param doc the document + * @param name the subelement name or NULL + * @param type the type of element content decl * @returns the new element content structure or NULL on * error. */ @@ -764,14 +761,13 @@ error: } /** - * @param name the subelement name or NULL - * @param type the type of element content decl - * - * @deprecated Internal function, don't use. - * * Allocate an element content structure. * Deprecated in favor of xmlNewDocElementContent() * + * @deprecated Internal function, don't use. + * + * @param name the subelement name or NULL + * @param type the type of element content decl * @returns the new element content structure or NULL on * error. */ @@ -781,13 +777,12 @@ xmlNewElementContent(const xmlChar *name, xmlElementContentType type) { } /** - * @param doc the document owning the element declaration - * @param cur An element content pointer. + * Build a copy of an element content description. * * @deprecated Internal function, don't use. * - * Build a copy of an element content description. - * + * @param doc the document owning the element declaration + * @param cur An element content pointer. * @returns the new xmlElementContentPtr or NULL in case of error. */ xmlElementContentPtr @@ -876,13 +871,12 @@ error: } /** - * @param cur An element content pointer. - * - * @deprecated Internal function, don't use. - * * Build a copy of an element content description. * Deprecated, use xmlCopyDocElementContent() instead * + * @deprecated Internal function, don't use. + * + * @param cur An element content pointer. * @returns the new xmlElementContentPtr or NULL in case of error. */ xmlElementContentPtr @@ -891,12 +885,12 @@ xmlCopyElementContent(xmlElementContentPtr cur) { } /** - * @param doc the document owning the element declaration - * @param cur the element content tree to free + * Free an element content structure. The whole subtree is removed. * * @deprecated Internal function, don't use. * - * Free an element content structure. The whole subtree is removed. + * @param doc the document owning the element declaration + * @param cur the element content tree to free */ void xmlFreeDocElementContent(xmlDocPtr doc, xmlElementContentPtr cur) { @@ -958,12 +952,12 @@ xmlFreeDocElementContent(xmlDocPtr doc, xmlElementContentPtr cur) { } /** - * @param cur the element content tree to free + * Free an element content structure. The whole subtree is removed. + * Deprecated, use xmlFreeDocElementContent() instead * * @deprecated Internal function, don't use. * - * Free an element content structure. The whole subtree is removed. - * Deprecated, use xmlFreeDocElementContent() instead + * @param cur the element content tree to free */ void xmlFreeElementContent(xmlElementContentPtr cur) { @@ -972,13 +966,13 @@ xmlFreeElementContent(xmlElementContentPtr cur) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param buf an output buffer - * @param content An element table - * @param englob 1 if one must print the englobing parenthesis, 0 otherwise + * Deprecated, unsafe, use xmlSnprintfElementContent() * * @deprecated Internal function, don't use. * - * Deprecated, unsafe, use xmlSnprintfElementContent() + * @param buf an output buffer + * @param content An element table + * @param englob 1 if one must print the englobing parenthesis, 0 otherwise */ void xmlSprintfElementContent(char *buf ATTRIBUTE_UNUSED, @@ -988,15 +982,15 @@ xmlSprintfElementContent(char *buf ATTRIBUTE_UNUSED, #endif /* LIBXML_OUTPUT_ENABLED */ /** + * This will dump the content of the element content definition + * Intended just for the debug routine + * + * @deprecated Internal function, don't use. + * * @param buf an output buffer * @param size the buffer size * @param content An element table * @param englob 1 if one must print the englobing parenthesis, 0 otherwise - * - * @deprecated Internal function, don't use. - * - * This will dump the content of the element content definition - * Intended just for the debug routine */ void xmlSnprintfElementContent(char *buf, int size, xmlElementContentPtr content, int englob) { @@ -1097,9 +1091,9 @@ xmlSnprintfElementContent(char *buf, int size, xmlElementContentPtr content, int ****************************************************************/ /** - * @param elem an element - * * Deallocate the memory used by an element definition + * + * @param elem an element */ static void xmlFreeElement(xmlElementPtr elem) { @@ -1119,16 +1113,15 @@ xmlFreeElement(xmlElementPtr elem) { /** + * Register a new element declaration. + * + * @deprecated Internal function, don't use. + * * @param ctxt the validation context * @param dtd pointer to the DTD * @param name the entity name * @param type the element type * @param content the element content tree or NULL - * - * @deprecated Internal function, don't use. - * - * Register a new element declaration. - * * @returns the entity or NULL on error. */ xmlElementPtr @@ -1333,11 +1326,11 @@ xmlFreeElementTableEntry(void *elem, const xmlChar *name ATTRIBUTE_UNUSED) { } /** - * @param table An element table + * Deallocate the memory used by an element hash table. * * @deprecated Internal function, don't use. * - * Deallocate the memory used by an element hash table. + * @param table An element table */ void xmlFreeElementTable(xmlElementTablePtr table) { @@ -1345,11 +1338,10 @@ xmlFreeElementTable(xmlElementTablePtr table) { } /** - * @param payload an element - * @param name unused - * * Build a copy of an element. * + * @param payload an element + * @param name unused * @returns the new xmlElementPtr or NULL in case of error. */ static void * @@ -1388,12 +1380,11 @@ error: } /** - * @param table An element table + * Build a copy of an element table. * * @deprecated Internal function, don't use. * - * Build a copy of an element table. - * + * @param table An element table * @returns the new xmlElementTablePtr or NULL in case of error. */ xmlElementTablePtr @@ -1403,13 +1394,13 @@ xmlCopyElementTable(xmlElementTablePtr table) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param buf the XML buffer output - * @param elem An element table + * This will dump the content of the element declaration as an XML + * DTD definition. * * @deprecated Use xmlSaveTree(). * - * This will dump the content of the element declaration as an XML - * DTD definition. + * @param buf the XML buffer output + * @param elem An element table */ void xmlDumpElementDecl(xmlBufferPtr buf, xmlElementPtr elem) { @@ -1425,12 +1416,12 @@ xmlDumpElementDecl(xmlBufferPtr buf, xmlElementPtr elem) { } /** + * This routine is used by the hash scan function. It just reverses + * the arguments. + * * @param elem an element declaration * @param save a save context * @param name unused - * - * This routine is used by the hash scan function. It just reverses - * the arguments. */ static void xmlDumpElementDeclScan(void *elem, void *save, @@ -1439,13 +1430,13 @@ xmlDumpElementDeclScan(void *elem, void *save, } /** - * @param buf the XML buffer output - * @param table An element table + * This will dump the content of the element table as an XML DTD + * definition. * * @deprecated Don't use. * - * This will dump the content of the element table as an XML DTD - * definition. + * @param buf the XML buffer output + * @param table An element table */ void xmlDumpElementTable(xmlBufferPtr buf, xmlElementTablePtr table) { @@ -1462,12 +1453,11 @@ xmlDumpElementTable(xmlBufferPtr buf, xmlElementTablePtr table) { #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param name the enumeration name or NULL + * Create and initialize an enumeration attribute node. * * @deprecated Internal function, don't use. * - * Create and initialize an enumeration attribute node. - * + * @param name the enumeration name or NULL * @returns the xmlEnumerationPtr just created or NULL in case * of error. */ @@ -1492,9 +1482,9 @@ xmlCreateEnumeration(const xmlChar *name) { } /** - * @param cur the tree to free. - * * Free an enumeration attribute node (recursive). + * + * @param cur the tree to free. */ void xmlFreeEnumeration(xmlEnumerationPtr cur) { @@ -1509,12 +1499,11 @@ xmlFreeEnumeration(xmlEnumerationPtr cur) { } /** - * @param cur the tree to copy. + * Copy an enumeration attribute node (recursive). * * @deprecated Internal function, don't use. * - * Copy an enumeration attribute node (recursive). - * + * @param cur the tree to copy. * @returns the xmlEnumerationPtr just created or NULL in case * of error. */ @@ -1546,13 +1535,12 @@ xmlCopyEnumeration(xmlEnumerationPtr cur) { #ifdef LIBXML_VALID_ENABLED /** - * @param ctxt the validation context - * @param elem the element name - * @param err whether to raise errors here - * * Verify that the element doesn't have too many ID attributes * declared. * + * @param ctxt the validation context + * @param elem the element name + * @param err whether to raise errors here * @returns the number of ID attributes found. */ static int @@ -1577,9 +1565,9 @@ xmlScanIDAttributeDecl(xmlValidCtxtPtr ctxt, xmlElementPtr elem, int err) { #endif /* LIBXML_VALID_ENABLED */ /** - * @param attr an attribute - * * Deallocate the memory used by an attribute definition. + * + * @param attr an attribute */ static void xmlFreeAttribute(xmlAttributePtr attr) { @@ -1618,6 +1606,10 @@ xmlFreeAttribute(xmlAttributePtr attr) { /** + * Register a new attribute declaration. + * + * @deprecated Internal function, don't use. + * * @param ctxt the validation context * @param dtd pointer to the DTD * @param elem the element name @@ -1627,11 +1619,6 @@ xmlFreeAttribute(xmlAttributePtr attr) { * @param def the attribute default type * @param defaultValue the attribute default value * @param tree if it's an enumeration, the associated list - * - * @deprecated Internal function, don't use. - * - * Register a new attribute declaration. - * * @returns the attribute decl or NULL on error. */ xmlAttributePtr @@ -1868,11 +1855,11 @@ xmlFreeAttributeTableEntry(void *attr, const xmlChar *name ATTRIBUTE_UNUSED) { } /** - * @param table An attribute table + * Deallocate the memory used by an entities hash table. * * @deprecated Internal function, don't use. * - * Deallocate the memory used by an entities hash table. + * @param table An attribute table */ void xmlFreeAttributeTable(xmlAttributeTablePtr table) { @@ -1880,11 +1867,10 @@ xmlFreeAttributeTable(xmlAttributeTablePtr table) { } /** - * @param payload an attribute declaration - * @param name unused - * * Build a copy of an attribute declaration. * + * @param payload an attribute declaration + * @param name unused * @returns the new xmlAttributePtr or NULL in case of error. */ static void * @@ -1932,12 +1918,11 @@ error: } /** - * @param table An attribute table + * Build a copy of an attribute table. * * @deprecated Internal function, don't use. * - * Build a copy of an attribute table. - * + * @param table An attribute table * @returns the new xmlAttributeTablePtr or NULL in case of error. */ xmlAttributeTablePtr @@ -1948,13 +1933,13 @@ xmlCopyAttributeTable(xmlAttributeTablePtr table) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param buf the XML buffer output - * @param attr An attribute declaration + * This will dump the content of the attribute declaration as an XML + * DTD definition. * * @deprecated Use xmlSaveTree(). * - * This will dump the content of the attribute declaration as an XML - * DTD definition. + * @param buf the XML buffer output + * @param attr An attribute declaration */ void xmlDumpAttributeDecl(xmlBufferPtr buf, xmlAttributePtr attr) { @@ -1970,12 +1955,12 @@ xmlDumpAttributeDecl(xmlBufferPtr buf, xmlAttributePtr attr) { } /** + * This is used with the hash scan function - just reverses + * arguments. + * * @param attr an attribute declaration * @param save a save context * @param name unused - * - * This is used with the hash scan function - just reverses - * arguments. */ static void xmlDumpAttributeDeclScan(void *attr, void *save, @@ -1984,13 +1969,13 @@ xmlDumpAttributeDeclScan(void *attr, void *save, } /** - * @param buf the XML buffer output - * @param table an attribute table + * This will dump the content of the attribute table as an XML + * DTD definition. * * @deprecated Don't use. * - * This will dump the content of the attribute table as an XML - * DTD definition. + * @param buf the XML buffer output + * @param table an attribute table */ void xmlDumpAttributeTable(xmlBufferPtr buf, xmlAttributeTablePtr table) { @@ -2012,9 +1997,9 @@ xmlDumpAttributeTable(xmlBufferPtr buf, xmlAttributeTablePtr table) { * * ************************************************************************/ /** - * @param nota a notation - * * Deallocate the memory used by an notation definition. + * + * @param nota a notation */ static void xmlFreeNotation(xmlNotationPtr nota) { @@ -2030,16 +2015,15 @@ xmlFreeNotation(xmlNotationPtr nota) { /** + * Register a new notation declaration. + * + * @deprecated Internal function, don't use. + * * @param dtd pointer to the DTD * @param ctxt the validation context * @param name the entity name * @param PublicID the public identifier or NULL * @param SystemID the system identifier or NULL - * - * @deprecated Internal function, don't use. - * - * Register a new notation declaration. - * * @returns the notation or NULL on error. */ xmlNotationPtr @@ -2126,11 +2110,11 @@ xmlFreeNotationTableEntry(void *nota, const xmlChar *name ATTRIBUTE_UNUSED) { } /** - * @param table An notation table + * Deallocate the memory used by an entities hash table. * * @deprecated Internal function, don't use. * - * Deallocate the memory used by an entities hash table. + * @param table An notation table */ void xmlFreeNotationTable(xmlNotationTablePtr table) { @@ -2138,11 +2122,10 @@ xmlFreeNotationTable(xmlNotationTablePtr table) { } /** - * @param payload a notation - * @param name unused - * * Build a copy of a notation. * + * @param payload a notation + * @param name unused * @returns the new xmlNotationPtr or NULL in case of error. */ static void * @@ -2177,12 +2160,11 @@ error: } /** - * @param table A notation table + * Build a copy of a notation table. * * @deprecated Internal function, don't use. * - * Build a copy of a notation table. - * + * @param table A notation table * @returns the new xmlNotationTablePtr or NULL in case of error. */ xmlNotationTablePtr @@ -2192,13 +2174,13 @@ xmlCopyNotationTable(xmlNotationTablePtr table) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param buf the XML buffer output - * @param nota A notation declaration + * This will dump the content the notation declaration as an XML + * DTD definition. * * @deprecated Don't use. * - * This will dump the content the notation declaration as an XML - * DTD definition. + * @param buf the XML buffer output + * @param nota A notation declaration */ void xmlDumpNotationDecl(xmlBufferPtr buf, xmlNotationPtr nota) { @@ -2214,13 +2196,13 @@ xmlDumpNotationDecl(xmlBufferPtr buf, xmlNotationPtr nota) { } /** - * @param buf the XML buffer output - * @param table A notation table + * This will dump the content of the notation table as an XML + * DTD definition. * * @deprecated Don't use. * - * This will dump the content of the notation table as an XML - * DTD definition. + * @param buf the XML buffer output + * @param table A notation table */ void xmlDumpNotationTable(xmlBufferPtr buf, xmlNotationTablePtr table) { @@ -2243,10 +2225,10 @@ xmlDumpNotationTable(xmlBufferPtr buf, xmlNotationTablePtr table) { ************************************************************************/ /** - * @param str a string - * * Free a string if it is not owned by the dictionary in the * current scope + * + * @param str a string */ #define DICT_FREE(str) \ if ((str) && ((!dict) || \ @@ -2266,9 +2248,9 @@ xmlIsStreaming(xmlValidCtxtPtr ctxt) { } /** - * @param id an id - * * Deallocate the memory used by an id definition. + * + * @param id an id */ static void xmlFreeID(xmlIDPtr id) { @@ -2293,12 +2275,11 @@ xmlFreeID(xmlIDPtr id) { /** + * Add an attribute to the docment's ID table. + * * @param attr the attribute holding the ID * @param value the attribute (ID) value * @param idPtr pointer to resulting ID - * - * Add an attribute to the docment's ID table. - * * @returns 1 on success, 0 if the ID already exists, -1 if a memory * allocation fails. */ @@ -2370,13 +2351,12 @@ xmlAddIDInternal(xmlAttrPtr attr, const xmlChar *value, xmlIDPtr *idPtr) { } /** - * @param attr the attribute holding the ID - * @param value the attribute (ID) value - * * Add an attribute to the docment's ID table. * * @since 2.13.0 * + * @param attr the attribute holding the ID + * @param value the attribute (ID) value * @returns 1 on success, 0 if the ID already exists, -1 if a memory * allocation fails. */ @@ -2386,13 +2366,12 @@ xmlAddIDSafe(xmlAttrPtr attr, const xmlChar *value) { } /** + * Add an attribute to the docment's ID table. + * * @param ctxt the validation context (optional) * @param doc pointer to the document, must equal `attr->doc` * @param value the attribute (ID) value * @param attr the attribute holding the ID - * - * Add an attribute to the docment's ID table. - * * @returns the new xmlIDPtr or NULL on error. */ xmlIDPtr @@ -2429,9 +2408,9 @@ xmlFreeIDTableEntry(void *id, const xmlChar *name ATTRIBUTE_UNUSED) { } /** - * @param table An id table - * * Deallocate the memory used by an ID hash table. + * + * @param table An id table */ void xmlFreeIDTable(xmlIDTablePtr table) { @@ -2439,15 +2418,14 @@ xmlFreeIDTable(xmlIDTablePtr table) { } /** - * @param doc the document - * @param elem the element carrying the attribute - * @param attr the attribute - * * Determine whether an attribute is of type ID. In case we have DTD(s) * then this is done if DTD loading has been requested. In case * of HTML documents parsed with the HTML parser, ID detection is * done systematically. * + * @param doc the document + * @param elem the element carrying the attribute + * @param attr the attribute * @returns 0 or 1 depending on the lookup result or -1 if a memory * allocation failed. */ @@ -2513,11 +2491,10 @@ xmlIsID(xmlDocPtr doc, xmlNodePtr elem, xmlAttrPtr attr) { } /** - * @param doc the document - * @param attr the attribute - * * Remove the given attribute from the document's ID table. * + * @param doc the document + * @param attr the attribute * @returns -1 if the lookup failed and 0 otherwise. */ int @@ -2538,12 +2515,11 @@ xmlRemoveID(xmlDocPtr doc, xmlAttrPtr attr) { } /** - * @param doc pointer to the document - * @param ID the ID value - * * Search the document's ID table for the attribute with the * given ID. * + * @param doc pointer to the document + * @param ID the ID value * @returns the attribute or NULL if not found. */ xmlAttrPtr @@ -2598,9 +2574,9 @@ typedef struct xmlValidateMemo_t typedef xmlValidateMemo *xmlValidateMemoPtr; /** - * @param lk A list link - * * Deallocate the memory used by a ref definition. + * + * @param lk A list link */ static void xmlFreeRef(xmlLinkPtr lk) { @@ -2614,10 +2590,10 @@ xmlFreeRef(xmlLinkPtr lk) { } /** + * Deallocate the memory used by a list of references. + * * @param payload A list of references. * @param name unused - * - * Deallocate the memory used by a list of references. */ static void xmlFreeRefTableEntry(void *payload, const xmlChar *name ATTRIBUTE_UNUSED) { @@ -2629,7 +2605,6 @@ xmlFreeRefTableEntry(void *payload, const xmlChar *name ATTRIBUTE_UNUSED) { /** * @param data Contents of current link * @param user Value supplied by the user - * * @returns 0 to abort the walk or 1 to continue. */ static int @@ -2647,11 +2622,10 @@ xmlWalkRemoveRef(const void *data, void *user) } /** - * @param data0 Value supplied by the user - * @param data1 Value supplied by the user - * * Do nothing. Used to create unordered lists. * + * @param data0 Value supplied by the user + * @param data1 Value supplied by the user * @returns 0 */ static int @@ -2662,16 +2636,15 @@ xmlDummyCompare(const void *data0 ATTRIBUTE_UNUSED, } /** - * @param ctxt the validation context - * @param doc pointer to the document - * @param value the value name - * @param attr the attribute holding the Ref + * Register a new ref declaration. * * @deprecated Don't use. This function will be removed from the * public API. * - * Register a new ref declaration. - * + * @param ctxt the validation context + * @param doc pointer to the document + * @param value the value name + * @param attr the attribute holding the Ref * @returns the new xmlRefPtr or NULL o error. */ xmlRefPtr @@ -2763,12 +2736,12 @@ failed: } /** - * @param table a ref table + * Deallocate the memory used by an Ref hash table. * * @deprecated Don't use. This function will be removed from the * public API. * - * Deallocate the memory used by an Ref hash table. + * @param table a ref table */ void xmlFreeRefTable(xmlRefTablePtr table) { @@ -2776,17 +2749,16 @@ xmlFreeRefTable(xmlRefTablePtr table) { } /** - * @param doc the document - * @param elem the element carrying the attribute - * @param attr the attribute - * - * @deprecated Don't use. This function will be removed from the - * public API. - * * Determine whether an attribute is of type Ref. In case we have DTD(s) * then this is simple, otherwise we use an heuristic: name Ref (upper * or lowercase). * + * @deprecated Don't use. This function will be removed from the + * public API. + * + * @param doc the document + * @param elem the element carrying the attribute + * @param attr the attribute * @returns 0 or 1 depending on the lookup result. */ int @@ -2824,14 +2796,13 @@ xmlIsRef(xmlDocPtr doc, xmlNodePtr elem, xmlAttrPtr attr) { } /** - * @param doc the document - * @param attr the attribute + * Remove the given attribute from the Ref table maintained internally. * * @deprecated Don't use. This function will be removed from the * public API. * - * Remove the given attribute from the Ref table maintained internally. - * + * @param doc the document + * @param attr the attribute * @returns -1 if the lookup failed and 0 otherwise. */ int @@ -2882,14 +2853,13 @@ xmlRemoveRef(xmlDocPtr doc, xmlAttrPtr attr) { } /** - * @param doc pointer to the document - * @param ID the ID value + * Find the set of references for the supplied ID. * * @deprecated Don't use. This function will be removed from the * public API. * - * Find the set of references for the supplied ID. - * + * @param doc pointer to the document + * @param ID the ID value * @returns the list of nodes matching the ID or NULL on error. */ xmlListPtr @@ -2918,13 +2888,12 @@ xmlGetRefs(xmlDocPtr doc, const xmlChar *ID) { ************************************************************************/ /** - * @param dtd a pointer to the DtD to search - * @param name the element name - * * Search the DTD for the description of this element. * * NOTE: A NULL return value can also mean that a memory allocation failed. * + * @param dtd a pointer to the DtD to search + * @param name the element name * @returns the xmlElementPtr or NULL if not found. */ @@ -2953,12 +2922,11 @@ xmlGetDtdElementDesc(xmlDtdPtr dtd, const xmlChar *name) { } /** + * Search the DTD for the description of this element. + * * @param ctxt a validation context * @param dtd a pointer to the DtD to search * @param name the element name - * - * Search the DTD for the description of this element. - * * @returns the xmlElementPtr or NULL if not found. */ @@ -3024,12 +2992,11 @@ mem_error: } /** + * Search the DTD for the description of this element. + * * @param dtd a pointer to the DtD to search * @param name the element name * @param prefix the element namespace prefix - * - * Search the DTD for the description of this element. - * * @returns the xmlElementPtr or NULL if not found. */ @@ -3046,13 +3013,12 @@ xmlGetDtdQElementDesc(xmlDtdPtr dtd, const xmlChar *name, } /** - * @param dtd a pointer to the DtD to search - * @param elem the element name - * @param name the attribute name - * * Search the DTD for the description of this attribute on * this element. * + * @param dtd a pointer to the DtD to search + * @param elem the element name + * @param name the attribute name * @returns the xmlAttributePtr or NULL if not found. */ @@ -3081,14 +3047,13 @@ xmlGetDtdAttrDesc(xmlDtdPtr dtd, const xmlChar *elem, const xmlChar *name) { } /** + * Search the DTD for the description of this qualified attribute on + * this element. + * * @param dtd a pointer to the DtD to search * @param elem the element name * @param name the attribute name * @param prefix the attribute namespace prefix - * - * Search the DTD for the description of this qualified attribute on - * this element. - * * @returns the xmlAttributePtr or NULL if not found. */ @@ -3105,11 +3070,10 @@ xmlGetDtdQAttrDesc(xmlDtdPtr dtd, const xmlChar *elem, const xmlChar *name, } /** - * @param dtd a pointer to the DtD to search - * @param name the notation name - * * Search the DTD for the description of this notation. * + * @param dtd a pointer to the DtD to search + * @param name the notation name * @returns the xmlNotationPtr or NULL if not found. */ @@ -3126,15 +3090,14 @@ xmlGetDtdNotationDesc(xmlDtdPtr dtd, const xmlChar *name) { #ifdef LIBXML_VALID_ENABLED /** - * @param ctxt the validation context - * @param doc the document - * @param notationName the notation name to check - * - * @deprecated Internal function, don't use. - * * Validate that the given name match a notation declaration. * [ VC: Notation Declared ] * + * @deprecated Internal function, don't use. + * + * @param ctxt the validation context + * @param doc the document + * @param notationName the notation name to check * @returns 1 if valid or 0 otherwise. */ @@ -3160,12 +3123,11 @@ xmlValidateNotationUse(xmlValidCtxtPtr ctxt, xmlDocPtr doc, #endif /* LIBXML_VALID_ENABLED */ /** - * @param doc the document - * @param name the element name - * * Search in the DTDs whether an element accepts mixed content * or ANY (basically if it is supposed to accept text children). * + * @param doc the document + * @param name the element name * @returns 0 if no, 1 if yes, and -1 if no element description * is available. */ @@ -3200,9 +3162,9 @@ xmlIsMixedElement(xmlDocPtr doc, const xmlChar *name) { #ifdef LIBXML_VALID_ENABLED /** - * @param str a string - * * Normalize a string in-place. + * + * @param str a string */ static void xmlValidNormalizeString(xmlChar *str) { @@ -3296,11 +3258,10 @@ xmlIsDocNameChar(xmlDocPtr doc, int c) { } /** - * @param doc pointer to the document or NULL - * @param value an Name value - * * Validate that the given value matches the Name production. * + * @param doc pointer to the document or NULL + * @param value an Name value * @returns 1 if valid or 0 otherwise. */ @@ -3329,10 +3290,9 @@ xmlValidateNameValueInternal(xmlDocPtr doc, const xmlChar *value) { } /** - * @param value an Name value - * * Validate that the given value matches the Name production. * + * @param value an Name value * @returns 1 if valid or 0 otherwise. */ @@ -3342,11 +3302,10 @@ xmlValidateNameValue(const xmlChar *value) { } /** - * @param doc pointer to the document or NULL - * @param value an Names value - * * Validate that the given value matches the Names production. * + * @param doc pointer to the document or NULL + * @param value an Names value * @returns 1 if valid or 0 otherwise. */ @@ -3395,10 +3354,9 @@ xmlValidateNamesValueInternal(xmlDocPtr doc, const xmlChar *value) { } /** - * @param value an Names value - * * Validate that the given value matches the Names production. * + * @param value an Names value * @returns 1 if valid or 0 otherwise. */ @@ -3408,13 +3366,12 @@ xmlValidateNamesValue(const xmlChar *value) { } /** - * @param doc pointer to the document or NULL - * @param value an Nmtoken value - * * Validate that the given value matches the Nmtoken production. * * [ VC: Name Token ] * + * @param doc pointer to the document or NULL + * @param value an Nmtoken value * @returns 1 if valid or 0 otherwise. */ @@ -3444,12 +3401,11 @@ xmlValidateNmtokenValueInternal(xmlDocPtr doc, const xmlChar *value) { } /** - * @param value an Nmtoken value - * * Validate that the given value matches the Nmtoken production. * * [ VC: Name Token ] * + * @param value an Nmtoken value * @returns 1 if valid or 0 otherwise. */ @@ -3459,13 +3415,12 @@ xmlValidateNmtokenValue(const xmlChar *value) { } /** - * @param doc pointer to the document or NULL - * @param value an Nmtokens value - * * Validate that the given value matches the Nmtokens production. * * [ VC: Name Token ] * + * @param doc pointer to the document or NULL + * @param value an Nmtokens value * @returns 1 if valid or 0 otherwise. */ @@ -3518,12 +3473,11 @@ xmlValidateNmtokensValueInternal(xmlDocPtr doc, const xmlChar *value) { } /** - * @param value an Nmtokens value - * * Validate that the given value matches the Nmtokens production. * * [ VC: Name Token ] * + * @param value an Nmtokens value * @returns 1 if valid or 0 otherwise. */ @@ -3533,17 +3487,16 @@ xmlValidateNmtokensValue(const xmlChar *value) { } /** - * @param ctxt the validation context - * @param doc a document instance - * @param nota a notation definition + * Try to validate a single notation definition. * * @deprecated Internal function, don't use. * - * Try to validate a single notation definition. - * * It seems that no validity constraint exists on notation declarations. * But this function gets called anyway ... * + * @param ctxt the validation context + * @param doc a document instance + * @param nota a notation definition * @returns 1 if valid or 0 otherwise. */ @@ -3556,12 +3509,11 @@ xmlValidateNotationDecl(xmlValidCtxtPtr ctxt ATTRIBUTE_UNUSED, xmlDocPtr doc ATT } /** + * Validate that the given attribute value matches the proper production. + * * @param doc the document * @param type an attribute type * @param value an attribute value - * - * Validate that the given attribute value matches the proper production. - * * @returns 1 if valid or 0 otherwise. */ @@ -3589,13 +3541,10 @@ xmlValidateAttributeValueInternal(xmlDocPtr doc, xmlAttributeType type, } /** - * @param type an attribute type - * @param value an attribute value + * Validate that the given attribute value matches the proper production. * * @deprecated Internal function, don't use. * - * Validate that the given attribute value matches the proper production. - * * [ VC: ID ] * Values of type ID must match the Name production.... * @@ -3611,6 +3560,8 @@ xmlValidateAttributeValueInternal(xmlDocPtr doc, xmlAttributeType type, * Values of type NMTOKEN must match the Nmtoken production; values * of type NMTOKENS must match Nmtokens. * + * @param type an attribute type + * @param value an attribute value * @returns 1 if valid or 0 otherwise. */ int @@ -3619,12 +3570,6 @@ xmlValidateAttributeValue(xmlAttributeType type, const xmlChar *value) { } /** - * @param ctxt the validation context - * @param doc the document - * @param name the attribute name (used for error reporting only) - * @param type the attribute type - * @param value the attribute value - * * Validate that the given attribute value matches a given type. * This typically cannot be done before having finished parsing * the subsets. @@ -3643,6 +3588,11 @@ xmlValidateAttributeValue(xmlAttributeType type, const xmlChar *value) { * [ VC: Notation Attributes ] * all notation names in the declaration must be declared. * + * @param ctxt the validation context + * @param doc the document + * @param name the attribute name (used for error reporting only) + * @param type the attribute type + * @param value the attribute value * @returns 1 if valid or 0 otherwise. */ @@ -3741,17 +3691,11 @@ xmlValidateAttributeValue2(xmlValidCtxtPtr ctxt, xmlDocPtr doc, } /** - * @param ctxt the validation context - * @param doc the document - * @param elem the parent - * @param name the attribute name - * @param value the attribute value - * - * @deprecated Internal function, don't use. - * * Performs the validation-related extra step of the normalization * of attribute values: * + * @deprecated Internal function, don't use. + * * If the declared value is not CDATA, then the XML processor must further * process the normalized attribute value by discarding any leading and * trailing space (\#x20) characters, and by replacing sequences of space @@ -3760,6 +3704,11 @@ xmlValidateAttributeValue2(xmlValidCtxtPtr ctxt, xmlDocPtr doc, * Also check VC: Standalone Document Declaration in P32, and update * `ctxt->valid` accordingly * + * @param ctxt the validation context + * @param doc the document + * @param elem the parent + * @param name the attribute name + * @param value the attribute value * @returns a new normalized string if normalization is needed, NULL * otherwise. The caller must free the returned value. */ @@ -3839,21 +3788,20 @@ done: } /** - * @param doc the document - * @param elem the parent - * @param name the attribute name - * @param value the attribute value - * - * @deprecated Internal function, don't use. - * * Performs the validation-related extra step of the normalization * of attribute values: * + * @deprecated Internal function, don't use. + * * If the declared value is not CDATA, then the XML processor must further * process the normalized attribute value by discarding any leading and * trailing space (\#x20) characters, and by replacing sequences of space * (\#x20) characters by single space (\#x20) character. * + * @param doc the document + * @param elem the parent + * @param name the attribute name + * @param value the attribute value * @returns a new normalized string if normalization is needed, NULL * otherwise. The caller must free the returned value. */ @@ -3904,22 +3852,21 @@ xmlValidateAttributeIdCallback(void *payload, void *data, } /** - * @param ctxt the validation context - * @param doc a document instance - * @param attr an attribute definition - * - * @deprecated Internal function, don't use. - * * Try to validate a single attribute definition. * Performs the following checks as described by the * XML-1.0 recommendation: * + * @deprecated Internal function, don't use. + * * - [ VC: Attribute Default Legal ] * - [ VC: Enumeration ] * - [ VC: ID Attribute Default ] * * The ID/IDREF uniqueness and matching are done separately. * + * @param ctxt the validation context + * @param doc a document instance + * @param attr an attribute definition * @returns 1 if valid or 0 otherwise. */ @@ -4035,20 +3982,19 @@ xmlValidateAttributeDecl(xmlValidCtxtPtr ctxt, xmlDocPtr doc, } /** - * @param ctxt the validation context - * @param doc a document instance - * @param elem an element definition - * - * @deprecated Internal function, don't use. - * * Try to validate a single element definition. * Performs the following checks as described by the * XML-1.0 recommendation: * + * @deprecated Internal function, don't use. + * * - [ VC: One ID per Element Type ] * - [ VC: No Duplicate Types ] * - [ VC: Unique Element Type Declaration ] * + * @param ctxt the validation context + * @param doc a document instance + * @param elem an element definition * @returns 1 if valid or 0 otherwise. */ @@ -4160,18 +4106,12 @@ xmlValidateElementDecl(xmlValidCtxtPtr ctxt, xmlDocPtr doc, } /** - * @param ctxt the validation context - * @param doc a document instance - * @param elem an element instance - * @param attr an attribute instance - * @param value the attribute value (without entities processing) - * - * @deprecated Internal function, don't use. - * * Try to validate a single attribute for an element. * Performs the following checks as described by the * XML-1.0 recommendation: * + * @deprecated Internal function, don't use. + * * - [ VC: Attribute Value Type ] * - [ VC: Fixed Attribute Default ] * - [ VC: Entity Name ] @@ -4183,6 +4123,11 @@ xmlValidateElementDecl(xmlValidCtxtPtr ctxt, xmlDocPtr doc, * * ID/IDREF uniqueness and matching are handled separately. * + * @param ctxt the validation context + * @param doc a document instance + * @param elem an element instance + * @param attr an attribute instance + * @param value the attribute value (without entities processing) * @returns 1 if valid or 0 otherwise. */ @@ -4330,19 +4275,12 @@ xmlValidateOneAttribute(xmlValidCtxtPtr ctxt, xmlDocPtr doc, } /** - * @param ctxt the validation context - * @param doc a document instance - * @param elem an element instance - * @param prefix the namespace prefix - * @param ns an namespace declaration instance - * @param value the attribute value (without entities processing) - * - * @deprecated Internal function, don't use. - * * Try to validate a single namespace declaration for an element. * Performs the following checks as described by the * XML-1.0 recommendation: * + * @deprecated Internal function, don't use. + * * - [ VC: Attribute Value Type ] * - [ VC: Fixed Attribute Default ] * - [ VC: Entity Name ] @@ -4354,6 +4292,12 @@ xmlValidateOneAttribute(xmlValidCtxtPtr ctxt, xmlDocPtr doc, * * ID/IDREF uniqueness and matching are handled separately. * + * @param ctxt the validation context + * @param doc a document instance + * @param elem an element instance + * @param prefix the namespace prefix + * @param ns an namespace declaration instance + * @param value the attribute value (without entities processing) * @returns 1 if valid or 0 otherwise. */ @@ -4547,11 +4491,10 @@ xmlNodePtr elem, const xmlChar *prefix, xmlNsPtr ns, const xmlChar *value) { #ifndef LIBXML_REGEXP_ENABLED /** - * @param ctxt the validation context - * @param child the child list - * * Skip ignorable elements w.r.t. the validation process * + * @param ctxt the validation context + * @param child the child list * @returns the first element to consider for validation of the content model */ @@ -4581,10 +4524,9 @@ xmlValidateSkipIgnorable(xmlNodePtr child) { } /** - * @param ctxt the validation context - * * Try to validate the content model of an element internal function * + * @param ctxt the validation context * @returns 1 if valid or 0 ,-1 in case of error, -2 if an entity * reference is found and -3 if the validation succeeded but * the content model is not determinist. @@ -4908,13 +4850,13 @@ analyze: #endif /** + * This will dump the list of elements to the buffer + * Intended just for the debug routine + * * @param buf an output buffer * @param size the size of the buffer * @param node an element * @param glob 1 if one must print the englobing parenthesis, 0 otherwise - * - * This will dump the list of elements to the buffer - * Intended just for the debug routine */ static void xmlSnprintfElements(char *buf, int size, xmlNodePtr node, int glob) { @@ -4990,14 +4932,13 @@ xmlSnprintfElements(char *buf, int size, xmlNodePtr node, int glob) { } /** + * Try to validate the content model of an element + * * @param ctxt the validation context * @param child the child list * @param elemDecl pointer to the element declaration * @param warn emit the error message * @param parent the parent element (for error reporting) - * - * Try to validate the content model of an element - * * @returns 1 if valid or 0 if not and -1 in case of error */ @@ -5297,12 +5238,11 @@ done: } /** + * Check that an element follows \#CDATA. + * * @param ctxt the validation context * @param doc a document instance * @param elem an element instance - * - * Check that an element follows \#CDATA. - * * @returns 1 if valid or 0 otherwise. */ static int @@ -5367,12 +5307,11 @@ done: #ifdef LIBXML_REGEXP_ENABLED /** + * Check if the given node is part of the content model. + * * @param ctxt the validation context * @param cont the mixed content model * @param qname the qualified name as appearing in the serialization - * - * Check if the given node is part of the content model. - * * @returns 1 if yes, 0 if no, -1 in case of error */ static int @@ -5433,14 +5372,13 @@ xmlValidateCheckMixed(xmlValidCtxtPtr ctxt, #endif /* LIBXML_REGEXP_ENABLED */ /** + * Finds a declaration associated to an element in the document. + * * @param ctxt the validation context * @param doc a document instance * @param elem an element instance * @param extsubset pointer, (out) indicate if the declaration was found * in the external subset. - * - * Finds a declaration associated to an element in the document. - * * @returns the pointer to the declaration or NULL if not found. */ static xmlElementPtr @@ -5496,15 +5434,14 @@ xmlValidGetElemDecl(xmlValidCtxtPtr ctxt, xmlDocPtr doc, #ifdef LIBXML_REGEXP_ENABLED /** + * Push a new element start on the validation stack. + * + * @deprecated Internal function, don't use. + * * @param ctxt the validation context * @param doc a document instance * @param elem an element instance * @param qname the qualified name as appearing in the serialization - * - * @deprecated Internal function, don't use. - * - * Push a new element start on the validation stack. - * * @returns 1 if no validation problem was found or 0 otherwise. */ int @@ -5595,14 +5532,13 @@ xmlValidatePushElement(xmlValidCtxtPtr ctxt, xmlDocPtr doc, } /** - * @param ctxt the validation context - * @param data some character data read - * @param len the length of the data + * Check the CData parsed for validation in the current stack. * * @deprecated Internal function, don't use. * - * Check the CData parsed for validation in the current stack. - * + * @param ctxt the validation context + * @param data some character data read + * @param len the length of the data * @returns 1 if no validation problem was found or 0 otherwise. */ int @@ -5667,15 +5603,14 @@ done: } /** + * Pop the element end from the validation stack. + * + * @deprecated Internal function, don't use. + * * @param ctxt the validation context * @param doc a document instance * @param elem an element instance * @param qname the qualified name as appearing in the serialization - * - * @deprecated Internal function, don't use. - * - * Pop the element end from the validation stack. - * * @returns 1 if no validation problem was found or 0 otherwise. */ int @@ -5726,16 +5661,12 @@ xmlValidatePopElement(xmlValidCtxtPtr ctxt, xmlDocPtr doc ATTRIBUTE_UNUSED, #endif /* LIBXML_REGEXP_ENABLED */ /** - * @param ctxt the validation context - * @param doc a document instance - * @param elem an element instance - * - * @deprecated Internal function, don't use. - * * Try to validate a single element and its attributes. * Performs the following checks as described by the * XML-1.0 recommendation: * + * @deprecated Internal function, don't use. + * * - [ VC: Element Valid ] * - [ VC: Required Attribute ] * @@ -5743,6 +5674,9 @@ xmlValidatePopElement(xmlValidCtxtPtr ctxt, xmlDocPtr doc ATTRIBUTE_UNUSED, * * ID/IDREF checks are handled separately. * + * @param ctxt the validation context + * @param doc a document instance + * @param elem an element instance * @returns 1 if valid or 0 otherwise. */ @@ -6058,19 +5992,18 @@ found: } /** - * @param ctxt the validation context - * @param doc a document instance - * - * @deprecated Internal function, don't use. - * * Try to validate the root element. * Performs the following check as described by the * XML-1.0 recommendation: * + * @deprecated Internal function, don't use. + * * - [ VC: Root Element Type ] * * It doesn't try to recurse or apply other checks to the element. * + * @param ctxt the validation context + * @param doc a document instance * @returns 1 if valid or 0 otherwise. */ @@ -6128,12 +6061,11 @@ name_ok: /** + * Try to validate the subtree under an element. + * * @param ctxt the validation context * @param doc a document instance * @param root an element instance - * - * Try to validate the subtree under an element. - * * @returns 1 if valid or 0 otherwise. */ @@ -6287,7 +6219,6 @@ xmlValidateRef(xmlRefPtr ref, xmlValidCtxtPtr ctxt, /** * @param data Contents of current link * @param user Value supplied by the user - * * @returns 0 to abort the walk or 1 to continue. */ static int @@ -6319,18 +6250,17 @@ xmlValidateCheckRefCallback(void *payload, void *data, const xmlChar *name) { } /** - * @param ctxt the validation context - * @param doc a document instance - * - * @deprecated Internal function, don't use. - * * Performs the final step of document validation once all the * incremental validation steps have been completed. * + * @deprecated Internal function, don't use. + * * Performs the following checks described by the XML Rec: * * - Check all the IDREF/IDREFS attributes definition for validity. * + * @param ctxt the validation context + * @param doc a document instance * @returns 1 if valid or 0 otherwise. */ @@ -6379,16 +6309,15 @@ xmlValidateDocumentFinal(xmlValidCtxtPtr ctxt, xmlDocPtr doc) { } /** - * @param ctxt the validation context - * @param doc a document instance - * @param dtd a DTD instance - * * Try to validate the document against the DTD instance. * * Note that the internal subset (if present) is de-coupled * (i.e. not used), which could cause problems if ID or IDREF * attributes are present. * + * @param ctxt the validation context + * @param doc a document instance + * @param dtd a DTD instance * @returns 1 if valid or 0 otherwise. */ @@ -6438,16 +6367,15 @@ xmlValidateDtd(xmlValidCtxtPtr ctxt, xmlDocPtr doc, xmlDtdPtr dtd) { } /** - * @param ctxt a parser context - * @param doc a document instance - * @param dtd a dtd instance - * * Validate a document against a DTD. * * Like xmlValidateDtd() but uses the parser context's error handler. * * @since 2.14.0 * + * @param ctxt a parser context + * @param doc a document instance + * @param dtd a dtd instance * @returns 1 if valid or 0 otherwise. */ int @@ -6569,14 +6497,11 @@ xmlValidateAttributeCallback(void *payload, void *data, } /** - * @param ctxt the validation context - * @param doc a document instance - * - * @deprecated Internal function, don't use. - * * Performs the final validation steps of DTD content once all the * subsets have been parsed. * + * @deprecated Internal function, don't use. + * * Performs the following checks described by the XML Rec: * * - check that ENTITY and ENTITIES type attributes default or @@ -6584,6 +6509,8 @@ xmlValidateAttributeCallback(void *payload, void *data, * - check that NOTATION type attributes default or * possible values matches one of the defined notations. * + * @param ctxt the validation context + * @param doc a document instance * @returns 1 if valid or 0 if invalid and -1 if not well-formed. */ @@ -6620,12 +6547,11 @@ xmlValidateDtdFinal(xmlValidCtxtPtr ctxt, xmlDocPtr doc) { } /** + * Validate a document. + * * @param ctxt parser context (optional) * @param vctxt validation context (optional) * @param doc document - * - * Validate a document. - * * @returns 1 if valid or 0 otherwise. */ static int @@ -6713,18 +6639,17 @@ xmlValidateDocumentInternal(xmlParserCtxtPtr ctxt, xmlValidCtxtPtr vctxt, } /** - * @param vctxt the validation context - * @param doc a document instance + * Try to validate the document instance. * * @deprecated This function can't report malloc or other failures. * Use xmlCtxtValidateDocument(). * - * Try to validate the document instance. - * * Performs the all the checks described by the XML Rec, * i.e. validates the internal and external subset (if present) * and validates the document tree. * + * @param vctxt the validation context + * @param doc a document instance * @returns 1 if valid or 0 otherwise. */ int @@ -6733,9 +6658,6 @@ xmlValidateDocument(xmlValidCtxtPtr vctxt, xmlDocPtr doc) { } /** - * @param ctxt a parser context - * @param doc a document instance - * * Validate a document. * * Like xmlValidateDocument() but uses the parser context's error handler. @@ -6745,6 +6667,8 @@ xmlValidateDocument(xmlValidCtxtPtr vctxt, xmlDocPtr doc) { * * @since 2.14.0 * + * @param ctxt a parser context + * @param doc a document instance * @returns 1 if valid or 0 otherwise. */ int @@ -6764,13 +6688,12 @@ xmlCtxtValidateDocument(xmlParserCtxtPtr ctxt, xmlDocPtr doc) { ************************************************************************/ /** + * Build/extend a list of potential children allowed by the content tree + * * @param ctree an element content tree * @param names an array to store the list of child names * @param len a pointer to the number of element in the list * @param max the size of the array - * - * Build/extend a list of potential children allowed by the content tree - * * @returns the number of element in the list, or -1 in case of error. */ @@ -6816,11 +6739,6 @@ static void xmlNoValidityErr(void *ctx ATTRIBUTE_UNUSED, } /** - * @param prev an element to insert after - * @param next an element to insert next - * @param names an array to store the list of child names - * @param max the size of the array - * * This function returns the list of authorized children to insert * within an existing tree while respecting the validity constraints * forced by the Dtd. The insertion point is defined using `prev` and @@ -6834,6 +6752,10 @@ static void xmlNoValidityErr(void *ctx ATTRIBUTE_UNUSED, * pointers to the element names are inserted at the beginning of the array * and do not need to be freed. * + * @param prev an element to insert after + * @param next an element to insert next + * @param names an array to store the list of child names + * @param max the size of the array * @returns the number of element in the list, or -1 in case of error. If * the function returns the value `max` the caller is invited to grow the * receiving array and retry. diff --git a/xinclude.c b/xinclude.c index 565e6ddd..b5b888f5 100644 --- a/xinclude.c +++ b/xinclude.c @@ -131,9 +131,9 @@ xmlXIncludeDoProcess(xmlXIncludeCtxtPtr ctxt, xmlNodePtr tree); ************************************************************************/ /** - * @param ctxt an XInclude context - * * Handle an out of memory condition + * + * @param ctxt an XInclude context */ static void xmlXIncludeErrMemory(xmlXIncludeCtxtPtr ctxt) @@ -147,13 +147,13 @@ xmlXIncludeErrMemory(xmlXIncludeCtxtPtr ctxt) } /** + * Handle an XInclude error + * * @param ctxt the XInclude context * @param node the context node * @param error the error code * @param msg the error message * @param extra extra information - * - * Handle an XInclude error */ static void LIBXML_ATTR_FORMAT(4,0) xmlXIncludeErr(xmlXIncludeCtxtPtr ctxt, xmlNodePtr node, int error, @@ -202,12 +202,11 @@ xmlXIncludeErr(xmlXIncludeCtxtPtr ctxt, xmlNodePtr node, int error, } /** + * Get an XInclude attribute + * * @param ctxt the XInclude context * @param cur the node * @param name the attribute name - * - * Get an XInclude attribute - * * @returns the value (to be freed) or NULL if not found */ static xmlChar * @@ -232,9 +231,9 @@ xmlXIncludeGetProp(xmlXIncludeCtxtPtr ctxt, xmlNodePtr cur, return(ret); } /** - * @param ref the XInclude reference - * * Free an XInclude reference + * + * @param ref the XInclude reference */ static void xmlXIncludeFreeRef(xmlXIncludeRefPtr ref) { @@ -250,10 +249,9 @@ xmlXIncludeFreeRef(xmlXIncludeRefPtr ref) { } /** - * @param doc an XML Document - * * Creates a new XInclude context * + * @param doc an XML Document * @returns the new set */ xmlXIncludeCtxtPtr @@ -275,9 +273,9 @@ xmlXIncludeNewContext(xmlDocPtr doc) { } /** - * @param ctxt the XInclude context - * * Free an XInclude context + * + * @param ctxt the XInclude context */ void xmlXIncludeFreeContext(xmlXIncludeCtxtPtr ctxt) { @@ -313,10 +311,10 @@ xmlXIncludeFreeContext(xmlXIncludeCtxtPtr ctxt) { } /** + * parse a document for XInclude + * * @param ctxt the XInclude context * @param URL the URL or file path - * - * parse a document for XInclude */ static xmlDocPtr xmlXIncludeParseFile(xmlXIncludeCtxtPtr ctxt, const char *URL) { @@ -389,10 +387,10 @@ error: } /** + * Add a new node to process to an XInclude context + * * @param ctxt the XInclude context * @param cur the new node - * - * Add a new node to process to an XInclude context */ static xmlXIncludeRefPtr xmlXIncludeAddNode(xmlXIncludeCtxtPtr ctxt, xmlNodePtr cur) { @@ -592,10 +590,10 @@ error: } /** + * The XInclude recursive nature is handled at this point. + * * @param ctxt the XInclude context * @param doc the new document - * - * The XInclude recursive nature is handled at this point. */ static void xmlXIncludeRecurseDoc(xmlXIncludeCtxtPtr ctxt, xmlDocPtr doc) { @@ -694,13 +692,12 @@ done: } /** + * Make a copy of the node while expanding nested XIncludes. + * * @param ctxt the XInclude context * @param elem the element * @param copyChildren copy children instead of node if true * @param targetBase the xml:base of the target node - * - * Make a copy of the node while expanding nested XIncludes. - * * @returns a node list, not a single node. */ static xmlNodePtr @@ -816,13 +813,12 @@ error: #ifdef LIBXML_XPTR_ENABLED /** - * @param ctxt the XInclude context - * @param obj the XPointer result from the evaluation. - * @param targetBase the xml:base of the target node - * * Build a node list tree copy of the XPointer result. * This will drop Attributes and Namespace declarations. * + * @param ctxt the XInclude context + * @param obj the XPointer result from the evaluation. + * @param targetBase the xml:base of the target node * @returns an xmlNodePtr list or NULL. * the caller has to free the node tree. */ @@ -914,11 +910,11 @@ struct _xmlXIncludeMergeData { }; /** + * Implements the merge of one entity + * * @param payload the entity * @param vdata the merge data * @param name unused - * - * Implements the merge of one entity */ static void xmlXIncludeMergeEntity(void *payload, void *vdata, @@ -994,12 +990,11 @@ error: } /** + * Implements the entity merge + * * @param ctxt an XInclude context * @param doc the including doc * @param from the included doc - * - * Implements the entity merge - * * @returns 0 if merge succeeded, -1 if some processing failed */ static int @@ -1056,11 +1051,10 @@ xmlXIncludeMergeEntities(xmlXIncludeCtxtPtr ctxt, xmlDocPtr doc, } /** - * @param ctxt the XInclude context - * @param ref an XMLXincludeRefPtr - * * Load the document, and store the result in the XInclude context * + * @param ctxt the XInclude context + * @param ref an XMLXincludeRefPtr * @returns 0 in case of success, -1 in case of failure */ static int @@ -1331,11 +1325,10 @@ error: } /** - * @param ctxt the XInclude context - * @param ref an XMLXincludeRefPtr - * * Load the content, and store the result in the XInclude context * + * @param ctxt the XInclude context + * @param ref an XMLXincludeRefPtr * @returns 0 in case of success, -1 in case of failure */ static int @@ -1528,13 +1521,12 @@ error: } /** - * @param ctxt the XInclude context - * @param fallback the fallback node - * @param ref an XMLXincludeRefPtr - * * Load the content of the fallback node, and store the result * in the XInclude context * + * @param ctxt the XInclude context + * @param fallback the fallback node + * @param ref an XMLXincludeRefPtr * @returns 0 in case of success, -1 in case of failure */ static int @@ -1569,12 +1561,11 @@ xmlXIncludeLoadFallback(xmlXIncludeCtxtPtr ctxt, xmlNodePtr fallback, ************************************************************************/ /** - * @param ctxt an XInclude context - * @param node an XInclude node - * * If the XInclude node wasn't processed yet, create a new RefPtr, * add it to ctxt->incTab and load the included items. * + * @param ctxt an XInclude context + * @param node an XInclude node * @returns the new or existing xmlXIncludeRefPtr, or NULL in case of error. */ static xmlXIncludeRefPtr @@ -1640,11 +1631,10 @@ xmlXIncludeExpandNode(xmlXIncludeCtxtPtr ctxt, xmlNodePtr node) { } /** - * @param ctxt an XInclude context - * @param ref an xmlXIncludeRefPtr - * * Find and load the infoset replacement for the given node. * + * @param ctxt an XInclude context + * @param ref an xmlXIncludeRefPtr * @returns 0 if substitution succeeded, -1 if some processing failed */ static int @@ -1694,11 +1684,10 @@ xmlXIncludeLoadNode(xmlXIncludeCtxtPtr ctxt, xmlXIncludeRefPtr ref) { } /** - * @param ctxt an XInclude context - * @param ref an xmlXIncludeRefPtr - * * Implement the infoset replacement for the given node * + * @param ctxt an XInclude context + * @param ref an xmlXIncludeRefPtr * @returns 0 if substitution succeeded, -1 if some processing failed */ static int @@ -1809,11 +1798,10 @@ err_memory: } /** - * @param ctxt the XInclude processing context - * @param node an XInclude node - * * test if the node is an XInclude node * + * @param ctxt the XInclude processing context + * @param node an XInclude node * @returns 1 true, 0 otherwise */ static int @@ -1879,11 +1867,10 @@ xmlXIncludeTestNode(xmlXIncludeCtxtPtr ctxt, xmlNodePtr node) { } /** - * @param ctxt the XInclude processing context - * @param tree the top of the tree to process - * * Implement the XInclude substitution on the XML document `doc` * + * @param ctxt the XInclude processing context + * @param tree the top of the tree to process * @returns 0 if no substitution were done, -1 if some processing failed * or the number of substitutions done. */ @@ -1961,11 +1948,10 @@ xmlXIncludeDoProcess(xmlXIncludeCtxtPtr ctxt, xmlNodePtr tree) { } /** - * @param ctxt the XInclude processing context - * @param tree the top of the tree to process - * * Implement the XInclude substitution on the XML document `doc` * + * @param ctxt the XInclude processing context + * @param tree the top of the tree to process * @returns 0 if no substitution were done, -1 if some processing failed * or the number of substitutions done. */ @@ -1980,10 +1966,9 @@ xmlXIncludeDoProcessRoot(xmlXIncludeCtxtPtr ctxt, xmlNodePtr tree) { } /** - * @param ctxt an XInclude processing context - * * @since 2.13.0 * + * @param ctxt an XInclude processing context * @returns the last error code. */ int @@ -1994,14 +1979,13 @@ xmlXIncludeGetLastError(xmlXIncludeCtxtPtr ctxt) { } /** - * @param ctxt an XInclude processing context - * @param handler error handler - * @param data user data which will be passed to the handler - * * Register a callback function that will be called on errors and * warnings. If handler is NULL, the error handler will be deactivated. * * @since 2.13.0 + * @param ctxt an XInclude processing context + * @param handler error handler + * @param data user data which will be passed to the handler */ void xmlXIncludeSetErrorHandler(xmlXIncludeCtxtPtr ctxt, @@ -2013,14 +1997,13 @@ xmlXIncludeSetErrorHandler(xmlXIncludeCtxtPtr ctxt, } /** - * @param ctxt an XInclude processing context - * @param loader resource loader - * @param data user data which will be passed to the loader - * * Register a callback function that will be called to load included * documents. * * @since 2.14.0 + * @param ctxt an XInclude processing context + * @param loader resource loader + * @param data user data which will be passed to the loader */ void xmlXIncludeSetResourceLoader(xmlXIncludeCtxtPtr ctxt, @@ -2032,11 +2015,10 @@ xmlXIncludeSetResourceLoader(xmlXIncludeCtxtPtr ctxt, } /** - * @param ctxt an XInclude processing context - * @param flags a set of xmlParserOption used for parsing XML includes - * * Set the flags used for further processing of XML resources. * + * @param ctxt an XInclude processing context + * @param flags a set of xmlParserOption used for parsing XML includes * @returns 0 in case of success and -1 in case of error. */ int @@ -2048,11 +2030,10 @@ xmlXIncludeSetFlags(xmlXIncludeCtxtPtr ctxt, int flags) { } /** - * @param ctxt an XInclude processing context - * @param mode whether streaming mode should be enabled - * * In streaming mode, XPointer expressions aren't allowed. * + * @param ctxt an XInclude processing context + * @param mode whether streaming mode should be enabled * @returns 0 in case of success and -1 in case of error. */ int @@ -2064,13 +2045,12 @@ xmlXIncludeSetStreamingMode(xmlXIncludeCtxtPtr ctxt, int mode) { } /** + * Implement the XInclude substitution on the XML node `tree` + * * @param tree an XML node * @param flags a set of xmlParserOption used for parsing XML includes * @param data application data that will be passed to the parser context * in the _private field of the parser context(s) - * - * Implement the XInclude substitution on the XML node `tree` - * * @returns 0 if no substitution were done, -1 if some processing failed * or the number of substitutions done. */ @@ -2098,13 +2078,12 @@ xmlXIncludeProcessTreeFlagsData(xmlNodePtr tree, int flags, void *data) { } /** + * Implement the XInclude substitution on the XML document `doc` + * * @param doc an XML document * @param flags a set of xmlParserOption used for parsing XML includes * @param data application data that will be passed to the parser context * in the _private field of the parser context(s) - * - * Implement the XInclude substitution on the XML document `doc` - * * @returns 0 if no substitution were done, -1 if some processing failed * or the number of substitutions done. */ @@ -2121,11 +2100,10 @@ xmlXIncludeProcessFlagsData(xmlDocPtr doc, int flags, void *data) { } /** - * @param doc an XML document - * @param flags a set of xmlParserOption used for parsing XML includes - * * Implement the XInclude substitution on the XML document `doc` * + * @param doc an XML document + * @param flags a set of xmlParserOption used for parsing XML includes * @returns 0 if no substitution were done, -1 if some processing failed * or the number of substitutions done. */ @@ -2135,10 +2113,9 @@ xmlXIncludeProcessFlags(xmlDocPtr doc, int flags) { } /** - * @param doc an XML document - * * Implement the XInclude substitution on the XML document `doc` * + * @param doc an XML document * @returns 0 if no substitution were done, -1 if some processing failed * or the number of substitutions done. */ @@ -2148,11 +2125,10 @@ xmlXIncludeProcess(xmlDocPtr doc) { } /** - * @param tree a node in an XML document - * @param flags a set of xmlParserOption used for parsing XML includes - * * Implement the XInclude substitution for the given subtree * + * @param tree a node in an XML document + * @param flags a set of xmlParserOption used for parsing XML includes * @returns 0 if no substitution were done, -1 if some processing failed * or the number of substitutions done. */ @@ -2177,10 +2153,9 @@ xmlXIncludeProcessTreeFlags(xmlNodePtr tree, int flags) { } /** - * @param tree a node in an XML document - * * Implement the XInclude substitution for the given subtree * + * @param tree a node in an XML document * @returns 0 if no substitution were done, -1 if some processing failed * or the number of substitutions done. */ @@ -2190,12 +2165,11 @@ xmlXIncludeProcessTree(xmlNodePtr tree) { } /** - * @param ctxt an existing XInclude context - * @param node a node in an XML document - * * Implement the XInclude substitution for the given subtree reusing * the information and data coming from the given context. * + * @param ctxt an existing XInclude context + * @param node a node in an XML document * @returns 0 if no substitution were done, -1 if some processing failed * or the number of substitutions done. */ diff --git a/xlink.c b/xlink.c index 2126eee5..16ae3203 100644 --- a/xlink.c +++ b/xlink.c @@ -34,10 +34,10 @@ static xlinkHandlerPtr xlinkDefaultHandler = NULL; static xlinkNodeDetectFunc xlinkDefaultDetect = NULL; /** - * @deprecated Don't use. - * * Get the default xlink handler. * + * @deprecated Don't use. + * * @returns the current xlinkHandlerPtr value. */ xlinkHandlerPtr @@ -47,11 +47,11 @@ xlinkGetDefaultHandler(void) { /** - * @param handler the new value for the xlink handler block + * Set the default xlink handlers * * @deprecated Don't use. * - * Set the default xlink handlers + * @param handler the new value for the xlink handler block */ void xlinkSetDefaultHandler(xlinkHandlerPtr handler) { @@ -59,10 +59,10 @@ xlinkSetDefaultHandler(xlinkHandlerPtr handler) { } /** - * @deprecated Don't use. - * * Get the default xlink detection routine * + * @deprecated Don't use. + * * @returns the current function or NULL; */ xlinkNodeDetectFunc @@ -71,11 +71,11 @@ xlinkGetDefaultDetect (void) { } /** - * @param func pointer to the new detection routine. + * Set the default xlink detection routine * * @deprecated Don't use. * - * Set the default xlink detection routine + * @param func pointer to the new detection routine. */ void xlinkSetDefaultDetect (xlinkNodeDetectFunc func) { @@ -90,17 +90,16 @@ xlinkSetDefaultDetect (xlinkNodeDetectFunc func) { /** - * @param doc the document containing the node - * @param node the node pointer itself - * - * @deprecated The XLink code was never finished. - * * Check whether the given node carries the attributes needed * to be a link element (or is one of the linking elements issued * from the (X)HTML DtDs). * This routine don't try to do full checking of the link validity * but tries to detect and return the appropriate link type. * + * @deprecated The XLink code was never finished. + * + * @param doc the document containing the node + * @param node the node pointer itself * @returns the xlinkType of the node (XLINK_TYPE_NONE if there is no * link detected. */ diff --git a/xmlIO.c b/xmlIO.c index 7e400cb7..16b80427 100644 --- a/xmlIO.c +++ b/xmlIO.c @@ -114,10 +114,9 @@ static int xmlOutputCallbackNr; ************************************************************************/ /** - * @param err the error number - * * Convert errno to xmlParserErrors. * + * @param err the error number * @returns an xmlParserErrors code. */ static xmlParserErrors @@ -288,9 +287,9 @@ xmlIOErr(int err) #if defined(_WIN32) /** - * @param u8String uft-8 string - * * Convert a string from utf-8 to wchar (WINDOWS ONLY!) + * + * @param u8String uft-8 string */ static wchar_t * __xmlIOWin32UTF8ToWChar(const char *u8String) @@ -328,10 +327,9 @@ __xmlIOWin32UTF8ToWChar(const char *u8String) #endif /** - * @param path the input file path - * * @deprecated This never really worked. * + * @param path the input file path * @returns a copy of path. */ xmlChar * @@ -341,11 +339,11 @@ xmlNormalizeWindowsPath(const xmlChar *path) } /** - * @param path the path to check + * if stat is not available on the target machine, * * @deprecated Internal function, don't use. * - * if stat is not available on the target machine, + * @param path the path to check * @returns 1. if stat fails, returns 0 (if calling * stat on the filename fails, it can't be right). * if stat succeeds and the file is a directory, @@ -436,7 +434,6 @@ typedef struct { * @param filename the URI for matching * @param write whether the fd is opened for writing * @param out pointer to resulting context - * * @returns an xmlParserErrors code */ static xmlParserErrors @@ -500,12 +497,11 @@ xmlFdOpen(const char *filename, int write, int *out) { } /** + * Read `len` bytes to `buffer` from the I/O channel. + * * @param context the I/O context * @param buffer where to drop data * @param len number of bytes to read - * - * Read `len` bytes to `buffer` from the I/O channel. - * * @returns the number of bytes read */ static int @@ -538,12 +534,11 @@ xmlFdRead(void *context, char *buffer, int len) { #ifdef LIBXML_OUTPUT_ENABLED /** + * Write `len` bytes from `buffer` to the I/O channel. + * * @param context the I/O context * @param buffer where to get data * @param len number of bytes to write - * - * Write `len` bytes from `buffer` to the I/O channel. - * * @returns the number of bytes written */ static int @@ -573,10 +568,9 @@ xmlFdFree(void *context) { } /** - * @param context the I/O context - * * Close an I/O channel * + * @param context the I/O context * @returns 0 in case of success and error code otherwise */ static int @@ -596,10 +590,9 @@ xmlFdClose (void * context) { } /** - * @param filename the URI for matching - * * @deprecated Internal function, don't use. * + * @param filename the URI for matching * @returns 1 if matches, 0 otherwise */ int @@ -608,12 +601,11 @@ xmlFileMatch (const char *filename ATTRIBUTE_UNUSED) { } /** + * input from FILE * + * * @param filename the URI for matching * @param write whether the file is opened for writing * @param out pointer to resulting context - * - * input from FILE * - * * @returns an xmlParserErrors code */ static xmlParserErrors @@ -670,10 +662,9 @@ xmlFileOpenSafe(const char *filename, int write, void **out) { } /** - * @param filename the URI for matching - * * @deprecated Internal function, don't use. * + * @param filename the URI for matching * @returns an IO context or NULL in case or failure */ void * @@ -685,12 +676,11 @@ xmlFileOpen(const char *filename) { } /** + * @deprecated Internal function, don't use. + * * @param context the I/O context * @param buffer where to drop data * @param len number of bytes to write - * - * @deprecated Internal function, don't use. - * * @returns the number of bytes read or < 0 in case of failure */ int @@ -717,12 +707,11 @@ xmlFileRead(void * context, char * buffer, int len) { #ifdef LIBXML_OUTPUT_ENABLED /** + * Write `len` bytes from `buffer` to the I/O channel. + * * @param context the I/O context * @param buffer where to drop data * @param len number of bytes to write - * - * Write `len` bytes from `buffer` to the I/O channel. - * * @returns the number of bytes written */ static int @@ -743,9 +732,9 @@ xmlFileWrite(void *context, const char *buffer, int len) { #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param context the I/O context - * * Flush an I/O channel + * + * @param context the I/O context */ static int xmlFileFlush (void * context) { @@ -761,10 +750,9 @@ xmlFileFlush (void * context) { } /** - * @param context the I/O context - * * @deprecated Internal function, don't use. * + * @param context the I/O context * @returns 0 or -1 an error code case of error */ int @@ -787,12 +775,11 @@ xmlFileClose (void * context) { #ifdef LIBXML_OUTPUT_ENABLED /** + * Write `len` bytes from `buffer` to the xml buffer + * * @param context the xmlBuffer * @param buffer the data to write * @param len number of bytes to write - * - * Write `len` bytes from `buffer` to the xml buffer - * * @returns the number of bytes written or a negative xmlParserErrors * value. */ @@ -815,12 +802,11 @@ xmlBufferWrite (void * context, const char * buffer, int len) { ************************************************************************/ /** + * Read `len` bytes to `buffer` from the compressed I/O channel. + * * @param context the I/O context * @param buffer where to drop data * @param len number of bytes to write - * - * Read `len` bytes to `buffer` from the compressed I/O channel. - * * @returns the number of bytes read. */ static int @@ -835,12 +821,11 @@ xmlGzfileRead (void * context, char * buffer, int len) { #ifdef LIBXML_OUTPUT_ENABLED /** + * Write `len` bytes from `buffer` to the compressed I/O channel. + * * @param context the I/O context * @param buffer where to drop data * @param len number of bytes to write - * - * Write `len` bytes from `buffer` to the compressed I/O channel. - * * @returns the number of bytes written */ static int @@ -855,9 +840,9 @@ xmlGzfileWrite (void * context, const char * buffer, int len) { #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param context the I/O context - * * Close a compressed I/O channel + * + * @param context the I/O context */ static int xmlGzfileClose (void * context) { @@ -878,12 +863,11 @@ xmlGzfileClose (void * context) { #include "private/xzlib.h" /** + * Read `len` bytes to `buffer` from the compressed I/O channel. + * * @param context the I/O context * @param buffer where to drop data * @param len number of bytes to write - * - * Read `len` bytes to `buffer` from the compressed I/O channel. - * * @returns the number of bytes written */ static int @@ -897,9 +881,9 @@ xmlXzfileRead (void * context, char * buffer, int len) { } /** - * @param context the I/O context - * * Close a compressed I/O channel + * + * @param context the I/O context */ static int xmlXzfileClose (void * context) { @@ -921,13 +905,12 @@ xmlIODefaultMatch(const char *filename ATTRIBUTE_UNUSED) { } /** - * @param buf parser input buffer - * @param fd file descriptor - * @param flags flags - * * Update the buffer to read from `fd`. Supports the XML_INPUT_UNZIP * flag. * + * @param buf parser input buffer + * @param fd file descriptor + * @param flags flags * @returns an xmlParserErrors code. */ xmlParserErrors @@ -1038,7 +1021,6 @@ xmlInputFromFd(xmlParserInputBufferPtr buf, int fd, * @param buf input buffer to be filled * @param filename filename or URI * @param flags XML_INPUT flags - * * @returns an xmlParserErrors code. */ static xmlParserErrors @@ -1066,7 +1048,6 @@ xmlInputDefaultOpen(xmlParserInputBufferPtr buf, const char *filename, * @param buf input buffer to be filled * @param filename filename or URI * @param compression compression level or 0 - * * @returns an xmlParserErrors code. */ static xmlParserErrors @@ -1126,16 +1107,15 @@ xmlOutputDefaultOpen(xmlOutputBufferPtr buf, const char *filename, #endif /** - * @param enc the charset encoding if known (deprecated) + * Create a buffered parser input for progressive parsing. * * @deprecated Use xmlNewInputFrom*. * - * Create a buffered parser input for progressive parsing. - * * The encoding argument is deprecated and should be set to * XML_CHAR_ENCODING_NONE. The encoding can be changed with * xmlSwitchEncoding() or xmlSwitchEncodingName() later on. * + * @param enc the charset encoding if known (deprecated) * @returns the new parser input or NULL */ xmlParserInputBufferPtr @@ -1174,12 +1154,11 @@ xmlAllocParserInputBuffer(xmlCharEncoding enc) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param encoder the encoding converter or NULL - * * Create a buffered parser output * * Consumes `encoder` even in error case. * + * @param encoder the encoding converter or NULL * @returns the new parser output or NULL */ xmlOutputBufferPtr @@ -1223,9 +1202,9 @@ xmlAllocOutputBuffer(xmlCharEncodingHandlerPtr encoder) { #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param in a buffered parser input - * * Free up the memory used by a buffered parser input + * + * @param in a buffered parser input */ void xmlFreeParserInputBuffer(xmlParserInputBufferPtr in) { @@ -1251,11 +1230,10 @@ xmlFreeParserInputBuffer(xmlParserInputBufferPtr in) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param out a buffered output - * * flushes and close the output I/O channel * and free up all the associated resources * + * @param out a buffered output * @returns the number of byte written or a negative xmlParserErrors * code in case of error. */ @@ -1310,7 +1288,6 @@ xmlOutputBufferClose(xmlOutputBufferPtr out) * @param enc encoding enum (deprecated) * @param flags XML_INPUT flags * @param out pointer to resulting input buffer - * * @returns an xmlParserErrors code. */ xmlParserErrors @@ -1377,16 +1354,15 @@ __xmlParserInputBufferCreateFilename(const char *URI, xmlCharEncoding enc) { } /** - * @param URI a C string containing the URI or filename - * @param enc the charset encoding if known - * - * @deprecated Use xmlNewInputFromUrl(). - * * 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 * + * @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 @@ -1490,10 +1466,6 @@ error: } /** - * @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). - * * 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 @@ -1501,6 +1473,9 @@ error: * * Consumes `encoder` even in error case. * + * @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 @@ -1515,18 +1490,17 @@ xmlOutputBufferCreateFilename(const char *URI, #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param file a FILE* - * @param enc the charset encoding if known (deprecated) - * - * @deprecated Don't use. - * * Create a buffered parser input for the progressive parsing of a FILE * * buffered C I/O * + * @deprecated Don't use. + * * The encoding argument is deprecated and should be set to * XML_CHAR_ENCODING_NONE. The encoding can be changed with * xmlSwitchEncoding() or xmlSwitchEncodingName() later on. * + * @param file a FILE* + * @param enc the charset encoding if known (deprecated) * @returns the new parser input or NULL */ xmlParserInputBufferPtr @@ -1547,14 +1521,13 @@ xmlParserInputBufferCreateFile(FILE *file, xmlCharEncoding enc) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param file a `FILE *` - * @param encoder the encoding converter or NULL - * * Create a buffered output for the progressive saving to a `FILE *` * buffered C I/O. * * Consumes `encoder` even in error case. * + * @param file a `FILE *` + * @param encoder the encoding converter or NULL * @returns the new parser output or NULL */ xmlOutputBufferPtr @@ -1577,13 +1550,12 @@ xmlOutputBufferCreateFile(FILE *file, xmlCharEncodingHandlerPtr encoder) { } /** - * @param buffer a xmlBufferPtr - * @param encoder the encoding converter or NULL - * * Create a buffered output for the progressive saving to a xmlBuffer * * Consumes `encoder` even in error case. * + * @param buffer a xmlBufferPtr + * @param encoder the encoding converter or NULL * @returns the new parser output or NULL */ xmlOutputBufferPtr @@ -1603,10 +1575,9 @@ xmlOutputBufferCreateBuffer(xmlBufferPtr buffer, } /** - * @param out an xmlOutputBufferPtr - * * Gives a pointer to the data currently held in the output buffer * + * @param out an xmlOutputBufferPtr * @returns a pointer to the data or NULL in case of error */ const xmlChar * @@ -1618,10 +1589,9 @@ xmlOutputBufferGetContent(xmlOutputBufferPtr out) { } /** - * @param out an xmlOutputBufferPtr - * * Gives the length of the data currently held in the output buffer * + * @param out an xmlOutputBufferPtr * @returns 0 in case or error or no data is held, the size otherwise */ size_t @@ -1636,18 +1606,17 @@ xmlOutputBufferGetSize(xmlOutputBufferPtr out) { #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param fd a file descriptor number - * @param enc the charset encoding if known (deprecated) - * - * @deprecated Use xmlNewInputFromFd(). - * * Create a buffered parser input for the progressive parsing for the input * from a file descriptor * + * @deprecated Use xmlNewInputFromFd(). + * * The encoding argument is deprecated and should be set to * XML_CHAR_ENCODING_NONE. The encoding can be changed with * xmlSwitchEncoding() or xmlSwitchEncodingName() later on. * + * @param fd a file descriptor number + * @param enc the charset encoding if known (deprecated) * @returns the new parser input or NULL */ xmlParserInputBufferPtr @@ -1702,13 +1671,12 @@ xmlMemClose(void *vctxt) { } /** + * Create an input buffer for memory. + * * @param mem memory buffer * @param size size of buffer * @param flags flags * @param enc the charset encoding if known (deprecated) - * - * Create an input buffer for memory. - * * @returns the new input buffer or NULL. */ xmlParserInputBufferPtr @@ -1759,14 +1727,10 @@ xmlNewInputBufferMemory(const void *mem, size_t size, } /** - * @param mem the memory input - * @param size the length of the memory block - * @param enc the charset encoding if known (deprecated) + * Create a parser input buffer for parsing from a memory area. * * @deprecated Use xmlNewInputFromMemory(). * - * Create a parser input buffer for parsing from a memory area. - * * This function makes a copy of the whole input buffer. If you are sure * that the contents of the buffer will remain valid until the document * was parsed, you can avoid the copy by using @@ -1776,6 +1740,9 @@ xmlNewInputBufferMemory(const void *mem, size_t size, * XML_CHAR_ENCODING_NONE. The encoding can be changed with * xmlSwitchEncoding() or xmlSwitchEncodingName() later on. * + * @param mem the memory input + * @param size the length of the memory block + * @param enc the charset encoding if known (deprecated) * @returns the new parser input or NULL in case of error. */ xmlParserInputBufferPtr @@ -1787,14 +1754,10 @@ xmlParserInputBufferCreateMem(const char *mem, int size, xmlCharEncoding enc) { } /** - * @param mem the memory input - * @param size the length of the memory block - * @param enc the charset encoding if known + * Create a parser input buffer for parsing from a memory area. * * @deprecated Use xmlNewInputFromMemory(). * - * Create a parser input buffer for parsing from a memory area. - * * This functions assumes that the contents of the input buffer remain * valid until the document was parsed. Use xmlParserInputBufferCreateMem() * otherwise. @@ -1803,6 +1766,9 @@ xmlParserInputBufferCreateMem(const char *mem, int size, xmlCharEncoding enc) { * XML_CHAR_ENCODING_NONE. The encoding can be changed with * xmlSwitchEncoding() or xmlSwitchEncodingName() later on. * + * @param mem the memory input + * @param size the length of the memory block + * @param enc the charset encoding if known * @returns the new parser input or NULL in case of error. */ xmlParserInputBufferPtr @@ -1815,13 +1781,12 @@ xmlParserInputBufferCreateStatic(const char *mem, int size, } /** - * @param str C string - * @param flags flags + * Create an input buffer for a null-terminated C string. * * @deprecated Use xmlNewInputFromString(). * - * Create an input buffer for a null-terminated C string. - * + * @param str C string + * @param flags flags * @returns the new input buffer or NULL. */ xmlParserInputBufferPtr @@ -1846,14 +1811,13 @@ xmlNewInputBufferString(const char *str, xmlParserInputFlags flags) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param fd a file descriptor number - * @param encoder the encoding converter or NULL - * * Create a buffered output for the progressive saving * to a file descriptor * * Consumes `encoder` even in error case. * + * @param fd a file descriptor number + * @param encoder the encoding converter or NULL * @returns the new parser output or NULL */ xmlOutputBufferPtr @@ -1885,20 +1849,19 @@ xmlOutputBufferCreateFd(int fd, xmlCharEncodingHandlerPtr encoder) { #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param ioread an I/O read function - * @param ioclose an I/O close function - * @param ioctx an I/O handler - * @param enc the charset encoding if known (deprecated) - * - * @deprecated Use xmlNewInputFromIO(). - * * Create a buffered parser input for the progressive parsing for the input * from an I/O handler * + * @deprecated Use xmlNewInputFromIO(). + * * The encoding argument is deprecated and should be set to * XML_CHAR_ENCODING_NONE. The encoding can be changed with * xmlSwitchEncoding() or xmlSwitchEncodingName() later on. * + * @param ioread an I/O read function + * @param ioclose an I/O close function + * @param ioctx an I/O handler + * @param enc the charset encoding if known (deprecated) * @returns the new parser input or NULL */ xmlParserInputBufferPtr @@ -1920,16 +1883,15 @@ xmlParserInputBufferCreateIO(xmlInputReadCallback ioread, #ifdef LIBXML_OUTPUT_ENABLED /** - * @param iowrite an I/O write function - * @param ioclose an I/O close function - * @param ioctx an I/O handler - * @param encoder the charset encoding if known - * * Create a buffered output for the progressive saving * to an I/O handler * * Consumes `encoder` even in error case. * + * @param iowrite an I/O write function + * @param ioclose an I/O close function + * @param ioctx an I/O handler + * @param encoder the charset encoding if known * @returns the new parser output or NULL */ xmlOutputBufferPtr @@ -1955,12 +1917,11 @@ xmlOutputBufferCreateIO(xmlOutputWriteCallback iowrite, #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param func function pointer to the new ParserInputBufferCreateFilenameFunc + * Registers a callback for URI input file handling * * @deprecated Use xmlCtxtSetResourceLoader() or similar functions. * - * Registers a callback for URI input file handling - * + * @param func function pointer to the new ParserInputBufferCreateFilenameFunc * @returns the old value of the registration function */ xmlParserInputBufferCreateFilenameFunc @@ -1980,10 +1941,9 @@ xmlParserInputBufferCreateFilenameDefault( } /** - * @param func function pointer to the new OutputBufferCreateFilenameFunc - * * Registers a callback for URI output file handling * + * @param func function pointer to the new OutputBufferCreateFilenameFunc * @returns the old value of the registration function */ xmlOutputBufferCreateFilenameFunc @@ -2000,16 +1960,15 @@ xmlOutputBufferCreateFilenameDefault(xmlOutputBufferCreateFilenameFunc func) } /** - * @param in a buffered parser input - * @param len the size in bytes of the array. - * @param buf an char array - * - * @deprecated Internal function, don't use. - * * Push the content of the arry in the input buffer * This routine handle the I18N transcoding to internal UTF-8 * This is used when operating the parser in progressive (push) mode. * + * @deprecated Internal function, don't use. + * + * @param in a buffered parser input + * @param len the size in bytes of the array. + * @param buf an char array * @returns the number of chars read and stored in the buffer, or -1 * in case of error. */ @@ -2070,15 +2029,14 @@ endOfInput (void * context ATTRIBUTE_UNUSED, } /** - * @param in a buffered parser input - * @param len indicative value of the amount of chars to read - * - * @deprecated Internal function, don't use. - * * Grow up the content of the input buffer, the old data are preserved * This routine handle the I18N transcoding to internal UTF-8 * This routine is used when operating the parser in normal (pull) mode * + * @deprecated Internal function, don't use. + * + * @param in a buffered parser input + * @param len indicative value of the amount of chars to read * @returns the number of chars read and stored in the buffer, or -1 * in case of error. */ @@ -2160,13 +2118,12 @@ xmlParserInputBufferGrow(xmlParserInputBufferPtr in, int len) { } /** - * @param in a buffered parser input - * @param len indicative value of the amount of chars to read + * Same as xmlParserInputBufferGrow(). * * @deprecated Internal function, don't use. * - * Same as xmlParserInputBufferGrow(). - * + * @param in a buffered parser input + * @param len indicative value of the amount of chars to read * @returns the number of chars read and stored in the buffer, or -1 * in case of error. */ @@ -2177,15 +2134,14 @@ xmlParserInputBufferRead(xmlParserInputBufferPtr in, int len) { #ifdef LIBXML_OUTPUT_ENABLED /** - * @param out a buffered parser output - * @param len the size in bytes of the array. - * @param data an char array - * * Write the content of the array in the output I/O buffer * This routine handle the I18N transcoding from internal UTF-8 * The buffer is lossless, i.e. will store in case of partial * or delayed writes. * + * @param out a buffered parser output + * @param len the size in bytes of the array. + * @param data an char array * @returns the number of chars immediately written, or -1 * in case of error. */ @@ -2277,16 +2233,15 @@ xmlOutputBufferWrite(xmlOutputBufferPtr out, int len, const char *data) { } /** - * @param out a buffered parser output - * @param str a zero terminated UTF-8 string - * @param escaping an optional escaping function (or NULL) - * * Write the content of the string in the output I/O buffer * This routine escapes the characters and then handle the I18N * transcoding from internal UTF-8 * The buffer is lossless, i.e. will store in case of partial * or delayed writes. * + * @param out a buffered parser output + * @param str a zero terminated UTF-8 string + * @param escaping an optional escaping function (or NULL) * @returns the number of chars immediately written, or -1 * in case of error. */ @@ -2352,14 +2307,13 @@ xmlOutputBufferWriteEscape(xmlOutputBufferPtr out, const xmlChar *str, } /** - * @param out a buffered parser output - * @param str a zero terminated C string - * * Write the content of the string in the output I/O buffer * This routine handle the I18N transcoding from internal UTF-8 * The buffer is lossless, i.e. will store in case of partial * or delayed writes. * + * @param out a buffered parser output + * @param str a zero terminated C string * @returns the number of chars immediately written, or -1 * in case of error. */ @@ -2378,12 +2332,12 @@ xmlOutputBufferWriteString(xmlOutputBufferPtr out, const char *str) { } /** - * @param buf output buffer - * @param string the string to add - * * routine which manage and grows an output buffer. This one writes * a quoted or double quoted \#xmlChar string, checking first if it holds * quote or double-quotes internally + * + * @param buf output buffer + * @param string the string to add */ void xmlOutputBufferWriteQuotedString(xmlOutputBufferPtr buf, @@ -2427,10 +2381,9 @@ xmlOutputBufferWriteQuotedString(xmlOutputBufferPtr buf, } /** - * @param out a buffered output - * * flushes the output I/O channel * + * @param out a buffered output * @returns the number of byte written or -1 in case of error. */ int @@ -2483,10 +2436,9 @@ xmlOutputBufferFlush(xmlOutputBufferPtr out) { #endif /* LIBXML_OUTPUT_ENABLED */ /** - * @param filename the path to a file - * * lookup the directory for that file * + * @param filename the path to a file * @returns a new allocated string containing the directory, or NULL. */ char * @@ -2522,12 +2474,11 @@ xmlParserGetDirectory(const char *filename) { } /** - * @param filename the path to check + * Like xmlCheckFilename() but handles file URIs. * * @deprecated Internal function, don't use. * - * Like xmlCheckFilename() but handles file URIs. - * + * @param filename the path to check * @returns 0, 1, or 2. */ int @@ -2572,15 +2523,14 @@ xmlInitIOCallbacks(void) } /** + * Register a new set of I/O callback for handling parser input. + * + * @deprecated Use xmlCtxtSetResourceLoader() or similar functions. + * * @param matchFunc the xmlInputMatchCallback * @param openFunc the xmlInputOpenCallback * @param readFunc the xmlInputReadCallback * @param closeFunc the xmlInputCloseCallback - * - * @deprecated Use xmlCtxtSetResourceLoader() or similar functions. - * - * Register a new set of I/O callback for handling parser input. - * * @returns the registered handler number or -1 in case of error */ int @@ -2640,13 +2590,12 @@ xmlCleanupInputCallbacks(void) #ifdef LIBXML_OUTPUT_ENABLED /** + * Register a new set of I/O callback for handling output. + * * @param matchFunc the xmlOutputMatchCallback * @param openFunc the xmlOutputOpenCallback * @param writeFunc the xmlOutputWriteCallback * @param closeFunc the xmlOutputCloseCallback - * - * Register a new set of I/O callback for handling output. - * * @returns the registered handler number or -1 in case of error */ int diff --git a/xmlcatalog.c b/xmlcatalog.c index 32c62899..12d38c2c 100644 --- a/xmlcatalog.c +++ b/xmlcatalog.c @@ -59,10 +59,9 @@ static char *filename = NULL; * * ************************************************************************/ /** - * @param prompt the prompt value - * * Read a string * + * @param prompt the prompt value * @returns a pointer to it or NULL on EOF the caller is expected to * free the returned string. */ diff --git a/xmlmemory.c b/xmlmemory.c index 6cf59277..b71a6aaf 100644 --- a/xmlmemory.c +++ b/xmlmemory.c @@ -56,12 +56,11 @@ typedef struct memnod { #define HDR_2_CLIENT(a) ((void *) (((char *) (a)) + RESERVE_SIZE)) /** + * @deprecated don't use + * * @param size an int specifying the size in byte to allocate. * @param file the file name or NULL * @param line the line number - * - * @deprecated don't use - * * @returns a pointer to the allocated area or NULL in case of lack of memory. */ void * @@ -72,12 +71,11 @@ xmlMallocLoc(size_t size, const char *file ATTRIBUTE_UNUSED, } /** + * @deprecated don't use + * * @param size an unsigned int specifying the size in byte to allocate. * @param file the file name or NULL * @param line the line number - * - * @deprecated don't use - * * @returns a pointer to the allocated area or NULL in case of lack of memory. */ void * @@ -88,10 +86,9 @@ xmlMallocAtomicLoc(size_t size, const char *file ATTRIBUTE_UNUSED, } /** - * @param size an int specifying the size in byte to allocate. - * * a malloc() equivalent, with logging of the allocation info. * + * @param size an int specifying the size in byte to allocate. * @returns a pointer to the allocated area or NULL in case of lack of memory. */ void * @@ -119,13 +116,12 @@ xmlMemMalloc(size_t size) } /** + * @deprecated don't use + * * @param ptr the initial memory block pointer * @param size an int specifying the size in byte to allocate. * @param file the file name or NULL * @param line the line number - * - * @deprecated don't use - * * @returns a pointer to the allocated area or NULL in case of lack of memory. */ void * @@ -136,11 +132,10 @@ xmlReallocLoc(void *ptr, size_t size, const char *file ATTRIBUTE_UNUSED, } /** - * @param ptr the initial memory block pointer - * @param size an int specifying the size in byte to allocate. - * * a realloc() equivalent, with logging of the allocation info. * + * @param ptr the initial memory block pointer + * @param size an int specifying the size in byte to allocate. * @returns a pointer to the allocated area or NULL in case of lack of memory. */ void * @@ -182,9 +177,9 @@ xmlMemRealloc(void *ptr, size_t size) { } /** - * @param ptr the memory block pointer - * * a free() equivalent, with error checking. + * + * @param ptr the memory block pointer */ void xmlMemFree(void *ptr) @@ -216,12 +211,11 @@ xmlMemFree(void *ptr) } /** + * @deprecated don't use + * * @param str the initial string pointer * @param file the file name or NULL * @param line the line number - * - * @deprecated don't use - * * @returns a pointer to the new string or NULL if allocation error occurred. */ char * @@ -232,10 +226,9 @@ xmlMemStrdupLoc(const char *str, const char *file ATTRIBUTE_UNUSED, } /** - * @param str the initial string pointer - * * a strdup() equivalent, with logging of the allocation info. * + * @param str the initial string pointer * @returns a pointer to the new string or NULL if allocation error occurred. */ char * @@ -269,7 +262,6 @@ xmlMemoryStrdup(const char *str) { /** * @param ptr pointer to the memory allocation - * * @returns the size of a memory allocation. */ @@ -315,10 +307,9 @@ xmlMemBlocks(void) { } /** + * @deprecated This feature was removed. * @param fp a FILE descriptor * @param nbBytes the amount of memory to dump - * - * @deprecated This feature was removed. */ void xmlMemDisplayLast(FILE *fp ATTRIBUTE_UNUSED, long nbBytes ATTRIBUTE_UNUSED) @@ -326,9 +317,8 @@ xmlMemDisplayLast(FILE *fp ATTRIBUTE_UNUSED, long nbBytes ATTRIBUTE_UNUSED) } /** - * @param fp a FILE descriptor - * * @deprecated This feature was removed. + * @param fp a FILE descriptor */ void xmlMemDisplay(FILE *fp ATTRIBUTE_UNUSED) @@ -336,10 +326,9 @@ xmlMemDisplay(FILE *fp ATTRIBUTE_UNUSED) } /** + * @deprecated This feature was removed. * @param fp a FILE descriptor * @param nr number of entries to dump - * - * @deprecated This feature was removed. */ void xmlMemShow(FILE *fp ATTRIBUTE_UNUSED, int nr ATTRIBUTE_UNUSED) @@ -409,17 +398,16 @@ xmlCleanupMemoryInternal(void) { } /** - * @param freeFunc the free() function to use - * @param mallocFunc the malloc() function to use - * @param reallocFunc the realloc() function to use - * @param strdupFunc the strdup() function to use - * * Override the default memory access functions with a new set * This has to be called before any other libxml routines ! * * Should this be blocked if there was already some allocations * done ? * + * @param freeFunc the free() function to use + * @param mallocFunc the malloc() function to use + * @param reallocFunc the realloc() function to use + * @param strdupFunc the strdup() function to use * @returns 0 on success */ int @@ -442,13 +430,12 @@ xmlMemSetup(xmlFreeFunc freeFunc, xmlMallocFunc mallocFunc, } /** + * Provides the memory access functions set currently in use + * * @param freeFunc place to save the free() function in use * @param mallocFunc place to save the malloc() function in use * @param reallocFunc place to save the realloc() function in use * @param strdupFunc place to save the strdup() function in use - * - * Provides the memory access functions set currently in use - * * @returns 0 on success */ int @@ -462,22 +449,21 @@ xmlMemGet(xmlFreeFunc *freeFunc, xmlMallocFunc *mallocFunc, } /** - * @param freeFunc the free() function to use - * @param mallocFunc the malloc() function to use - * @param mallocAtomicFunc the malloc() function to use for atomic allocations - * @param reallocFunc the realloc() function to use - * @param strdupFunc the strdup() function to use - * - * @deprecated Use xmlMemSetup(). - * * Override the default memory access functions with a new set * This has to be called before any other libxml routines ! * The mallocAtomicFunc is specialized for atomic block * allocations (i.e. of areas useful for garbage collected memory allocators * + * @deprecated Use xmlMemSetup(). + * * Should this be blocked if there was already some allocations * done ? * + * @param freeFunc the free() function to use + * @param mallocFunc the malloc() function to use + * @param mallocAtomicFunc the malloc() function to use for atomic allocations + * @param reallocFunc the realloc() function to use + * @param strdupFunc the strdup() function to use * @returns 0 on success */ int @@ -503,18 +489,17 @@ xmlGcMemSetup(xmlFreeFunc freeFunc, xmlMallocFunc mallocFunc, } /** + * Provides the memory access functions set currently in use + * The mallocAtomicFunc is specialized for atomic block + * allocations (i.e. of areas useful for garbage collected memory allocators + * + * @deprecated xmlMemGet(). + * * @param freeFunc place to save the free() function in use * @param mallocFunc place to save the malloc() function in use * @param mallocAtomicFunc place to save the atomic malloc() function in use * @param reallocFunc place to save the realloc() function in use * @param strdupFunc place to save the strdup() function in use - * - * @deprecated xmlMemGet(). - * - * Provides the memory access functions set currently in use - * The mallocAtomicFunc is specialized for atomic block - * allocations (i.e. of areas useful for garbage collected memory allocators - * * @returns 0 on success */ int diff --git a/xmlmodule.c b/xmlmodule.c index 4e0dc788..b8eb5ff5 100644 --- a/xmlmodule.c +++ b/xmlmodule.c @@ -42,9 +42,6 @@ static int xmlModulePlatformSymbol(void *handle, const char *name, void **result ************************************************************************/ /** - * @param name the module name - * @param options a set of xmlModuleOption - * * Opens a module/shared library given its name or path * NOTE: that due to portability issues, behaviour can only be * guaranteed with `name` using ASCII. We cannot guarantee that @@ -52,6 +49,8 @@ static int xmlModulePlatformSymbol(void *handle, const char *name, void **result * and not a const xmlChar * . * TODO: options are not yet implemented. * + * @param name the module name + * @param options a set of xmlModuleOption * @returns a handle for the module or NULL in case of error */ xmlModulePtr @@ -77,16 +76,15 @@ xmlModuleOpen(const char *name, int options ATTRIBUTE_UNUSED) } /** - * @param module the module - * @param name the name of the symbol - * @param symbol the resulting symbol address - * * Lookup for a symbol address in the given module * NOTE: that due to portability issues, behaviour can only be * guaranteed with `name` using ASCII. We cannot guarantee that * an UTF-8 string would work, which is why name is a const char * * and not a const xmlChar * . * + * @param module the module + * @param name the name of the symbol + * @param symbol the resulting symbol address * @returns 0 if the symbol was found, or -1 in case of error */ int @@ -106,11 +104,10 @@ xmlModuleSymbol(xmlModulePtr module, const char *name, void **symbol) } /** - * @param module the module handle - * * The close operations unload the associated module and free the * data associated to the module. * + * @param module the module handle * @returns 0 in case of success, -1 in case of argument error and -2 * if the module could not be closed/unloaded. */ @@ -132,12 +129,11 @@ xmlModuleClose(xmlModulePtr module) } /** - * @param module the module handle - * * The free operations free the data associated to the module * but does not unload the associated shared library which may still * be in use. * + * @param module the module handle * @returns 0 in case of success, -1 in case of argument error */ int @@ -161,7 +157,6 @@ xmlModuleFree(xmlModulePtr module) /** * @param name path to the module - * * @returns a handle on success, and zero on error. */ diff --git a/xmlreader.c b/xmlreader.c index 61759a7e..9f5eca40 100644 --- a/xmlreader.c +++ b/xmlreader.c @@ -175,10 +175,10 @@ static int xmlTextReaderReadTree(xmlTextReaderPtr reader); static int xmlTextReaderNextTree(xmlTextReaderPtr reader); /** - * @param str a string - * * Free a string if it is not owned by the "dict" dictionary in the * current scope + * + * @param str a string */ #define DICT_FREE(str) \ if ((str) && ((!dict) || \ @@ -263,10 +263,10 @@ constQString(xmlTextReaderPtr reader, const xmlChar *prefix, ************************************************************************/ /** + * Free a node. + * * @param reader the xmlTextReaderPtr used * @param cur the node - * - * Free a node. */ static void xmlTextReaderFreeProp(xmlTextReaderPtr reader, xmlAttrPtr cur) { @@ -308,10 +308,10 @@ xmlTextReaderFreeProp(xmlTextReaderPtr reader, xmlAttrPtr cur) { } /** + * Free a property and all its siblings, all the children are freed too. + * * @param reader the xmlTextReaderPtr used * @param cur the first property in the list - * - * Free a property and all its siblings, all the children are freed too. */ static void xmlTextReaderFreePropList(xmlTextReaderPtr reader, xmlAttrPtr cur) { @@ -325,11 +325,11 @@ xmlTextReaderFreePropList(xmlTextReaderPtr reader, xmlAttrPtr cur) { } /** - * @param reader the xmlTextReaderPtr used - * @param cur the first node in the list - * * Free a node and all its siblings, this is a recursive behaviour, all * the children are freed too. + * + * @param reader the xmlTextReaderPtr used + * @param cur the first node in the list */ static void xmlTextReaderFreeNodeList(xmlTextReaderPtr reader, xmlNodePtr cur) { @@ -419,11 +419,11 @@ xmlTextReaderFreeNodeList(xmlTextReaderPtr reader, xmlNodePtr cur) { } /** - * @param reader the xmlTextReaderPtr used - * @param cur the node - * * Free a node, this is a recursive behaviour, all the children are freed too. * This doesn't unlink the child from the list, use xmlUnlinkNode() first. + * + * @param reader the xmlTextReaderPtr used + * @param cur the node */ static void xmlTextReaderFreeNode(xmlTextReaderPtr reader, xmlNodePtr cur) { @@ -494,10 +494,10 @@ xmlTextReaderFreeNode(xmlTextReaderPtr reader, xmlNodePtr cur) { } /** + * Free up all the structures used by a document, tree included. + * * @param reader the xmlTextReaderPtr used * @param cur pointer to the document - * - * Free up all the structures used by a document, tree included. */ static void xmlTextReaderFreeDoc(xmlTextReaderPtr reader, xmlDocPtr cur) { @@ -577,11 +577,10 @@ xmlTextReaderStructuredRelay(void *userData, const xmlError *error) } /** - * @param reader the xmlTextReaderPtr used - * @param value the entity reference node - * * Pushes a new entity reference node on top of the entities stack * + * @param reader the xmlTextReaderPtr used + * @param value the entity reference node * @returns -1 in case of error, the index in the stack otherwise */ static int @@ -611,10 +610,9 @@ xmlTextReaderEntPush(xmlTextReaderPtr reader, xmlNodePtr value) } /** - * @param reader the xmlTextReaderPtr used - * * Pops the top element entity from the entities stack * + * @param reader the xmlTextReaderPtr used * @returns the entity just removed */ static xmlNodePtr @@ -635,11 +633,11 @@ xmlTextReaderEntPop(xmlTextReaderPtr reader) } /** + * called when an opening tag has been processed. + * * @param ctx the user data (XML parser context) * @param fullname The element name, including namespace prefix * @param atts An array of name/value attributes pairs, NULL terminated - * - * called when an opening tag has been processed. */ static void xmlTextReaderStartElement(void *ctx, const xmlChar *fullname, @@ -659,10 +657,10 @@ xmlTextReaderStartElement(void *ctx, const xmlChar *fullname, } /** + * called when an ending tag has been processed. + * * @param ctx the user data (XML parser context) * @param fullname The element name, including namespace prefix - * - * called when an ending tag has been processed. */ static void xmlTextReaderEndElement(void *ctx, const xmlChar *fullname) { @@ -675,6 +673,8 @@ xmlTextReaderEndElement(void *ctx, const xmlChar *fullname) { } /** + * called when an opening tag has been processed. + * * @param ctx the user data (XML parser context) * @param localname the local name of the element * @param prefix the element namespace prefix if available @@ -685,8 +685,6 @@ xmlTextReaderEndElement(void *ctx, const xmlChar *fullname) { * @param nb_defaulted the number of defaulted attributes. * @param attributes pointer to the array of (localname/prefix/URI/value/end) * attribute values. - * - * called when an opening tag has been processed. */ static void xmlTextReaderStartElementNs(void *ctx, @@ -716,12 +714,12 @@ xmlTextReaderStartElementNs(void *ctx, } /** + * called when an ending tag has been processed. + * * @param ctx the user data (XML parser context) * @param localname the local name of the element * @param prefix the element namespace prefix if available * @param URI the element namespace name if available - * - * called when an ending tag has been processed. */ static void xmlTextReaderEndElementNs(void *ctx, @@ -739,11 +737,11 @@ xmlTextReaderEndElementNs(void *ctx, /** + * receiving some chars from the parser. + * * @param ctx the user data (XML parser context) * @param ch a xmlChar string * @param len the number of xmlChar - * - * receiving some chars from the parser. */ static void xmlTextReaderCharacters(void *ctx, const xmlChar *ch, int len) @@ -757,11 +755,11 @@ xmlTextReaderCharacters(void *ctx, const xmlChar *ch, int len) } /** + * called when a pcdata block has been parsed + * * @param ctx the user data (XML parser context) * @param ch The pcdata content * @param len the block length - * - * called when a pcdata block has been parsed */ static void xmlTextReaderCDataBlock(void *ctx, const xmlChar *ch, int len) @@ -775,11 +773,10 @@ xmlTextReaderCDataBlock(void *ctx, const xmlChar *ch, int len) } /** - * @param reader the xmlTextReaderPtr used - * * Push data down the progressive parser until a significant callback * got raised. * + * @param reader the xmlTextReaderPtr used * @returns -1 in case of failure, 0 otherwise */ static int @@ -885,9 +882,9 @@ xmlTextReaderPushData(xmlTextReaderPtr reader) { #ifdef LIBXML_REGEXP_ENABLED /** - * @param reader the xmlTextReaderPtr used - * * Push the current node for validation + * + * @param reader the xmlTextReaderPtr used */ static int xmlTextReaderValidatePush(xmlTextReaderPtr reader) { @@ -952,11 +949,11 @@ xmlTextReaderValidatePush(xmlTextReaderPtr reader) { } /** + * Push some CData for validation + * * @param reader the xmlTextReaderPtr used * @param data pointer to the CData * @param len length of the CData block in bytes. - * - * Push some CData for validation */ static void xmlTextReaderValidateCData(xmlTextReaderPtr reader, @@ -982,9 +979,9 @@ xmlTextReaderValidateCData(xmlTextReaderPtr reader, } /** - * @param reader the xmlTextReaderPtr used - * * Pop the current node from validation + * + * @param reader the xmlTextReaderPtr used */ static int xmlTextReaderValidatePop(xmlTextReaderPtr reader) { @@ -1039,11 +1036,11 @@ xmlTextReaderValidatePop(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Handle the validation when an entity reference is encountered and * entity substitution is not activated. As a result the parser interface * must walk through the entity and do the validation calls + * + * @param reader the xmlTextReaderPtr used */ static int xmlTextReaderValidateEntity(xmlTextReaderPtr reader) { @@ -1134,10 +1131,9 @@ skip_children: /** - * @param cur the current node - * * Get the successor of a node if available. * + * @param cur the current node * @returns the successor node or NULL */ static xmlNodePtr @@ -1153,12 +1149,11 @@ xmlTextReaderGetSuccessor(xmlNodePtr cur) { } /** - * @param reader the xmlTextReaderPtr used - * * Makes sure that the current node is fully read as well as all its * descendant. It means the full DOM subtree must be available at the * end of the call. * + * @param reader the xmlTextReaderPtr used * @returns 1 if the node was expanded successfully, 0 if there is no more * nodes to read, or -1 in case of error */ @@ -1189,11 +1184,10 @@ xmlTextReaderDoExpand(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Moves the position of the current instance to the next node in * the stream, exposing its properties. * + * @param reader the xmlTextReaderPtr used * @returns 1 if the node was read successfully, 0 if there is no more * nodes to read, or -1 in case of error */ @@ -1549,10 +1543,9 @@ node_end: } /** - * @param reader the xmlTextReaderPtr used - * * Gets the read state of the reader. * + * @param reader the xmlTextReaderPtr used * @returns the state value, or -1 in case of error */ int @@ -1563,11 +1556,10 @@ xmlTextReaderReadState(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Reads the contents of the current node and the full subtree. It then makes * the subtree available until the next xmlTextReaderRead() call * + * @param reader the xmlTextReaderPtr used * @returns a node pointer valid until the next xmlTextReaderRead() call * or NULL in case of error. */ @@ -1585,11 +1577,10 @@ xmlTextReaderExpand(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Skip to the node following the current one in document order while * avoiding the subtree if any. * + * @param reader the xmlTextReaderPtr used * @returns 1 if the node was read successfully, 0 if there is no more * nodes to read, or -1 in case of error */ @@ -1650,10 +1641,9 @@ xmlTextReaderDumpCopy(xmlTextReaderPtr reader, xmlOutputBufferPtr output, } /** - * @param reader the xmlTextReaderPtr used - * * Reads the contents of the current node, including child nodes and markup. * + * @param reader the xmlTextReaderPtr used * @returns a string containing the XML content, or NULL if the current node * is neither an element nor attribute, or has no child nodes. The * string must be deallocated by the caller. @@ -1690,10 +1680,9 @@ xmlTextReaderReadInnerXml(xmlTextReaderPtr reader) } /** - * @param reader the xmlTextReaderPtr used - * * Reads the contents of the current node, including child nodes and markup. * + * @param reader the xmlTextReaderPtr used * @returns a string containing the node and any XML content, or NULL if the * current node cannot be serialized. The string must be deallocated * by the caller. @@ -1730,10 +1719,9 @@ xmlTextReaderReadOuterXml(xmlTextReaderPtr reader) #endif /** - * @param reader the xmlTextReaderPtr used - * * Reads the contents of an element or a text node as a string. * + * @param reader the xmlTextReaderPtr used * @returns a string containing the contents of the non-empty Element or * Text node (including CDATA sections), or NULL if the reader * is positioned on any other type of node. @@ -1875,11 +1863,10 @@ xmlTextReaderNextTree(xmlTextReaderPtr reader) } /** - * @param reader the xmlTextReaderPtr used - * * Moves the position of the current instance to the next node in * the stream, exposing its properties. * + * @param reader the xmlTextReaderPtr used * @returns 1 if the node was read successfully, 0 if there is no more * nodes to read, or -1 in case of error */ @@ -1947,12 +1934,11 @@ found_node: } /** - * @param reader the xmlTextReaderPtr used - * * Skip to the node following the current one in document order while * avoiding the subtree if any. * Currently implemented only for Readers built on a document * + * @param reader the xmlTextReaderPtr used * @returns 1 if the node was read successfully, 0 if there is no more * nodes to read, or -1 in case of error */ @@ -1986,11 +1972,10 @@ xmlTextReaderNextSibling(xmlTextReaderPtr reader) { * * ************************************************************************/ /** - * @param input the xmlParserInputBufferPtr used to read data - * @param URI the URI information for the source if available - * * Create an xmlTextReader structure fed with `input` * + * @param input the xmlParserInputBufferPtr used to read data + * @param URI the URI information for the source if available * @returns the new xmlTextReaderPtr or NULL in case of error */ xmlTextReaderPtr @@ -2087,10 +2072,9 @@ xmlNewTextReader(xmlParserInputBufferPtr input, const char *URI) { } /** - * @param URI the URI of the resource to process - * * Create an xmlTextReader structure fed with the resource at `URI` * + * @param URI the URI of the resource to process * @returns the new xmlTextReaderPtr or NULL in case of error */ xmlTextReaderPtr @@ -2130,9 +2114,9 @@ xmlNewTextReaderFilename(const char *URI) { } /** - * @param reader the xmlTextReaderPtr - * * Deallocate all the resources associated to the reader + * + * @param reader the xmlTextReaderPtr */ void xmlFreeTextReader(xmlTextReaderPtr reader) { @@ -2204,11 +2188,10 @@ xmlFreeTextReader(xmlTextReaderPtr reader) { ************************************************************************/ /** - * @param reader the xmlTextReaderPtr used - * * This method releases any resources allocated by the current instance * changes the state to Closed and close any underlying input. * + * @param reader the xmlTextReaderPtr used * @returns 0 or -1 in case of error */ int @@ -2250,12 +2233,11 @@ xmlTextReaderClose(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * @param no the zero-based index of the attribute relative to the containing element - * * Provides the value of the attribute with the specified index relative * to the containing element. * + * @param reader the xmlTextReaderPtr used + * @param no the zero-based index of the attribute relative to the containing element * @returns a string containing the value of the specified attribute, or NULL * in case of error. The string must be deallocated by the caller. */ @@ -2302,11 +2284,10 @@ xmlTextReaderGetAttributeNo(xmlTextReaderPtr reader, int no) { } /** - * @param reader the xmlTextReaderPtr used - * @param name the qualified name of the attribute. - * * Provides the value of the attribute with the specified qualified name. * + * @param reader the xmlTextReaderPtr used + * @param name the qualified name of the attribute. * @returns a string containing the value of the specified attribute, or NULL * in case of error. The string must be deallocated by the caller. */ @@ -2386,12 +2367,11 @@ xmlTextReaderGetAttribute(xmlTextReaderPtr reader, const xmlChar *name) { /** + * Provides the value of the specified attribute + * * @param reader the xmlTextReaderPtr used * @param localName the local name of the attribute. * @param namespaceURI the namespace URI of the attribute. - * - * Provides the value of the specified attribute - * * @returns a string containing the value of the specified attribute, or NULL * in case of error. The string must be deallocated by the caller. */ @@ -2437,8 +2417,6 @@ xmlTextReaderGetAttributeNs(xmlTextReaderPtr reader, const xmlChar *localName, } /** - * @param reader the xmlTextReaderPtr used - * * Method to get the remainder of the buffered XML. this method stops the * parser, set its state to End Of File and return the input stream with * what is left that the parser did not use. @@ -2447,6 +2425,7 @@ xmlTextReaderGetAttributeNs(xmlTextReaderPtr reader, const xmlChar *localName, * what's left in reader->input, and there is an allocation problem. Best * would be to rewrite it differently. * + * @param reader the xmlTextReaderPtr used * @returns the xmlParserInputBufferPtr attached to the XML or NULL * in case of error. */ @@ -2487,12 +2466,11 @@ xmlTextReaderGetRemainder(xmlTextReaderPtr reader) { } /** + * Resolves a namespace prefix in the scope of the current element. + * * @param reader the xmlTextReaderPtr used * @param prefix the prefix whose namespace URI is to be resolved. To return * the default namespace, specify NULL - * - * Resolves a namespace prefix in the scope of the current element. - * * @returns a string containing the namespace URI to which the prefix maps * or NULL in case of error. The string must be deallocated by the caller. */ @@ -2517,13 +2495,12 @@ xmlTextReaderLookupNamespace(xmlTextReaderPtr reader, const xmlChar *prefix) { } /** - * @param reader the xmlTextReaderPtr used - * @param no the zero-based index of the attribute relative to the containing - * element. - * * Moves the position of the current instance to the attribute with * the specified index relative to the containing element. * + * @param reader the xmlTextReaderPtr used + * @param no the zero-based index of the attribute relative to the containing + * element. * @returns 1 in case of success, -1 in case of error, 0 if not found */ int @@ -2566,12 +2543,11 @@ xmlTextReaderMoveToAttributeNo(xmlTextReaderPtr reader, int no) { } /** - * @param reader the xmlTextReaderPtr used - * @param name the qualified name of the attribute. - * * Moves the position of the current instance to the attribute with * the specified qualified name. * + * @param reader the xmlTextReaderPtr used + * @param name the qualified name of the attribute. * @returns 1 in case of success, -1 in case of error, 0 if not found */ int @@ -2668,13 +2644,12 @@ found: } /** - * @param reader the xmlTextReaderPtr used - * @param localName the local name of the attribute. - * @param namespaceURI the namespace URI of the attribute. - * * Moves the position of the current instance to the attribute with the * specified local name and namespace URI. * + * @param reader the xmlTextReaderPtr used + * @param localName the local name of the attribute. + * @param namespaceURI the namespace URI of the attribute. * @returns 1 in case of success, -1 in case of error, 0 if not found */ int @@ -2728,11 +2703,10 @@ xmlTextReaderMoveToAttributeNs(xmlTextReaderPtr reader, } /** - * @param reader the xmlTextReaderPtr used - * * Moves the position of the current instance to the first attribute * associated with the current node. * + * @param reader the xmlTextReaderPtr used * @returns 1 in case of success, -1 in case of error, 0 if not found */ int @@ -2756,11 +2730,10 @@ xmlTextReaderMoveToFirstAttribute(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Moves the position of the current instance to the next attribute * associated with the current node. * + * @param reader the xmlTextReaderPtr used * @returns 1 in case of success, -1 in case of error, 0 if not found */ int @@ -2794,11 +2767,10 @@ xmlTextReaderMoveToNextAttribute(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Moves the position of the current instance to the node that * contains the current Attribute node. * + * @param reader the xmlTextReaderPtr used * @returns 1 in case of success, -1 in case of error, 0 if not moved */ int @@ -2817,10 +2789,9 @@ xmlTextReaderMoveToElement(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Parses an attribute value into one or more Text and EntityReference nodes. * + * @param reader the xmlTextReaderPtr used * @returns 1 in case of success, 0 if the reader was not positioned on an * attribute node or all the attribute values have been read, or -1 * in case of error. @@ -2872,10 +2843,9 @@ xmlTextReaderReadAttributeValue(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Determine the encoding of the document being read. * + * @param reader the xmlTextReaderPtr used * @returns a string containing the encoding of the document or NULL in * case of error. The string is deallocated with the reader. */ @@ -2901,10 +2871,9 @@ xmlTextReaderConstEncoding(xmlTextReaderPtr reader) { * * ************************************************************************/ /** - * @param reader the xmlTextReaderPtr used - * * Provides the number of attributes of the current node * + * @param reader the xmlTextReaderPtr used * @returns 0 i no attributes, -1 in case of error or the attribute count */ int @@ -2944,12 +2913,11 @@ xmlTextReaderAttributeCount(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Get the node type of the current node * Reference: * http://www.gnu.org/software/dotgnu/pnetlib-doc/System/Xml/XmlNodeType.html * + * @param reader the xmlTextReaderPtr used * @returns the xmlReaderTypes of the current node or -1 in case of error */ int @@ -3014,10 +2982,9 @@ xmlTextReaderNodeType(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Check if the current node is empty * + * @param reader the xmlTextReaderPtr used * @returns 1 if empty, 0 if not and -1 in case of error */ int @@ -3042,10 +3009,9 @@ xmlTextReaderIsEmptyElement(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The local name of the node. * + * @param reader the xmlTextReaderPtr used * @returns the local name or NULL if not available, * if non NULL it need to be freed by the caller. */ @@ -3072,10 +3038,9 @@ xmlTextReaderLocalName(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The local name of the node. * + * @param reader the xmlTextReaderPtr used * @returns the local name or NULL if not available, the * string will be deallocated with the reader. */ @@ -3102,10 +3067,9 @@ xmlTextReaderConstLocalName(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The qualified name of the node, equal to Prefix :LocalName. * + * @param reader the xmlTextReaderPtr used * @returns the local name or NULL if not available, * if non NULL it need to be freed by the caller. */ @@ -3174,10 +3138,9 @@ xmlTextReaderName(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The qualified name of the node, equal to Prefix :LocalName. * + * @param reader the xmlTextReaderPtr used * @returns the local name or NULL if not available, the string is * deallocated with the reader. */ @@ -3238,10 +3201,9 @@ xmlTextReaderConstName(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * A shorthand reference to the namespace associated with the node. * + * @param reader the xmlTextReaderPtr used * @returns the prefix or NULL if not available, * if non NULL it need to be freed by the caller. */ @@ -3269,10 +3231,9 @@ xmlTextReaderPrefix(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * A shorthand reference to the namespace associated with the node. * + * @param reader the xmlTextReaderPtr used * @returns the prefix or NULL if not available, the string is deallocated * with the reader. */ @@ -3300,10 +3261,9 @@ xmlTextReaderConstPrefix(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The URI defining the namespace associated with the node. * + * @param reader the xmlTextReaderPtr used * @returns the namespace URI or NULL if not available, * if non NULL it need to be freed by the caller. */ @@ -3327,10 +3287,9 @@ xmlTextReaderNamespaceUri(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The URI defining the namespace associated with the node. * + * @param reader the xmlTextReaderPtr used * @returns the namespace URI or NULL if not available, the string * will be deallocated with the reader */ @@ -3354,10 +3313,9 @@ xmlTextReaderConstNamespaceUri(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The base URI of the node. * + * @param reader the xmlTextReaderPtr used * @returns the base URI or NULL if not available, * if non NULL it need to be freed by the caller. */ @@ -3376,10 +3334,9 @@ xmlTextReaderBaseUri(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The base URI of the node. * + * @param reader the xmlTextReaderPtr used * @returns the base URI or NULL if not available, the string * will be deallocated with the reader */ @@ -3402,10 +3359,9 @@ xmlTextReaderConstBaseUri(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The depth of the node in the tree. * + * @param reader the xmlTextReaderPtr used * @returns the depth or -1 in case of error */ int @@ -3425,10 +3381,9 @@ xmlTextReaderDepth(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Whether the node has attributes. * + * @param reader the xmlTextReaderPtr used * @returns 1 if true, 0 if false, and -1 in case or error */ int @@ -3451,10 +3406,9 @@ xmlTextReaderHasAttributes(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Whether the node can have a text value. * + * @param reader the xmlTextReaderPtr used * @returns 1 if true, 0 if false, and -1 in case or error */ int @@ -3484,10 +3438,9 @@ xmlTextReaderHasValue(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Provides the text value of the node if present * + * @param reader the xmlTextReaderPtr used * @returns the string or NULL if not available. The result must be deallocated * with xmlFree() */ @@ -3532,10 +3485,9 @@ xmlTextReaderValue(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Provides the text value of the node if present * + * @param reader the xmlTextReaderPtr used * @returns the string or NULL if not available. The result will be * deallocated on the next Read() operation. */ @@ -3593,11 +3545,10 @@ xmlTextReaderConstValue(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Whether an Attribute node was generated from the default value * defined in the DTD or schema. * + * @param reader the xmlTextReaderPtr used * @returns 0 if not defaulted, 1 if defaulted, and -1 in case of error */ int @@ -3608,10 +3559,9 @@ xmlTextReaderIsDefault(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The quotation mark character used to enclose the value of an attribute. * + * @param reader the xmlTextReaderPtr used * @returns " or ' and -1 in case of error */ int @@ -3623,10 +3573,9 @@ xmlTextReaderQuoteChar(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The xml:lang scope within which the node resides. * + * @param reader the xmlTextReaderPtr used * @returns the xml:lang value or NULL if none exists., * if non NULL it need to be freed by the caller. */ @@ -3640,10 +3589,9 @@ xmlTextReaderXmlLang(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * The xml:lang scope within which the node resides. * + * @param reader the xmlTextReaderPtr used * @returns the xml:lang value or NULL if none exists. */ const xmlChar * @@ -3664,12 +3612,11 @@ xmlTextReaderConstXmlLang(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * @param str the string to intern. - * * Get an interned string from the reader, allows for example to * speedup string name comparisons * + * @param reader the xmlTextReaderPtr used + * @param str the string to intern. * @returns an interned copy of the string or NULL in case of error. The * string will be deallocated with the reader. */ @@ -3681,14 +3628,13 @@ xmlTextReaderConstString(xmlTextReaderPtr reader, const xmlChar *str) { } /** - * @param reader the xmlTextReaderPtr used - * * The value indicating whether to normalize white space and attribute values. * Since attribute value and end of line normalizations are a MUST in the XML * specification only the value true is accepted. The broken behaviour of * accepting out of range character entities like &\#0; is of course not * supported either. * + * @param reader the xmlTextReaderPtr used * @returns 1 or -1 in case of error. */ int @@ -3705,14 +3651,13 @@ xmlTextReaderNormalization(xmlTextReaderPtr reader) { ************************************************************************/ /** - * @param reader the xmlTextReaderPtr used - * @param prop the xmlParserProperties to set - * @param value usually 0 or 1 to (de)activate it - * * Change the parser processing behaviour by changing some of its internal * properties. Note that some properties can only be changed before any * read has been done. * + * @param reader the xmlTextReaderPtr used + * @param prop the xmlParserProperties to set + * @param value usually 0 or 1 to (de)activate it * @returns 0 if the call was successful, or -1 in case of error */ int @@ -3771,11 +3716,10 @@ xmlTextReaderSetParserProp(xmlTextReaderPtr reader, int prop, int value) { } /** - * @param reader the xmlTextReaderPtr used - * @param prop the xmlParserProperties to get - * * Read the parser internal property. * + * @param reader the xmlTextReaderPtr used + * @param prop the xmlParserProperties to get * @returns the value, usually 0 or 1, or -1 in case of error. */ int @@ -3806,10 +3750,9 @@ xmlTextReaderGetParserProp(xmlTextReaderPtr reader, int prop) { /** - * @param reader the user data (XML reader context) - * * Provide the line number of the current parsing point. * + * @param reader the user data (XML reader context) * @returns an int or 0 if not available */ int @@ -3823,10 +3766,9 @@ xmlTextReaderGetParserLineNumber(xmlTextReaderPtr reader) } /** - * @param reader the user data (XML reader context) - * * Provide the column number of the current parsing point. * + * @param reader the user data (XML reader context) * @returns an int or 0 if not available */ int @@ -3840,12 +3782,11 @@ xmlTextReaderGetParserColumnNumber(xmlTextReaderPtr reader) } /** - * @param reader the xmlTextReaderPtr used - * * Hacking interface allowing to get the xmlNodePtr corresponding to the * current node being accessed by the xmlTextReader. This is dangerous * because the underlying node may be destroyed on the next Reads. * + * @param reader the xmlTextReaderPtr used * @returns the xmlNodePtr or NULL in case of error. */ xmlNodePtr @@ -3859,12 +3800,11 @@ xmlTextReaderCurrentNode(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * This tells the XML Reader to preserve the current node. * The caller must also use xmlTextReaderCurrentDoc() to * keep an handle on the resulting document once parsing has finished * + * @param reader the xmlTextReaderPtr used * @returns the xmlNodePtr or NULL in case of error. */ xmlNodePtr @@ -3895,14 +3835,13 @@ xmlTextReaderPreserve(xmlTextReaderPtr reader) { #ifdef LIBXML_PATTERN_ENABLED /** - * @param reader the xmlTextReaderPtr used - * @param pattern an XPath subset pattern - * @param namespaces the prefix definitions, array of [URI, prefix] or NULL - * * This tells the XML Reader to preserve all nodes matched by the * pattern. The caller must also use xmlTextReaderCurrentDoc() to * keep an handle on the resulting document once parsing has finished * + * @param reader the xmlTextReaderPtr used + * @param pattern an XPath subset pattern + * @param namespaces the prefix definitions, array of [URI, prefix] or NULL * @returns a non-negative number in case of success and -1 in case of error */ int @@ -3942,14 +3881,13 @@ xmlTextReaderPreservePattern(xmlTextReaderPtr reader, const xmlChar *pattern, #endif /** - * @param reader the xmlTextReaderPtr used - * * Hacking interface allowing to get the xmlDocPtr corresponding to the * current document being accessed by the xmlTextReader. * NOTE: as a result of this call, the reader will not destroy the * associated XML document and calling xmlFreeDoc() on the result * is needed once the reader parsing has finished. * + * @param reader the xmlTextReaderPtr used * @returns the xmlDocPtr or NULL in case of error. */ xmlDocPtr @@ -3967,15 +3905,14 @@ xmlTextReaderCurrentDoc(xmlTextReaderPtr reader) { #ifdef LIBXML_RELAXNG_ENABLED /** - * @param reader the xmlTextReaderPtr used - * @param schema a precompiled RelaxNG schema - * * Use RelaxNG to validate the document as it is processed. * Activation is only possible before the first Read(). * if `schema` is NULL, then RelaxNG validation is deactivated. * The `schema` should not be freed until the reader is deallocated * or its use has been deactivated. * + * @param reader the xmlTextReaderPtr used + * @param schema a precompiled RelaxNG schema * @returns 0 in case the RelaxNG validation could be (de)activated and * -1 in case of error. */ @@ -4023,12 +3960,11 @@ xmlTextReaderRelaxNGSetSchema(xmlTextReaderPtr reader, xmlRelaxNGPtr schema) { #ifdef LIBXML_SCHEMAS_ENABLED /** + * Internal locator function for the readers + * * @param ctx the xmlTextReaderPtr used * @param file returned file information * @param line returned line information - * - * Internal locator function for the readers - * * @returns 0 in case the Schema validation could be (de)activated and * -1 in case of error. */ @@ -4076,15 +4012,14 @@ xmlTextReaderLocator(void *ctx, const char **file, unsigned long *line) { } /** - * @param reader the xmlTextReaderPtr used - * @param schema a precompiled Schema schema - * * Use XSD Schema to validate the document as it is processed. * Activation is only possible before the first Read(). * if `schema` is NULL, then Schema validation is deactivated. * The `schema` should not be freed until the reader is deallocated * or its use has been deactivated. * + * @param reader the xmlTextReaderPtr used + * @param schema a precompiled Schema schema * @returns 0 in case the Schema validation could be (de)activated and * -1 in case of error. */ @@ -4156,15 +4091,14 @@ xmlTextReaderSetSchema(xmlTextReaderPtr reader, xmlSchemaPtr schema) { #ifdef LIBXML_RELAXNG_ENABLED /** - * @param reader the xmlTextReaderPtr used - * @param rng the path to a RelaxNG schema or NULL - * @param ctxt the RelaxNG schema validation context or NULL - * @param options options (not yet used) - * * Use RelaxNG to validate the document as it is processed. * Activation is only possible before the first Read(). * If both `rng` and `ctxt` are NULL, then RelaxNG validation is deactivated. * + * @param reader the xmlTextReaderPtr used + * @param rng the path to a RelaxNG schema or NULL + * @param ctxt the RelaxNG schema validation context or NULL + * @param options options (not yet used) * @returns 0 in case the RelaxNG validation could be (de)activated and * -1 in case of error. */ @@ -4245,15 +4179,14 @@ xmlTextReaderRelaxNGValidateInternal(xmlTextReaderPtr reader, #ifdef LIBXML_SCHEMAS_ENABLED /** - * @param reader the xmlTextReaderPtr used - * @param xsd the path to a W3C XSD schema or NULL - * @param ctxt the XML Schema validation context or NULL - * @param options options (not used yet) - * * Validate the document as it is processed using XML Schema. * Activation is only possible before the first Read(). * If both `xsd` and `ctxt` are NULL then XML Schema validation is deactivated. * + * @param reader the xmlTextReaderPtr used + * @param xsd the path to a W3C XSD schema or NULL + * @param ctxt the XML Schema validation context or NULL + * @param options options (not used yet) * @returns 0 in case the schemas validation could be (de)activated and * -1 in case of error. */ @@ -4353,14 +4286,13 @@ xmlTextReaderSchemaValidateInternal(xmlTextReaderPtr reader, } /** - * @param reader the xmlTextReaderPtr used - * @param ctxt the XML Schema validation context or NULL - * @param options options (not used yet) - * * Use W3C XSD schema context to validate the document as it is processed. * Activation is only possible before the first Read(). * If `ctxt` is NULL, then XML Schema validation is deactivated. * + * @param reader the xmlTextReaderPtr used + * @param ctxt the XML Schema validation context or NULL + * @param options options (not used yet) * @returns 0 in case the schemas validation could be (de)activated and * -1 in case of error. */ @@ -4373,13 +4305,12 @@ xmlTextReaderSchemaValidateCtxt(xmlTextReaderPtr reader, } /** - * @param reader the xmlTextReaderPtr used - * @param xsd the path to a W3C XSD schema or NULL - * * Use W3C XSD schema to validate the document as it is processed. * Activation is only possible before the first Read(). * If `xsd` is NULL, then XML Schema validation is deactivated. * + * @param reader the xmlTextReaderPtr used + * @param xsd the path to a W3C XSD schema or NULL * @returns 0 in case the schemas validation could be (de)activated and * -1 in case of error. */ @@ -4392,14 +4323,13 @@ xmlTextReaderSchemaValidate(xmlTextReaderPtr reader, const char *xsd) #ifdef LIBXML_RELAXNG_ENABLED /** - * @param reader the xmlTextReaderPtr used - * @param ctxt the RelaxNG schema validation context or NULL - * @param options options (not used yet) - * * Use RelaxNG schema context to validate the document as it is processed. * Activation is only possible before the first Read(). * If `ctxt` is NULL, then RelaxNG schema validation is deactivated. * + * @param reader the xmlTextReaderPtr used + * @param ctxt the RelaxNG schema validation context or NULL + * @param options options (not used yet) * @returns 0 in case the schemas validation could be (de)activated and * -1 in case of error. */ @@ -4412,13 +4342,12 @@ xmlTextReaderRelaxNGValidateCtxt(xmlTextReaderPtr reader, } /** - * @param reader the xmlTextReaderPtr used - * @param rng the path to a RelaxNG schema or NULL - * * Use RelaxNG schema to validate the document as it is processed. * Activation is only possible before the first Read(). * If `rng` is NULL, then RelaxNG schema validation is deactivated. * + * @param reader the xmlTextReaderPtr used + * @param rng the path to a RelaxNG schema or NULL * @returns 0 in case the schemas validation could be (de)activated and * -1 in case of error. */ @@ -4430,11 +4359,10 @@ xmlTextReaderRelaxNGValidate(xmlTextReaderPtr reader, const char *rng) #endif /* LIBXML_RELAXNG_ENABLED */ /** - * @param reader the xmlTextReaderPtr used - * * Determine whether the current node is a namespace declaration * rather than a regular attribute. * + * @param reader the xmlTextReaderPtr used * @returns 1 if the current node is a namespace declaration, 0 if it * is a regular attribute or other type of node, or -1 in case of * error. @@ -4458,10 +4386,9 @@ xmlTextReaderIsNamespaceDecl(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Determine the XML version of the document being read. * + * @param reader the xmlTextReaderPtr used * @returns a string containing the XML version of the document or NULL * in case of error. The string is deallocated with the reader. */ @@ -4484,10 +4411,9 @@ xmlTextReaderConstXmlVersion(xmlTextReaderPtr reader) { } /** - * @param reader the xmlTextReaderPtr used - * * Determine the standalone status of the document being read. * + * @param reader the xmlTextReaderPtr used * @returns 1 if the document was declared to be standalone, 0 if it * was declared to be not standalone, or -1 if the document did not * specify its standalone status or in case of error. @@ -4514,10 +4440,9 @@ xmlTextReaderStandalone(xmlTextReaderPtr reader) { ************************************************************************/ /** - * @param locator the xmlTextReaderLocatorPtr used - * * Obtain the line number for the given locator. * + * @param locator the xmlTextReaderLocatorPtr used * @returns the line number or -1 in case of error. */ int @@ -4549,10 +4474,9 @@ xmlTextReaderLocatorLineNumber(xmlTextReaderLocatorPtr locator) { } /** - * @param locator the xmlTextReaderLocatorPtr used - * * Obtain the base URI for the given locator. * + * @param locator the xmlTextReaderLocatorPtr used * @returns the base URI or NULL in case of error, * if non NULL it need to be freed by the caller. */ @@ -4585,15 +4509,14 @@ xmlTextReaderLocatorBaseURI(xmlTextReaderLocatorPtr locator) { } /** - * @param reader the xmlTextReaderPtr used - * @param f the callback function to call on error and warnings - * @param arg a user argument to pass to the callback function + * Register a callback function that will be called on error and warnings. * * @deprecated Use xmlTextReaderSetStructuredErrorHandler(). * - * Register a callback function that will be called on error and warnings. - * * If `f` is NULL, the default error and warning handlers are restored. + * @param reader the xmlTextReaderPtr used + * @param f the callback function to call on error and warnings + * @param arg a user argument to pass to the callback function */ void xmlTextReaderSetErrorHandler(xmlTextReaderPtr reader, @@ -4643,13 +4566,13 @@ xmlTextReaderSetErrorHandler(xmlTextReaderPtr reader, /** * xmlTextReaderSetStructuredErrorHandler: - * @param reader the xmlTextReaderPtr used - * @param f the callback function to call on error and warnings - * @param arg a user argument to pass to the callback function * * Register a callback function that will be called on error and warnings. * * If `f` is NULL, the default error and warning handlers are restored. + * @param reader the xmlTextReaderPtr used + * @param f the callback function to call on error and warnings + * @param arg a user argument to pass to the callback function */ void xmlTextReaderSetStructuredErrorHandler(xmlTextReaderPtr reader, @@ -4698,11 +4621,11 @@ xmlTextReaderSetStructuredErrorHandler(xmlTextReaderPtr reader, } /** + * Retrieve the error callback function and user argument. + * * @param reader the xmlTextReaderPtr used * @param f the callback function or NULL is no callback has been registered * @param arg a user argument - * - * Retrieve the error callback function and user argument. */ void xmlTextReaderGetErrorHandler(xmlTextReaderPtr reader, @@ -4715,14 +4638,13 @@ xmlTextReaderGetErrorHandler(xmlTextReaderPtr reader, } /** - * @param reader thr reader - * @param loader resource loader - * @param data user data which will be passed to the loader - * * Register a callback function that will be called to load external * resources like entities. * * @since 2.14.0 + * @param reader thr reader + * @param loader resource loader + * @param data user data which will be passed to the loader */ void xmlTextReaderSetResourceLoader(xmlTextReaderPtr reader, @@ -4737,10 +4659,9 @@ xmlTextReaderSetResourceLoader(xmlTextReaderPtr reader, } /** - * @param reader the xmlTextReaderPtr used - * * Retrieve the validity status from the parser context * + * @param reader the xmlTextReaderPtr used * @returns the flag value 1 if valid, 0 if no, and -1 in case of error */ int @@ -4768,15 +4689,14 @@ xmlTextReaderIsValid(xmlTextReaderPtr reader) ************************************************************************/ /** + * Setup an XML reader with new options + * * @param reader an XML reader * @param input xmlParserInputBufferPtr used to feed the reader, will * be destroyed with it. * @param URL the base URL to use for the document * @param encoding the document encoding, or NULL * @param options a combination of xmlParserOption - * - * Setup an XML reader with new options - * * @returns 0 in case of success and -1 in case of error. */ int @@ -4966,10 +4886,10 @@ xmlTextReaderSetup(xmlTextReaderPtr reader, } /** + * Set the maximum amplification factor. See xmlCtxtSetMaxAmplification(). + * * @param reader an XML reader * @param maxAmpl maximum amplification factor - * - * Set the maximum amplification factor. See xmlCtxtSetMaxAmplification(). */ void xmlTextReaderSetMaxAmplification(xmlTextReaderPtr reader, unsigned maxAmpl) @@ -4980,10 +4900,9 @@ xmlTextReaderSetMaxAmplification(xmlTextReaderPtr reader, unsigned maxAmpl) } /** - * @param reader an XML reader - * * @since 2.13.0 * + * @param reader an XML reader * @returns the last error. */ const xmlError * @@ -4995,18 +4914,17 @@ xmlTextReaderGetLastError(xmlTextReaderPtr reader) } /** - * @param reader an XML reader - * - * @deprecated The returned value is mostly random and useless. - * It reflects the parser reading ahead and is in no way related to - * the current node. - * * This function provides the current index of the parser used * by the reader, relative to the start of the current entity. * This function actually just wraps a call to xmlBytesConsumed() * for the parser context associated with the reader. * See xmlBytesConsumed() for more information. * + * @deprecated The returned value is mostly random and useless. + * It reflects the parser reading ahead and is in no way related to + * the current node. + * + * @param reader an XML reader * @returns the index in bytes from the beginning of the entity or -1 * in case the index could not be computed. */ @@ -5024,10 +4942,9 @@ xmlTextReaderByteConsumed(xmlTextReaderPtr reader) { /** - * @param doc a preparsed document - * * Create an xmltextReader for a preparsed document. * + * @param doc a preparsed document * @returns the new reader or NULL in case of error. */ xmlTextReaderPtr @@ -5058,14 +4975,13 @@ xmlReaderWalker(xmlDocPtr doc) } /** + * Create an xmltextReader for an XML in-memory document. + * The parsing flags `options` are a combination of xmlParserOption. + * * @param cur a pointer to a zero terminated string * @param URL the base URL to use for the document * @param encoding the document encoding, or NULL * @param options a combination of xmlParserOption - * - * Create an xmltextReader for an XML in-memory document. - * The parsing flags `options` are a combination of xmlParserOption. - * * @returns the new reader or NULL in case of error. */ xmlTextReaderPtr @@ -5083,13 +4999,12 @@ xmlReaderForDoc(const xmlChar * cur, const char *URL, const char *encoding, } /** - * @param filename a file or URL - * @param encoding the document encoding, or NULL - * @param options a combination of xmlParserOption - * * parse an XML file from the filesystem or the network. * The parsing flags `options` are a combination of xmlParserOption. * + * @param filename a file or URL + * @param encoding the document encoding, or NULL + * @param options a combination of xmlParserOption * @returns the new reader or NULL in case of error. */ xmlTextReaderPtr @@ -5108,15 +5023,14 @@ xmlReaderForFile(const char *filename, const char *encoding, int options) } /** + * Create an xmltextReader for an XML in-memory document. + * The parsing flags `options` are a combination of xmlParserOption. + * * @param buffer a pointer to a char array * @param size the size of the array * @param URL the base URL to use for the document * @param encoding the document encoding, or NULL * @param options a combination of xmlParserOption - * - * Create an xmltextReader for an XML in-memory document. - * The parsing flags `options` are a combination of xmlParserOption. - * * @returns the new reader or NULL in case of error. */ xmlTextReaderPtr @@ -5144,16 +5058,15 @@ xmlReaderForMemory(const char *buffer, int size, const char *URL, } /** - * @param fd an open file descriptor - * @param URL the base URL to use for the document - * @param encoding the document encoding, or NULL - * @param options a combination of xmlParserOption - * * Create an xmltextReader for an XML from a file descriptor. * The parsing flags `options` are a combination of xmlParserOption. * NOTE that the file descriptor will not be closed when the * reader is closed or reset. * + * @param fd an open file descriptor + * @param URL the base URL to use for the document + * @param encoding the document encoding, or NULL + * @param options a combination of xmlParserOption * @returns the new reader or NULL in case of error. */ xmlTextReaderPtr @@ -5199,16 +5112,15 @@ xmlReaderForFd(int fd, const char *URL, const char *encoding, int options) } /** + * Create an xmltextReader for an XML document from I/O functions and source. + * The parsing flags `options` are a combination of xmlParserOption. + * * @param ioread an I/O read function * @param ioclose an I/O close function * @param ioctx an I/O handler * @param URL the base URL to use for the document * @param encoding the document encoding, or NULL * @param options a combination of xmlParserOption - * - * Create an xmltextReader for an XML document from I/O functions and source. - * The parsing flags `options` are a combination of xmlParserOption. - * * @returns the new reader or NULL in case of error. */ xmlTextReaderPtr @@ -5243,12 +5155,11 @@ xmlReaderForIO(xmlInputReadCallback ioread, xmlInputCloseCallback ioclose, } /** - * @param reader an XML reader - * @param doc a preparsed document - * * Setup an xmltextReader to parse a preparsed XML document. * This reuses the existing `reader` xmlTextReader. * + * @param reader an XML reader + * @param doc a preparsed document * @returns 0 in case of success and -1 in case of error */ int @@ -5286,16 +5197,15 @@ xmlReaderNewWalker(xmlTextReaderPtr reader, xmlDocPtr doc) } /** + * Setup an xmltextReader to parse an XML in-memory document. + * The parsing flags `options` are a combination of xmlParserOption. + * This reuses the existing `reader` xmlTextReader. + * * @param reader an XML reader * @param cur a pointer to a zero terminated string * @param URL the base URL to use for the document * @param encoding the document encoding, or NULL * @param options a combination of xmlParserOption - * - * Setup an xmltextReader to parse an XML in-memory document. - * The parsing flags `options` are a combination of xmlParserOption. - * This reuses the existing `reader` xmlTextReader. - * * @returns 0 in case of success and -1 in case of error */ int @@ -5316,15 +5226,14 @@ xmlReaderNewDoc(xmlTextReaderPtr reader, const xmlChar * cur, } /** - * @param reader an XML reader - * @param filename a file or URL - * @param encoding the document encoding, or NULL - * @param options a combination of xmlParserOption - * * parse an XML file from the filesystem or the network. * The parsing flags `options` are a combination of xmlParserOption. * This reuses the existing `reader` xmlTextReader. * + * @param reader an XML reader + * @param filename a file or URL + * @param encoding the document encoding, or NULL + * @param options a combination of xmlParserOption * @returns 0 in case of success and -1 in case of error */ int @@ -5372,17 +5281,16 @@ xmlReaderNewFile(xmlTextReaderPtr reader, const char *filename, } /** + * Setup an xmltextReader to parse an XML in-memory document. + * The parsing flags `options` are a combination of xmlParserOption. + * This reuses the existing `reader` xmlTextReader. + * * @param reader an XML reader * @param buffer a pointer to a char array * @param size the size of the array * @param URL the base URL to use for the document * @param encoding the document encoding, or NULL * @param options a combination of xmlParserOption - * - * Setup an xmltextReader to parse an XML in-memory document. - * The parsing flags `options` are a combination of xmlParserOption. - * This reuses the existing `reader` xmlTextReader. - * * @returns 0 in case of success and -1 in case of error */ int @@ -5405,18 +5313,17 @@ xmlReaderNewMemory(xmlTextReaderPtr reader, const char *buffer, int size, } /** - * @param reader an XML reader - * @param fd an open file descriptor - * @param URL the base URL to use for the document - * @param encoding the document encoding, or NULL - * @param options a combination of xmlParserOption - * * Setup an xmltextReader to parse an XML from a file descriptor. * NOTE that the file descriptor will not be closed when the * reader is closed or reset. * The parsing flags `options` are a combination of xmlParserOption. * This reuses the existing `reader` xmlTextReader. * + * @param reader an XML reader + * @param fd an open file descriptor + * @param URL the base URL to use for the document + * @param encoding the document encoding, or NULL + * @param options a combination of xmlParserOption * @returns 0 in case of success and -1 in case of error */ int @@ -5455,6 +5362,11 @@ xmlReaderNewFd(xmlTextReaderPtr reader, int fd, } /** + * Setup an xmltextReader to parse an XML document from I/O functions + * and source. + * The parsing flags `options` are a combination of xmlParserOption. + * This reuses the existing `reader` xmlTextReader. + * * @param reader an XML reader * @param ioread an I/O read function * @param ioclose an I/O close function @@ -5462,12 +5374,6 @@ xmlReaderNewFd(xmlTextReaderPtr reader, int fd, * @param URL the base URL to use for the document * @param encoding the document encoding, or NULL * @param options a combination of xmlParserOption - * - * Setup an xmltextReader to parse an XML document from I/O functions - * and source. - * The parsing flags `options` are a combination of xmlParserOption. - * This reuses the existing `reader` xmlTextReader. - * * @returns 0 in case of success and -1 in case of error */ int diff --git a/xmlregexp.c b/xmlregexp.c index 535078f9..5ed2db16 100644 --- a/xmlregexp.c +++ b/xmlregexp.c @@ -355,9 +355,9 @@ static int xmlRegCheckCharacterRange(xmlRegAtomType type, int codepoint, * * ************************************************************************/ /** - * @param ctxt regexp parser context - * * Handle an out of memory condition + * + * @param ctxt regexp parser context */ static void xmlRegexpErrMemory(xmlRegParserCtxtPtr ctxt) @@ -369,10 +369,10 @@ xmlRegexpErrMemory(xmlRegParserCtxtPtr ctxt) } /** + * Handle a compilation failure + * * @param ctxt regexp parser context * @param extra extra information - * - * Handle a compilation failure */ static void xmlRegexpErrCompile(xmlRegParserCtxtPtr ctxt, const char *extra) @@ -404,12 +404,11 @@ xmlRegexpErrCompile(xmlRegParserCtxtPtr ctxt, const char *extra) static int xmlFAComputesDeterminism(xmlRegParserCtxtPtr ctxt); /** + * Allocate a two-dimensional array and set all elements to zero. + * * @param dim1 size of first dimension * @param dim2 size of second dimension * @param elemSize size of element - * - * Allocate a two-dimensional array and set all elements to zero. - * * @returns the new array or NULL in case of error. */ static void* @@ -429,10 +428,9 @@ xmlRegCalloc2(size_t dim1, size_t dim2, size_t elemSize) { } /** - * @param ctxt the parser context used to build it - * * Allocate a new regexp and fill it with the result from the parser * + * @param ctxt the parser context used to build it * @returns the new regexp or NULL in case of error */ static xmlRegexpPtr @@ -658,10 +656,9 @@ not_determ: } /** - * @param string the string to parse - * * Allocate a new regexp parser context * + * @param string the string to parse * @returns the new context or NULL in case of error */ static xmlRegParserCtxtPtr @@ -688,14 +685,13 @@ xmlRegNewParserCtxt(const xmlChar *string) { } /** + * Allocate a new regexp range + * * @param ctxt the regexp parser context * @param neg is that negative * @param type the type of range * @param start the start codepoint * @param end the end codepoint - * - * Allocate a new regexp range - * * @returns the new range or NULL in case of error */ static xmlRegRangePtr @@ -716,9 +712,9 @@ xmlRegNewRange(xmlRegParserCtxtPtr ctxt, } /** - * @param range the regexp range - * * Free a regexp range + * + * @param range the regexp range */ static void xmlRegFreeRange(xmlRegRangePtr range) { @@ -731,11 +727,10 @@ xmlRegFreeRange(xmlRegRangePtr range) { } /** - * @param ctxt regexp parser context - * @param range the regexp range - * * Copy a regexp range * + * @param ctxt regexp parser context + * @param range the regexp range * @returns the new copy or NULL in case of error. */ static xmlRegRangePtr @@ -761,11 +756,10 @@ xmlRegCopyRange(xmlRegParserCtxtPtr ctxt, xmlRegRangePtr range) { } /** - * @param ctxt the regexp parser context - * @param type the type of atom - * * Allocate a new atom * + * @param ctxt the regexp parser context + * @param type the type of atom * @returns the new atom or NULL in case of error */ static xmlRegAtomPtr @@ -786,9 +780,9 @@ xmlRegNewAtom(xmlRegParserCtxtPtr ctxt, xmlRegAtomType type) { } /** - * @param atom the regexp atom - * * Free a regexp atom + * + * @param atom the regexp atom */ static void xmlRegFreeAtom(xmlRegAtomPtr atom) { @@ -811,11 +805,10 @@ xmlRegFreeAtom(xmlRegAtomPtr atom) { } /** - * @param ctxt the regexp parser context - * @param atom the original atom - * * Allocate a new regexp range * + * @param ctxt the regexp parser context + * @param atom the original atom * @returns the new atom or NULL in case of error */ static xmlRegAtomPtr @@ -871,9 +864,9 @@ xmlRegNewState(xmlRegParserCtxtPtr ctxt) { } /** - * @param state the regexp state - * * Free a regexp state + * + * @param state the regexp state */ static void xmlRegFreeState(xmlRegStatePtr state) { @@ -888,9 +881,9 @@ xmlRegFreeState(xmlRegStatePtr state) { } /** - * @param ctxt the regexp parser context - * * Free a regexp parser context + * + * @param ctxt the regexp parser context */ static void xmlRegFreeParserCtxt(xmlRegParserCtxtPtr ctxt) { @@ -1552,7 +1545,6 @@ xmlRegStatePush(xmlRegParserCtxtPtr ctxt) { * @param from the from state * @param to the target state or NULL for building a new one * @param lax - * */ static int xmlFAGenerateAllTransition(xmlRegParserCtxtPtr ctxt, @@ -1575,7 +1567,6 @@ xmlFAGenerateAllTransition(xmlRegParserCtxtPtr ctxt, * @param ctxt a regexp parser context * @param from the from state * @param to the target state or NULL for building a new one - * */ static int xmlFAGenerateEpsilonTransition(xmlRegParserCtxtPtr ctxt, @@ -1633,7 +1624,6 @@ xmlFAGenerateCountedTransition(xmlRegParserCtxtPtr ctxt, * @param from the from state * @param to the target state or NULL for building a new one * @param atom the atom generating the transition - * * @returns 0 if success and -1 in case of error. */ static int @@ -1865,7 +1855,6 @@ xmlFAGenerateTransitions(xmlRegParserCtxtPtr ctxt, xmlRegStatePtr from, * @param fromnr the from state * @param tonr the to state * @param counter should that transition be associated to a counted - * */ static void xmlFAReduceEpsilonTransitions(xmlRegParserCtxtPtr ctxt, int fromnr, @@ -1946,8 +1935,6 @@ xmlFAFinishReduceEpsilonTransitions(xmlRegParserCtxtPtr ctxt, int tonr) { } /** - * @param ctxt a regexp parser context - * * Eliminating general epsilon transitions can get costly in the general * algorithm due to the large amount of generated new transitions and * associated comparisons. However for simple epsilon transition used just @@ -1964,6 +1951,7 @@ xmlFAFinishReduceEpsilonTransitions(xmlRegParserCtxtPtr ctxt, int tonr) { * eliminating state 2: * State 1 has a transition with an atom to state 2. * State 2 is final and has an epsilon transition to state 1. + * @param ctxt a regexp parser context */ static void xmlFAEliminateSimpleEpsilonTransitions(xmlRegParserCtxtPtr ctxt) { @@ -2015,7 +2003,6 @@ xmlFAEliminateSimpleEpsilonTransitions(xmlRegParserCtxtPtr ctxt) { } /** * @param ctxt a regexp parser context - * */ static void xmlFAEliminateEpsilonTransitions(xmlRegParserCtxtPtr ctxt) { @@ -2315,12 +2302,11 @@ xmlFACompareRanges(xmlRegRangePtr range1, xmlRegRangePtr range2) { } /** - * @param type1 an atom type - * @param type2 an atom type - * * Compares two atoms type to check whether they intersect in some ways, * this is used by xmlFACompareAtoms() only * + * @param type1 an atom type + * @param type2 an atom type * @returns 1 if they may intersect and 0 otherwise */ static int @@ -2515,13 +2501,12 @@ xmlFACompareAtomTypes(xmlRegAtomType type1, xmlRegAtomType type2) { } /** - * @param atom1 an atom - * @param atom2 an atom - * @param deep if not set only compare string pointers - * * Compares two atoms to check whether they are the same exactly * this is used to remove equivalent transitions * + * @param atom1 an atom + * @param atom2 an atom + * @param deep if not set only compare string pointers * @returns 1 if same and 0 otherwise */ static int @@ -2559,13 +2544,12 @@ xmlFAEqualAtoms(xmlRegAtomPtr atom1, xmlRegAtomPtr atom2, int deep) { } /** - * @param atom1 an atom - * @param atom2 an atom - * @param deep if not set only compare string pointers - * * Compares two atoms to check whether they intersect in some ways, * this is used by xmlFAComputesDeterminism() and xmlFARecurseDeterminism() only * + * @param atom1 an atom + * @param atom2 an atom + * @param deep if not set only compare string pointers * @returns 1 if yes and 0 otherwise */ static int @@ -2657,15 +2641,14 @@ not_determinist: } /** + * Check whether the associated regexp is determinist, + * should be called after xmlFAEliminateEpsilonTransitions() + * * @param ctxt a regexp parser context * @param state regexp state * @param fromnr the from state * @param tonr the to state * @param atom the atom - * - * Check whether the associated regexp is determinist, - * should be called after xmlFAEliminateEpsilonTransitions() - * */ static int xmlFARecurseDeterminism(xmlRegParserCtxtPtr ctxt, xmlRegStatePtr state, @@ -2719,10 +2702,10 @@ xmlFARecurseDeterminism(xmlRegParserCtxtPtr ctxt, xmlRegStatePtr state, } /** + * Reset flags after checking determinism. + * * @param ctxt a regexp parser context * @param state regexp state - * - * Reset flags after checking determinism. */ static void xmlFAFinishRecurseDeterminism(xmlRegParserCtxtPtr ctxt, xmlRegStatePtr state) { @@ -2743,11 +2726,10 @@ xmlFAFinishRecurseDeterminism(xmlRegParserCtxtPtr ctxt, xmlRegStatePtr state) { } /** - * @param ctxt a regexp parser context - * * Check whether the associated regexp is determinist, * should be called after xmlFAEliminateEpsilonTransitions() * + * @param ctxt a regexp parser context */ static int xmlFAComputesDeterminism(xmlRegParserCtxtPtr ctxt) { @@ -3551,13 +3533,12 @@ error: ************************************************************************/ /** + * Build a context used for progressive evaluation of a regexp. + * * @param comp a precompiled regular expression * @param callback a callback function used for handling progresses in the * automata matching phase * @param data the context data associated to the callback in this context - * - * Build a context used for progressive evaluation of a regexp. - * * @returns the new context */ xmlRegExecCtxtPtr @@ -3613,9 +3594,9 @@ xmlRegNewExecCtxt(xmlRegexpPtr comp, xmlRegExecCallbacks callback, void *data) { } /** - * @param exec a regular expression evaluation context - * * Free the structures associated to a regular expression evaluation context. + * + * @param exec a regular expression evaluation context */ void xmlRegFreeExecCtxt(xmlRegExecCtxtPtr exec) { @@ -3705,13 +3686,12 @@ xmlFARegExecSaveInputString(xmlRegExecCtxtPtr exec, const xmlChar *value, } /** - * @param expStr the string to be evaluated - * @param valStr the validation string - * * Checks if both strings are equal or have the same content. "*" * can be used as a wildcard in `valStr`; "|" is used as a separator of * substrings in both `expStr` and `valStr`. * + * @param expStr the string to be evaluated + * @param valStr the validation string * @returns 1 if the comparison is satisfied and the number of substrings * is equal, 0 otherwise. */ @@ -3754,13 +3734,12 @@ xmlRegStrEqualWildcard(const xmlChar *expStr, const xmlChar *valStr) { } /** + * Push one input token in the execution context + * * @param exec a regexp execution context * @param comp the precompiled exec with a compact table * @param value a string token input * @param data data associated to the token to reuse in callbacks - * - * Push one input token in the execution context - * * @returns 1 if the regexp reached a final state, 0 if non-final, and * a negative value in case of error. */ @@ -3821,13 +3800,12 @@ error: } /** + * Push one input token in the execution context + * * @param exec a regexp execution context or NULL to indicate the end * @param value a string token input * @param data data associated to the token to reuse in callbacks * @param compound value was assembled from 2 strings - * - * Push one input token in the execution context - * * @returns 1 if the regexp reached a final state, 0 if non-final, and * a negative value in case of error. */ @@ -4132,12 +4110,11 @@ progress: } /** + * Push one input token in the execution context + * * @param exec a regexp execution context or NULL to indicate the end * @param value a string token input * @param data data associated to the token to reuse in callbacks - * - * Push one input token in the execution context - * * @returns 1 if the regexp reached a final state, 0 if non-final, and * a negative value in case of error. */ @@ -4148,13 +4125,12 @@ xmlRegExecPushString(xmlRegExecCtxtPtr exec, const xmlChar *value, } /** + * Push one input token in the execution context + * * @param exec a regexp execution context or NULL to indicate the end * @param value the first string token input * @param value2 the second string token input * @param data data associated to the token to reuse in callbacks - * - * Push one input token in the execution context - * * @returns 1 if the regexp reached a final state, 0 if non-final, and * a negative value in case of error. */ @@ -4203,16 +4179,15 @@ xmlRegExecPushString2(xmlRegExecCtxtPtr exec, const xmlChar *value, } /** + * Extract information from the regexp execution, internal routine to + * implement xmlRegExecNextValues() and xmlRegExecErrInfo() + * * @param exec a regexp execution context * @param err error extraction or normal one * @param nbval pointer to the number of accepted values IN/OUT * @param nbneg return number of negative transitions * @param values pointer to the array of acceptable values * @param terminal return value if this was a terminal state - * - * Extract information from the regexp execution, internal routine to - * implement xmlRegExecNextValues() and xmlRegExecErrInfo() - * * @returns 0 in case of success or -1 in case of error. */ static int @@ -4360,12 +4335,6 @@ xmlRegExecGetValues(xmlRegExecCtxtPtr exec, int err, } /** - * @param exec a regexp execution context - * @param nbval pointer to the number of accepted values IN/OUT - * @param nbneg return number of negative transitions - * @param values pointer to the array of acceptable values - * @param terminal return value if this was a terminal state - * * Extract information from the regexp execution, * the parameter `values` must point to an array of `nbval` string pointers * on return nbval will contain the number of possible strings in that @@ -4373,6 +4342,11 @@ xmlRegExecGetValues(xmlRegExecCtxtPtr exec, int err, * returned will be freed with the `exec` context and don't need to be * deallocated. * + * @param exec a regexp execution context + * @param nbval pointer to the number of accepted values IN/OUT + * @param nbneg return number of negative transitions + * @param values pointer to the array of acceptable values + * @param terminal return value if this was a terminal state * @returns 0 in case of success or -1 in case of error. */ int @@ -4382,13 +4356,6 @@ xmlRegExecNextValues(xmlRegExecCtxtPtr exec, int *nbval, int *nbneg, } /** - * @param exec a regexp execution context generating an error - * @param string return value for the error string - * @param nbval pointer to the number of accepted values IN/OUT - * @param nbneg return number of negative transitions - * @param values pointer to the array of acceptable values - * @param terminal return value if this was a terminal state - * * Extract error information from the regexp execution, the parameter * `string` will be updated with the value pushed and not accepted, * the parameter `values` must point to an array of `nbval` string pointers @@ -4397,6 +4364,12 @@ xmlRegExecNextValues(xmlRegExecCtxtPtr exec, int *nbval, int *nbneg, * returned will be freed with the `exec` context and don't need to be * deallocated. * + * @param exec a regexp execution context generating an error + * @param string return value for the error string + * @param nbval pointer to the number of accepted values IN/OUT + * @param nbneg return number of negative transitions + * @param values pointer to the array of acceptable values + * @param terminal return value if this was a terminal state * @returns 0 in case of success or -1 in case of error. */ int @@ -4421,9 +4394,9 @@ xmlRegExecErrInfo(xmlRegExecCtxtPtr exec, const xmlChar **string, ************************************************************************/ /** - * @param ctxt a regexp parser context - * * [10] Char ::= [^.\?*+()|\#x5B\#x5D] + * + * @param ctxt a regexp parser context */ static int xmlFAIsChar(xmlRegParserCtxtPtr ctxt) { @@ -4445,8 +4418,6 @@ xmlFAIsChar(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * * [27] charProp ::= IsCategory | IsBlock * [28] IsCategory ::= Letters | Marks | Numbers | Punctuation | * Separators | Symbols | Others @@ -4458,6 +4429,8 @@ xmlFAIsChar(xmlRegParserCtxtPtr ctxt) { * [34] Symbols ::= 'S' [mcko]? * [35] Others ::= 'C' [cfon]? * [36] IsBlock ::= 'Is' [a-zA-Z0-9\#x2D]+ + * + * @param ctxt a regexp parser context */ static void xmlFAParseCharProp(xmlRegParserCtxtPtr ctxt) { @@ -4715,8 +4688,6 @@ static int parse_escaped_codepoint(xmlRegParserCtxtPtr ctxt) } /** - * @param ctxt a regexp parser context - * * ``` * [23] charClassEsc ::= ( SingleCharEsc | MultiCharEsc | catEsc | complEsc ) * [24] SingleCharEsc ::= '\' [nrt\|.?*+(){}\#x2D\#x5B\#x5D\#x5E] @@ -4724,6 +4695,8 @@ static int parse_escaped_codepoint(xmlRegParserCtxtPtr ctxt) * [26] complEsc ::= '\P{' charProp '}' * [37] MultiCharEsc ::= '.' | ('\' [sSiIcCdDwW]) * ``` + * + * @param ctxt a regexp parser context */ static void xmlFAParseCharClassEsc(xmlRegParserCtxtPtr ctxt) { @@ -4886,8 +4859,6 @@ xmlFAParseCharClassEsc(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * * ``` * [17] charRange ::= seRange | XmlCharRef | XmlCharIncDash * [18] seRange ::= charOrEsc '-' charOrEsc @@ -4895,6 +4866,8 @@ xmlFAParseCharClassEsc(xmlRegParserCtxtPtr ctxt) { * [21] XmlChar ::= [^\\#x2D\#x5B\#x5D] * [22] XmlCharIncDash ::= [^\\#x5B\#x5D] * ``` + * + * @param ctxt a regexp parser context */ static void xmlFAParseCharRange(xmlRegParserCtxtPtr ctxt) { @@ -4992,9 +4965,9 @@ xmlFAParseCharRange(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * * [14] posCharGroup ::= ( charRange | charClassEsc )+ + * + * @param ctxt a regexp parser context */ static void xmlFAParsePosCharGroup(xmlRegParserCtxtPtr ctxt) { @@ -5009,12 +4982,12 @@ xmlFAParsePosCharGroup(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * * [13] charGroup ::= posCharGroup | negCharGroup | charClassSub * [15] negCharGroup ::= '^' posCharGroup * [16] charClassSub ::= ( posCharGroup | negCharGroup ) '-' charClassExpr * [12] charClassExpr ::= '[' charGroup ']' + * + * @param ctxt a regexp parser context */ static void xmlFAParseCharGroup(xmlRegParserCtxtPtr ctxt) { @@ -5046,10 +5019,10 @@ xmlFAParseCharGroup(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * * [11] charClass ::= charClassEsc | charClassExpr * [12] charClassExpr ::= '[' charGroup ']' + * + * @param ctxt a regexp parser context */ static void xmlFAParseCharClass(xmlRegParserCtxtPtr ctxt) { @@ -5070,10 +5043,9 @@ xmlFAParseCharClass(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * * [8] QuantExact ::= [0-9]+ * + * @param ctxt a regexp parser context * @returns 0 if success or -1 in case of error */ static int @@ -5104,13 +5076,13 @@ xmlFAParseQuantExact(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * * [4] quantifier ::= [?*+] | ( '{' quantity '}' ) * [5] quantity ::= quantRange | quantMin | QuantExact * [6] quantRange ::= QuantExact ',' QuantExact * [7] quantMin ::= QuantExact ',' * [8] QuantExact ::= [0-9]+ + * + * @param ctxt a regexp parser context */ static int xmlFAParseQuantifier(xmlRegParserCtxtPtr ctxt) { @@ -5170,9 +5142,9 @@ xmlFAParseQuantifier(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * * [9] atom ::= Char | charClass | ( '(' regExp ')' ) + * + * @param ctxt a regexp parser context */ static int xmlFAParseAtom(xmlRegParserCtxtPtr ctxt) { @@ -5241,9 +5213,9 @@ xmlFAParseAtom(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * * [3] piece ::= atom quantifier? + * + * @param ctxt a regexp parser context */ static int xmlFAParsePiece(xmlRegParserCtxtPtr ctxt) { @@ -5261,13 +5233,12 @@ xmlFAParsePiece(xmlRegParserCtxtPtr ctxt) { } /** - * @param ctxt a regexp parser context - * @param to optional target to the end of the branch - * * `to` is used to optimize by removing duplicate path in automata * in expressions like (a|b)(c|d) * * [2] branch ::= piece* + * @param ctxt a regexp parser context + * @param to optional target to the end of the branch */ static int xmlFAParseBranch(xmlRegParserCtxtPtr ctxt, xmlRegStatePtr to) { @@ -5308,10 +5279,10 @@ xmlFAParseBranch(xmlRegParserCtxtPtr ctxt, xmlRegStatePtr to) { } /** + * [1] regExp ::= branch ( '|' branch )* + * * @param ctxt a regexp parser context * @param top is this the top-level expression ? - * - * [1] regExp ::= branch ( '|' branch )* */ static void xmlFAParseRegExp(xmlRegParserCtxtPtr ctxt, int top) { @@ -5348,12 +5319,12 @@ xmlFAParseRegExp(xmlRegParserCtxtPtr ctxt, int top) { ************************************************************************/ /** - * @param output the file for the output debug - * @param regexp the compiled regexp + * No-op since 2.14.0. * * @deprecated Don't use. * - * No-op since 2.14.0. + * @param output the file for the output debug + * @param regexp the compiled regexp */ void xmlRegexpPrint(FILE *output ATTRIBUTE_UNUSED, @@ -5361,12 +5332,11 @@ xmlRegexpPrint(FILE *output ATTRIBUTE_UNUSED, } /** - * @param regexp a regular expression string - * * Parses a regular expression conforming to XML Schemas Part 2 Datatype * Appendix F and builds an automata suitable for testing strings against * that regular expression * + * @param regexp a regular expression string * @returns the compiled expression or NULL in case of error */ xmlRegexpPtr @@ -5413,11 +5383,10 @@ error: } /** - * @param comp the compiled regular expression - * @param content the value to check against the regular expression - * * Check if the regular expression generates the value * + * @param comp the compiled regular expression + * @param content the value to check against the regular expression * @returns 1 if it matches, 0 if not and a negative value in case of error */ int @@ -5428,10 +5397,9 @@ xmlRegexpExec(xmlRegexpPtr comp, const xmlChar *content) { } /** - * @param comp the compiled regular expression - * * Check if the regular expression is determinist * + * @param comp the compiled regular expression * @returns 1 if it yes, 0 if not and a negative value in case of error */ int @@ -5469,9 +5437,9 @@ xmlRegexpIsDeterminist(xmlRegexpPtr comp) { } /** - * @param regexp the regexp - * * Free a regexp + * + * @param regexp the regexp */ void xmlRegFreeRegexp(xmlRegexpPtr regexp) { @@ -5541,9 +5509,9 @@ xmlNewAutomata(void) { } /** - * @param am an automata - * * Free an automata + * + * @param am an automata */ void xmlFreeAutomata(xmlAutomataPtr am) { @@ -5553,10 +5521,10 @@ xmlFreeAutomata(xmlAutomataPtr am) { } /** + * Set some flags on the automata + * * @param am an automata * @param flags a set of internal flags - * - * Set some flags on the automata */ void xmlAutomataSetFlags(xmlAutomataPtr am, int flags) { @@ -5566,10 +5534,9 @@ xmlAutomataSetFlags(xmlAutomataPtr am, int flags) { } /** - * @param am an automata - * * Initial state lookup * + * @param am an automata * @returns the initial state of the automata */ xmlAutomataStatePtr @@ -5580,11 +5547,10 @@ xmlAutomataGetInitState(xmlAutomataPtr am) { } /** - * @param am an automata - * @param state a state in this automata - * * Makes that state a final state * + * @param am an automata + * @param state a state in this automata * @returns 0 or -1 in case of error */ int @@ -5596,16 +5562,15 @@ xmlAutomataSetFinalState(xmlAutomataPtr am, xmlAutomataStatePtr state) { } /** + * If `to` is NULL, this creates first a new target state in the automata + * and then adds a transition from the `from` state to the target state + * activated by the value of `token` + * * @param am an automata * @param from the starting point of the transition * @param to the target point of the transition or NULL * @param token the input string associated to that transition * @param data data passed to the callback function if the transition is activated - * - * If `to` is NULL, this creates first a new target state in the automata - * and then adds a transition from the `from` state to the target state - * activated by the value of `token` - * * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -5637,17 +5602,16 @@ xmlAutomataNewTransition(xmlAutomataPtr am, xmlAutomataStatePtr from, } /** + * If `to` is NULL, this creates first a new target state in the automata + * and then adds a transition from the `from` state to the target state + * activated by the value of `token` + * * @param am an automata * @param from the starting point of the transition * @param to the target point of the transition or NULL * @param token the first input string associated to that transition * @param token2 the second input string associated to that transition * @param data data passed to the callback function if the transition is activated - * - * If `to` is NULL, this creates first a new target state in the automata - * and then adds a transition from the `from` state to the target state - * activated by the value of `token` - * * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -5694,19 +5658,18 @@ xmlAutomataNewTransition2(xmlAutomataPtr am, xmlAutomataStatePtr from, } /** - * @param am an automata - * @param from the starting point of the transition - * @param to the target point of the transition or NULL - * @param token the first input string associated to that transition - * @param token2 the second input string associated to that transition - * @param data data passed to the callback function if the transition is activated - * * If `to` is NULL, this creates first a new target state in the automata * and then adds a transition from the `from` state to the target state * activated by any value except (`token`,`token2`) * Note that if `token2` is not NULL, then (X, NULL) won't match to follow * the semantic of XSD \#\#other * + * @param am an automata + * @param from the starting point of the transition + * @param to the target point of the transition or NULL + * @param token the first input string associated to that transition + * @param token2 the second input string associated to that transition + * @param data data passed to the callback function if the transition is activated * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -5759,6 +5722,11 @@ xmlAutomataNewNegTrans(xmlAutomataPtr am, xmlAutomataStatePtr from, } /** + * If `to` is NULL, this creates first a new target state in the automata + * and then adds a transition from the `from` state to the target state + * activated by a succession of input of value `token` and `token2` and + * whose number is between `min` and `max` + * * @param am an automata * @param from the starting point of the transition * @param to the target point of the transition or NULL @@ -5767,12 +5735,6 @@ xmlAutomataNewNegTrans(xmlAutomataPtr am, xmlAutomataStatePtr from, * @param min the minimum successive occurrences of token * @param max the maximum successive occurrences of token * @param data data associated to the transition - * - * If `to` is NULL, this creates first a new target state in the automata - * and then adds a transition from the `from` state to the target state - * activated by a succession of input of value `token` and `token2` and - * whose number is between `min` and `max` - * * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -5854,6 +5816,11 @@ error: } /** + * If `to` is NULL, this creates first a new target state in the automata + * and then adds a transition from the `from` state to the target state + * activated by a succession of input of value `token` and whose number + * is between `min` and `max` + * * @param am an automata * @param from the starting point of the transition * @param to the target point of the transition or NULL @@ -5861,12 +5828,6 @@ error: * @param min the minimum successive occurrences of token * @param max the maximum successive occurrences of token * @param data data associated to the transition - * - * If `to` is NULL, this creates first a new target state in the automata - * and then adds a transition from the `from` state to the target state - * activated by a succession of input of value `token` and whose number - * is between `min` and `max` - * * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -5929,6 +5890,12 @@ error: } /** + * If `to` is NULL, this creates first a new target state in the automata + * and then adds a transition from the `from` state to the target state + * activated by a succession of input of value `token` and `token2` and whose + * number is between `min` and `max`, moreover that transition can only be + * crossed once. + * * @param am an automata * @param from the starting point of the transition * @param to the target point of the transition or NULL @@ -5937,13 +5904,6 @@ error: * @param min the minimum successive occurrences of token * @param max the maximum successive occurrences of token * @param data data associated to the transition - * - * If `to` is NULL, this creates first a new target state in the automata - * and then adds a transition from the `from` state to the target state - * activated by a succession of input of value `token` and `token2` and whose - * number is between `min` and `max`, moreover that transition can only be - * crossed once. - * * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -6017,6 +5977,12 @@ error: /** + * If `to` is NULL, this creates first a new target state in the automata + * and then adds a transition from the `from` state to the target state + * activated by a succession of input of value `token` and whose number + * is between `min` and `max`, moreover that transition can only be crossed + * once. + * * @param am an automata * @param from the starting point of the transition * @param to the target point of the transition or NULL @@ -6024,13 +5990,6 @@ error: * @param min the minimum successive occurrences of token * @param max the maximum successive occurrences of token * @param data data associated to the transition - * - * If `to` is NULL, this creates first a new target state in the automata - * and then adds a transition from the `from` state to the target state - * activated by a succession of input of value `token` and whose number - * is between `min` and `max`, moreover that transition can only be crossed - * once. - * * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -6081,10 +6040,9 @@ error: } /** - * @param am an automata - * * Create a new disconnected state in the automata * + * @param am an automata * @returns the new state or NULL in case of error */ xmlAutomataStatePtr @@ -6095,14 +6053,13 @@ xmlAutomataNewState(xmlAutomataPtr am) { } /** - * @param am an automata - * @param from the starting point of the transition - * @param to the target point of the transition or NULL - * * If `to` is NULL, this creates first a new target state in the automata * and then adds an epsilon transition from the `from` state to the * target state * + * @param am an automata + * @param from the starting point of the transition + * @param to the target point of the transition or NULL * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -6117,16 +6074,15 @@ xmlAutomataNewEpsilon(xmlAutomataPtr am, xmlAutomataStatePtr from, } /** - * @param am an automata - * @param from the starting point of the transition - * @param to the target point of the transition or NULL - * @param lax allow to transition if not all all transitions have been activated - * * If `to` is NULL, this creates first a new target state in the automata * and then adds a an ALL transition from the `from` state to the * target state. That transition is an epsilon transition allowed only when * all transitions from the `from` node have been activated. * + * @param am an automata + * @param from the starting point of the transition + * @param to the target point of the transition or NULL + * @param lax allow to transition if not all all transitions have been activated * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -6141,12 +6097,11 @@ xmlAutomataNewAllTrans(xmlAutomataPtr am, xmlAutomataStatePtr from, } /** + * Create a new counter + * * @param am an automata * @param min the minimal value on the counter * @param max the maximal value on the counter - * - * Create a new counter - * * @returns the counter number or -1 in case of error */ int @@ -6165,15 +6120,14 @@ xmlAutomataNewCounter(xmlAutomataPtr am, int min, int max) { } /** - * @param am an automata - * @param from the starting point of the transition - * @param to the target point of the transition or NULL - * @param counter the counter associated to that transition - * * If `to` is NULL, this creates first a new target state in the automata * and then adds an epsilon transition from the `from` state to the target state * which will increment the counter provided * + * @param am an automata + * @param from the starting point of the transition + * @param to the target point of the transition or NULL + * @param counter the counter associated to that transition * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -6188,15 +6142,14 @@ xmlAutomataNewCountedTrans(xmlAutomataPtr am, xmlAutomataStatePtr from, } /** - * @param am an automata - * @param from the starting point of the transition - * @param to the target point of the transition or NULL - * @param counter the counter associated to that transition - * * If `to` is NULL, this creates first a new target state in the automata * and then adds an epsilon transition from the `from` state to the target state * which will be allowed only if the counter is within the right range. * + * @param am an automata + * @param from the starting point of the transition + * @param to the target point of the transition or NULL + * @param counter the counter associated to that transition * @returns the target state or NULL in case of error */ xmlAutomataStatePtr @@ -6211,11 +6164,10 @@ xmlAutomataNewCounterTrans(xmlAutomataPtr am, xmlAutomataStatePtr from, } /** - * @param am an automata - * * Compile the automata into a Reg Exp ready for being executed. * The automata should be free after this point. * + * @param am an automata * @returns the compiled regexp or NULL in case of error */ xmlRegexpPtr @@ -6233,10 +6185,9 @@ xmlAutomataCompile(xmlAutomataPtr am) { } /** - * @param am an automata - * * Checks if an automata is determinist. * + * @param am an automata * @returns 1 if true, 0 if not, and -1 in case of error */ int @@ -6384,11 +6335,10 @@ struct _xmlExpCtxt { }; /** - * @param maxNodes the maximum number of nodes - * @param dict optional dictionary to use internally - * * Creates a new context for manipulating expressions * + * @param maxNodes the maximum number of nodes + * @param dict optional dictionary to use internally * @returns the context or NULL in case of error */ xmlExpCtxtPtr @@ -6427,9 +6377,9 @@ xmlExpNewCtxt(int maxNodes, xmlDictPtr dict) { } /** - * @param ctxt an expression context - * * Free an expression context + * + * @param ctxt an expression context */ void xmlExpFreeCtxt(xmlExpCtxtPtr ctxt) { @@ -6578,12 +6528,11 @@ xmlExpNewNode(xmlExpCtxtPtr ctxt, xmlExpNodeType type) { } /** - * @param table the hash table - * * Get the unique entry from the hash table. The entry is created if * needed. `left` and `right` are consumed, i.e. their ref count will * be decremented by the operation. * + * @param table the hash table * @returns the pointer or NULL in case of error */ static xmlExpNodePtr @@ -6814,10 +6763,10 @@ xmlExpHashGetEntry(xmlExpCtxtPtr ctxt, xmlExpNodeType type, } /** + * Dereference the expression + * * @param ctxt the expression context * @param exp the expression - * - * Dereference the expression */ void xmlExpFree(xmlExpCtxtPtr ctxt, xmlExpNodePtr exp) { @@ -6856,9 +6805,9 @@ xmlExpFree(xmlExpCtxtPtr ctxt, xmlExpNodePtr exp) { } /** - * @param exp the expression - * * Increase the reference count of the expression + * + * @param exp the expression */ void xmlExpRef(xmlExpNodePtr exp) { @@ -6867,12 +6816,11 @@ xmlExpRef(xmlExpNodePtr exp) { } /** + * Get the atom associated to this name from that context + * * @param ctxt the expression context * @param name the atom name * @param len the atom name length in byte (or -1); - * - * Get the atom associated to this name from that context - * * @returns the node or NULL in case of error */ xmlExpNodePtr @@ -6886,15 +6834,14 @@ xmlExpNewAtom(xmlExpCtxtPtr ctxt, const xmlChar *name, int len) { } /** - * @param ctxt the expression context - * @param left left expression - * @param right right expression - * * Get the atom associated to the choice `left` | `right` * Note that `left` and `right` are consumed in the operation, to keep * an handle on them use xmlExpRef() and use xmlExpFree() to release them, * this is true even in case of failure (unless ctxt == NULL). * + * @param ctxt the expression context + * @param left left expression + * @param right right expression * @returns the node or NULL in case of error */ xmlExpNodePtr @@ -6910,15 +6857,14 @@ xmlExpNewOr(xmlExpCtxtPtr ctxt, xmlExpNodePtr left, xmlExpNodePtr right) { } /** - * @param ctxt the expression context - * @param left left expression - * @param right right expression - * * Get the atom associated to the sequence `left` , `right` * Note that `left` and `right` are consumed in the operation, to keep * an handle on them use xmlExpRef() and use xmlExpFree() to release them, * this is true even in case of failure (unless ctxt == NULL). * + * @param ctxt the expression context + * @param left left expression + * @param right right expression * @returns the node or NULL in case of error */ xmlExpNodePtr @@ -6934,16 +6880,15 @@ xmlExpNewSeq(xmlExpCtxtPtr ctxt, xmlExpNodePtr left, xmlExpNodePtr right) { } /** - * @param ctxt the expression context - * @param subset the expression to be repeated - * @param min the lower bound for the repetition - * @param max the upper bound for the repetition, -1 means infinite - * * Get the atom associated to the range (`subset`){`min`, `max`} * Note that `subset` is consumed in the operation, to keep * an handle on it use xmlExpRef() and use xmlExpFree() to release it, * this is true even in case of failure (unless ctxt == NULL). * + * @param ctxt the expression context + * @param subset the expression to be repeated + * @param min the lower bound for the repetition + * @param max the upper bound for the repetition, -1 means infinite * @returns the node or NULL in case of error */ xmlExpNodePtr @@ -6999,13 +6944,12 @@ tail: } /** + * Find all the strings used in `exp` and store them in `list` + * * @param ctxt the expression context * @param exp the expression * @param langList where to store the tokens * @param len the allocated length of `list` - * - * Find all the strings used in `exp` and store them in `list` - * * @returns the number of unique strings found, -1 in case of errors and * -2 if there is more than `len` strings */ @@ -7064,15 +7008,14 @@ tail: } /** - * @param ctxt the expression context - * @param exp the expression - * @param tokList where to store the tokens - * @param len the allocated length of `list` - * * Find all the strings that appears at the start of the languages * accepted by `exp` and store them in `list`. E.g. for (a, b) | c * it will return the list [a, c] * + * @param ctxt the expression context + * @param exp the expression + * @param tokList where to store the tokens + * @param len the allocated length of `list` * @returns the number of unique strings found, -1 in case of errors and * -2 if there is more than `len` strings */ @@ -7085,10 +7028,9 @@ xmlExpGetStart(xmlExpCtxtPtr ctxt, xmlExpNodePtr exp, } /** - * @param exp the expression - * * Finds if the expression is nillable, i.e. if it accepts the empty sequence * + * @param exp the expression * @returns 1 if nillable, 0 if not and -1 in case of error */ int @@ -7182,14 +7124,13 @@ xmlExpStringDeriveInt(xmlExpCtxtPtr ctxt, xmlExpNodePtr exp, const xmlChar *str) } /** + * Do one step of Brzozowski derivation of the expression `exp` with + * respect to the input string + * * @param ctxt the expression context * @param exp the expression * @param str the string * @param len the string len in bytes if available - * - * Do one step of Brzozowski derivation of the expression `exp` with - * respect to the input string - * * @returns the resulting expression or NULL in case of internal error */ xmlExpNodePtr @@ -7227,15 +7168,14 @@ xmlExpCheckCard(xmlExpNodePtr exp, xmlExpNodePtr sub) { static xmlExpNodePtr xmlExpExpDeriveInt(xmlExpCtxtPtr ctxt, xmlExpNodePtr exp, xmlExpNodePtr sub); /** + * Check if exp is a multiple of sub, i.e. if there is a finite number n + * so that sub{n} subsume exp + * * @param ctxt the expressions context * @param exp the englobing expression * @param sub the subexpression * @param mult the multiple expression * @param remain the remain from the derivation of the multiple - * - * Check if exp is a multiple of sub, i.e. if there is a finite number n - * so that sub{n} subsume exp - * * @returns the multiple value if successful, 0 if it is not a multiple * and -1 in case of internal error. */ @@ -7285,13 +7225,12 @@ xmlExpDivide(xmlExpCtxtPtr ctxt, xmlExpNodePtr exp, xmlExpNodePtr sub, } /** - * @param ctxt the expressions context - * @param exp the englobing expression - * @param sub the subexpression - * * Try to do a step of Brzozowski derivation but at a higher level * the input being a subexpression. * + * @param ctxt the expressions context + * @param exp the englobing expression + * @param sub the subexpression * @returns the resulting expression or NULL in case of internal error */ static xmlExpNodePtr @@ -7642,15 +7581,14 @@ xmlExpExpDeriveInt(xmlExpCtxtPtr ctxt, xmlExpNodePtr exp, xmlExpNodePtr sub) { } /** - * @param ctxt the expressions context - * @param exp the englobing expression - * @param sub the subexpression - * * Evaluates the expression resulting from `exp` consuming a sub expression `sub` * Based on algebraic derivation and sometimes direct Brzozowski derivation * it usually takes less than linear time and can handle expressions generating * infinite languages. * + * @param ctxt the expressions context + * @param exp the englobing expression + * @param sub the subexpression * @returns the resulting expression or NULL in case of internal error, the * result must be freed */ @@ -7672,13 +7610,12 @@ xmlExpExpDerive(xmlExpCtxtPtr ctxt, xmlExpNodePtr exp, xmlExpNodePtr sub) { } /** - * @param ctxt the expressions context - * @param exp the englobing expression - * @param sub the subexpression - * * Check whether `exp` accepts all the languages accepted by `sub` * the input being a subexpression. * + * @param ctxt the expressions context + * @param exp the englobing expression + * @param sub the subexpression * @returns 1 if true 0 if false and -1 in case of failure. */ int @@ -7867,9 +7804,6 @@ xmlExpParseExpr(xmlExpCtxtPtr ctxt) { } /** - * @param ctxt the expressions context - * @param expr the 0 terminated string - * * Minimal parser for regexps, it understand the following constructs * - string terminals * - choice operator | @@ -7880,6 +7814,8 @@ xmlExpParseExpr(xmlExpCtxtPtr ctxt) { * - infinite sequences { min, * } * There is minimal checkings made especially no checking on strings values * + * @param ctxt the expressions context + * @param expr the 0 terminated string * @returns a new expression or NULL in case of failure */ xmlExpNodePtr @@ -7975,10 +7911,10 @@ xmlExpDumpInt(xmlBufferPtr buf, xmlExpNodePtr expr, int glob) { xmlBufferWriteChar(buf, ")"); } /** + * Serialize the expression as compiled to the buffer + * * @param buf a buffer to receive the output * @param expr the compiled expression - * - * Serialize the expression as compiled to the buffer */ void xmlExpDump(xmlBufferPtr buf, xmlExpNodePtr expr) { @@ -7988,10 +7924,9 @@ xmlExpDump(xmlBufferPtr buf, xmlExpNodePtr expr) { } /** - * @param expr a compiled expression - * * Indicate the maximum number of input a expression can accept * + * @param expr a compiled expression * @returns the maximum length or -1 in case of error */ int @@ -8002,10 +7937,9 @@ xmlExpMaxToken(xmlExpNodePtr expr) { } /** - * @param ctxt an expression context - * * Debugging facility provides the number of allocated nodes at a that point * + * @param ctxt an expression context * @returns the number of nodes in use or -1 in case of error */ int @@ -8016,10 +7950,9 @@ xmlExpCtxtNbNodes(xmlExpCtxtPtr ctxt) { } /** - * @param ctxt an expression context - * * Debugging facility provides the number of allocated nodes over lifetime * + * @param ctxt an expression context * @returns the number of nodes ever allocated or -1 in case of error */ int diff --git a/xmlsave.c b/xmlsave.c index 096b54a3..2aa8531a 100644 --- a/xmlsave.c +++ b/xmlsave.c @@ -51,9 +51,9 @@ struct _xmlSaveCtxt { * * ************************************************************************/ /** - * @param out an output buffer - * * Handle an out of memory condition + * + * @param out an output buffer */ static void xmlSaveErrMemory(xmlOutputBufferPtr out) @@ -64,12 +64,12 @@ xmlSaveErrMemory(xmlOutputBufferPtr out) } /** + * Handle an out of memory condition + * * @param out an output buffer * @param code the error number * @param node the location of the error. * @param extra extra information - * - * Handle an out of memory condition */ static void xmlSaveErr(xmlOutputBufferPtr out, int code, xmlNodePtr node, @@ -223,13 +223,12 @@ xmlSerializeText(xmlOutputBufferPtr buf, const xmlChar *string, ************************************************************************/ /** - * @param ctxt save context - * @param indent indent string - * * Sets the indent string. * * @since 2.14.0 * + * @param ctxt save context + * @param indent indent string * @returns 0 on success, -1 if the string is NULL, empty or too long. */ int @@ -253,10 +252,10 @@ xmlSaveSetIndentString(xmlSaveCtxtPtr ctxt, const char *indent) { } /** + * Initialize a saving context + * * @param ctxt the saving context * @param options save options - * - * Initialize a saving context */ static void xmlSaveCtxtInit(xmlSaveCtxtPtr ctxt, int options) @@ -341,10 +340,10 @@ xmlSaveWriteText(xmlSaveCtxt *ctxt, const xmlChar *text, unsigned flags) { } /** + * Serialize the attribute in the buffer + * * @param ctxt save context * @param attr the attribute pointer - * - * Serialize the attribute in the buffer */ static void xmlSaveWriteAttrContent(xmlSaveCtxt *ctxt, xmlAttrPtr attr) @@ -372,10 +371,10 @@ xmlSaveWriteAttrContent(xmlSaveCtxt *ctxt, xmlAttrPtr attr) } /** + * This will dump the content the notation declaration as an XML DTD definition + * * @param buf the XML buffer output * @param nota A notation declaration - * - * This will dump the content the notation declaration as an XML DTD definition */ static void xmlBufDumpNotationDecl(xmlOutputBufferPtr buf, xmlNotationPtr nota) { @@ -398,11 +397,11 @@ xmlBufDumpNotationDecl(xmlOutputBufferPtr buf, xmlNotationPtr nota) { } /** + * This is called with the hash scan function, and just reverses args + * * @param nota A notation declaration * @param buf the XML buffer output * @param name unused - * - * This is called with the hash scan function, and just reverses args */ static void xmlBufDumpNotationDeclScan(void *nota, void *buf, @@ -411,10 +410,10 @@ xmlBufDumpNotationDeclScan(void *nota, void *buf, } /** + * This will dump the content of the notation table as an XML DTD definition + * * @param buf an xmlBufPtr output * @param table A notation table - * - * This will dump the content of the notation table as an XML DTD definition */ static void xmlBufDumpNotationTable(xmlOutputBufferPtr buf, xmlNotationTablePtr table) { @@ -422,10 +421,10 @@ xmlBufDumpNotationTable(xmlOutputBufferPtr buf, xmlNotationTablePtr table) { } /** + * Dump the occurrence operator of an element. + * * @param buf output buffer * @param cur element table - * - * Dump the occurrence operator of an element. */ static void xmlBufDumpElementOccur(xmlOutputBufferPtr buf, xmlElementContentPtr cur) { @@ -445,10 +444,10 @@ xmlBufDumpElementOccur(xmlOutputBufferPtr buf, xmlElementContentPtr cur) { } /** + * This will dump the content of the element table as an XML DTD definition + * * @param buf output buffer * @param content element table - * - * This will dump the content of the element table as an XML DTD definition */ static void xmlBufDumpElementContent(xmlOutputBufferPtr buf, @@ -517,11 +516,11 @@ xmlBufDumpElementContent(xmlOutputBufferPtr buf, } /** - * @param buf an xmlBufPtr output - * @param elem An element table - * * This will dump the content of the element declaration as an XML * DTD definition + * + * @param buf an xmlBufPtr output + * @param elem An element table */ static void xmlBufDumpElementDecl(xmlOutputBufferPtr buf, xmlElementPtr elem) { @@ -553,10 +552,10 @@ xmlBufDumpElementDecl(xmlOutputBufferPtr buf, xmlElementPtr elem) { } /** + * This will dump the content of the enumeration + * * @param buf output buffer * @param cur an enumeration - * - * This will dump the content of the enumeration */ static void xmlBufDumpEnumeration(xmlOutputBufferPtr buf, xmlEnumerationPtr cur) { @@ -571,11 +570,11 @@ xmlBufDumpEnumeration(xmlOutputBufferPtr buf, xmlEnumerationPtr cur) { xmlOutputBufferWrite(buf, 1, ")"); } /** - * @param buf output buffer - * @param attr An attribute declaration - * * This will dump the content of the attribute declaration as an XML * DTD definition + * + * @param buf output buffer + * @param attr An attribute declaration */ static void xmlBufDumpAttributeDecl(xmlOutputBufferPtr buf, xmlAttributePtr attr) { @@ -652,11 +651,11 @@ xmlBufDumpAttributeDecl(xmlOutputBufferPtr buf, xmlAttributePtr attr) { } /** - * @param buf output buffer - * @param content entity content. - * * This will dump the quoted string value, taking care of the special * treatment required by % + * + * @param buf output buffer + * @param content entity content. */ static void xmlBufDumpEntityContent(xmlOutputBufferPtr buf, const xmlChar *content) { @@ -691,10 +690,10 @@ xmlBufDumpEntityContent(xmlOutputBufferPtr buf, const xmlChar *content) { } /** + * This will dump the content of the entity table as an XML DTD definition + * * @param buf an xmlBufPtr output * @param ent An entity table - * - * This will dump the content of the entity table as an XML DTD definition */ static void xmlBufDumpEntityDecl(xmlOutputBufferPtr buf, xmlEntityPtr ent) { @@ -833,10 +832,10 @@ xmlSaveWriteIndent(xmlSaveCtxtPtr ctxt, int extra) } /** + * Write out formatting for non-significant whitespace output. + * * @param ctxt The save context * @param extra Number of extra indents to apply to ctxt->level - * - * Write out formatting for non-significant whitespace output. */ static void xmlOutputBufferWriteWSNonSig(xmlSaveCtxtPtr ctxt, int extra) @@ -854,13 +853,13 @@ xmlOutputBufferWriteWSNonSig(xmlSaveCtxtPtr ctxt, int extra) } /** - * @param buf the XML buffer output - * @param cur a namespace - * @param ctxt the output save context. Optional. - * * Dump a local Namespace definition. * Should be called in the context of attributes dumps. * If `ctxt` is supplied, `buf` should be its buffer. + * + * @param buf the XML buffer output + * @param cur a namespace + * @param ctxt the output save context. Optional. */ static void xmlNsDumpOutput(xmlOutputBufferPtr buf, xmlNsPtr cur, xmlSaveCtxtPtr ctxt) { @@ -893,11 +892,11 @@ xmlNsDumpOutput(xmlOutputBufferPtr buf, xmlNsPtr cur, xmlSaveCtxtPtr ctxt) { } /** - * @param ctxt the save context - * @param cur the first namespace - * * Dump a list of local namespace definitions to a save context. * Should be called in the context of attribute dumps. + * + * @param ctxt the save context + * @param cur the first namespace */ static void xmlNsListDumpOutputCtxt(xmlSaveCtxtPtr ctxt, xmlNsPtr cur) { @@ -908,10 +907,10 @@ xmlNsListDumpOutputCtxt(xmlSaveCtxtPtr ctxt, xmlNsPtr cur) { } /** + * Serialize a list of namespace definitions. + * * @param buf the XML buffer output * @param cur the first namespace - * - * Serialize a list of namespace definitions. */ void xmlNsListDumpOutput(xmlOutputBufferPtr buf, xmlNsPtr cur) { @@ -922,10 +921,10 @@ xmlNsListDumpOutput(xmlOutputBufferPtr buf, xmlNsPtr cur) { } /** + * Dump the XML document DTD, if any. + * * @param ctxt the save context * @param dtd the pointer to the DTD - * - * Dump the XML document DTD, if any. */ static void xmlDtdDumpOutput(xmlSaveCtxtPtr ctxt, xmlDtdPtr dtd) { @@ -976,10 +975,10 @@ xmlDtdDumpOutput(xmlSaveCtxtPtr ctxt, xmlDtdPtr dtd) { } /** + * Dump an XML attribute + * * @param ctxt the save context * @param cur the attribute pointer - * - * Dump an XML attribute */ static void xmlAttrDumpOutput(xmlSaveCtxtPtr ctxt, xmlAttrPtr cur) { @@ -1016,10 +1015,10 @@ xmlAttrDumpOutput(xmlSaveCtxtPtr ctxt, xmlAttrPtr cur) { #ifdef LIBXML_HTML_ENABLED /** + * Dump an HTML node, recursive behaviour, children are printed too. + * * @param ctxt the save context * @param cur the current node - * - * Dump an HTML node, recursive behaviour, children are printed too. */ static int htmlNodeDumpOutputInternal(xmlSaveCtxtPtr ctxt, xmlNodePtr cur) { @@ -1067,10 +1066,10 @@ htmlNodeDumpOutputInternal(xmlSaveCtxtPtr ctxt, xmlNodePtr cur) { #endif /** + * Dump an XML node, recursive behaviour, children are printed too. + * * @param ctxt the save context * @param cur the current node - * - * Dump an XML node, recursive behaviour, children are printed too. */ static void xmlNodeDumpOutputInternal(xmlSaveCtxtPtr ctxt, xmlNodePtr cur) { @@ -1330,11 +1329,11 @@ xmlNodeDumpOutputInternal(xmlSaveCtxtPtr ctxt, xmlNodePtr cur) { } /** + * Dump an XML document. + * * @param ctxt the save context * @param cur the document * @param encoding character encoding (optional) - * - * Dump an XML document. */ static int xmlSaveDocInternal(xmlSaveCtxtPtr ctxt, xmlDocPtr cur, @@ -1466,10 +1465,9 @@ xmlSaveDocInternal(xmlSaveCtxtPtr ctxt, xmlDocPtr cur, ************************************************************************/ /** - * @param node the node - * * Check if a node is an empty xhtml node * + * @param node the node * @returns 1 if the node is an empty node, 0 if not and -1 in case of error */ static int @@ -1532,10 +1530,10 @@ xhtmlIsEmpty(xmlNodePtr node) { } /** + * Dump a list of XML attributes + * * @param ctxt the save context * @param cur the first attribute pointer - * - * Dump a list of XML attributes */ static void xhtmlAttrListDumpOutput(xmlSaveCtxtPtr ctxt, xmlAttrPtr cur) { @@ -1600,10 +1598,10 @@ xhtmlAttrListDumpOutput(xmlSaveCtxtPtr ctxt, xmlAttrPtr cur) { } /** + * Dump an XHTML node, recursive behaviour, children are printed too. + * * @param ctxt the save context * @param cur the current node - * - * Dump an XHTML node, recursive behaviour, children are printed too. */ static void xhtmlNodeDumpOutput(xmlSaveCtxtPtr ctxt, xmlNodePtr cur) { @@ -1933,10 +1931,6 @@ xhtmlNodeDumpOutput(xmlSaveCtxtPtr ctxt, xmlNodePtr cur) { ************************************************************************/ /** - * @param fd a file descriptor number - * @param encoding the encoding name to use (optional) - * @param options a set of xmlSaveOptions - * * Create a document saving context serializing to a file descriptor * with the encoding and the options given. * @@ -1946,6 +1940,9 @@ xhtmlNodeDumpOutput(xmlSaveCtxtPtr ctxt, xmlNodePtr cur) { * This function doesn't allow to distinguish unsupported * encoding errors from failed memory allocations. * + * @param fd a file descriptor number + * @param encoding the encoding name to use (optional) + * @param options a set of xmlSaveOptions * @returns a new serialization context or NULL in case of error. */ xmlSaveCtxtPtr @@ -1964,10 +1961,6 @@ xmlSaveToFd(int fd, const char *encoding, int options) } /** - * @param filename a file name or an URL - * @param encoding the encoding name to use or NULL - * @param options a set of xmlSaveOptions - * * Create a document saving context serializing to a filename * with the encoding and the options given. * @@ -1977,6 +1970,9 @@ xmlSaveToFd(int fd, const char *encoding, int options) * This function doesn't allow to distinguish unsupported * encoding errors from failed memory allocations. * + * @param filename a file name or an URL + * @param encoding the encoding name to use or NULL + * @param options a set of xmlSaveOptions * @returns a new serialization context or NULL in case of error. */ xmlSaveCtxtPtr @@ -1997,10 +1993,6 @@ xmlSaveToFilename(const char *filename, const char *encoding, int options) } /** - * @param buffer a buffer - * @param encoding the encoding name to use or NULL - * @param options a set of xmlSaveOptions - * * Create a document saving context serializing to a buffer * with the encoding and the options given. * @@ -2010,6 +2002,9 @@ xmlSaveToFilename(const char *filename, const char *encoding, int options) * This function doesn't allow to distinguish unsupported * encoding errors from failed memory allocations. * + * @param buffer a buffer + * @param encoding the encoding name to use or NULL + * @param options a set of xmlSaveOptions * @returns a new serialization context or NULL in case of error. */ @@ -2029,12 +2024,6 @@ xmlSaveToBuffer(xmlBufferPtr buffer, const char *encoding, int options) } /** - * @param iowrite an I/O write function - * @param ioclose an I/O close function - * @param ioctx an I/O handler - * @param encoding the encoding name to use or NULL - * @param options a set of xmlSaveOptions - * * Create a document saving context serializing to a file descriptor * with the encoding and the options given * @@ -2044,6 +2033,11 @@ xmlSaveToBuffer(xmlBufferPtr buffer, const char *encoding, int options) * This function doesn't allow to distinguish unsupported * encoding errors from failed memory allocations. * + * @param iowrite an I/O write function + * @param ioclose an I/O close function + * @param ioctx an I/O handler + * @param encoding the encoding name to use or NULL + * @param options a set of xmlSaveOptions * @returns a new serialization context or NULL in case of error. */ xmlSaveCtxtPtr @@ -2064,15 +2058,14 @@ xmlSaveToIO(xmlOutputWriteCallback iowrite, } /** - * @param ctxt a document saving context - * @param doc a document - * * Serialize a document. * * If the save context has no encoding, uses the document's * encoding. If the document has no encoding, uses ASCII * without an encoding declaration. * + * @param ctxt a document saving context + * @param doc a document * @returns 0 on success or -1 in case of error. */ long @@ -2087,13 +2080,12 @@ xmlSaveDoc(xmlSaveCtxtPtr ctxt, xmlDocPtr doc) } /** - * @param ctxt a document saving context - * @param cur the root of the subtree to save - * * Serialize a subtree starting. * * If the save context has no encoding, uses UTF-8. * + * @param ctxt a document saving context + * @param cur the root of the subtree to save * @returns 0 on success or -1 in case of error. */ long @@ -2120,11 +2112,10 @@ xmlSaveTree(xmlSaveCtxtPtr ctxt, xmlNodePtr cur) } /** - * @param ctxt save context - * @param cur notation - * * Serialize a notation declaration. * + * @param ctxt save context + * @param cur notation * @returns 0 on succes, -1 on error. */ int @@ -2136,11 +2127,10 @@ xmlSaveNotationDecl(xmlSaveCtxtPtr ctxt, xmlNotationPtr cur) { } /** - * @param ctxt save context - * @param cur notation table - * * Serialize notation declarations of a document. * + * @param ctxt save context + * @param cur notation table * @returns 0 on succes, -1 on error. */ int @@ -2152,11 +2142,10 @@ xmlSaveNotationTable(xmlSaveCtxtPtr ctxt, xmlNotationTablePtr cur) { } /** - * @param ctxt a document saving context - * * Flush a document saving context, i.e. make sure that all * buffered input has been processed. * + * @param ctxt a document saving context * @returns the number of bytes written or -1 in case of error. */ int @@ -2168,11 +2157,10 @@ xmlSaveFlush(xmlSaveCtxtPtr ctxt) } /** - * @param ctxt a document saving context - * * Close a document saving context, i.e. make sure that all * buffered input has been processed and free the context struct. * + * @param ctxt a document saving context * @returns the number of bytes written or -1 in case of error. */ int @@ -2187,13 +2175,12 @@ xmlSaveClose(xmlSaveCtxtPtr ctxt) } /** - * @param ctxt a document saving context - * * Close a document saving context, i.e. make sure that all * buffered input has been processed and free the context struct. * * @since 2.13.0 * + * @param ctxt a document saving context * @returns an xmlParserErrors code. */ xmlParserErrors @@ -2216,14 +2203,13 @@ xmlSaveFinish(xmlSaveCtxtPtr ctxt) } /** - * @param ctxt a document saving context - * @param escape the escaping function - * - * @deprecated Don't use. - * * Set a custom escaping function to be used for text in element * content. * + * @deprecated Don't use. + * + * @param ctxt a document saving context + * @param escape the escaping function * @returns 0 if successful or -1 in case of error. */ int @@ -2235,13 +2221,12 @@ xmlSaveSetEscape(xmlSaveCtxtPtr ctxt, xmlCharEncodingOutputFunc escape) } /** - * @param ctxt a document saving context - * @param escape the escaping function + * Has no effect. * * @deprecated Don't use. * - * Has no effect. - * + * @param ctxt a document saving context + * @param escape the escaping function * @returns 0 if successful or -1 in case of error. */ int @@ -2259,11 +2244,11 @@ xmlSaveSetAttrEscape(xmlSaveCtxtPtr ctxt, ************************************************************************/ /** + * Serialize attribute text to an output buffer. + * * @param buf output buffer * @param doc the document * @param string the text content - * - * Serialize attribute text to an output buffer. */ void xmlBufAttrSerializeTxtContent(xmlOutputBufferPtr buf, xmlDocPtr doc, @@ -2277,12 +2262,12 @@ xmlBufAttrSerializeTxtContent(xmlOutputBufferPtr buf, xmlDocPtr doc, } /** + * Serialize attribute text to an xmlBuffer. + * * @param buf the XML buffer output * @param doc the document * @param attr the attribute node * @param string the text content - * - * Serialize attribute text to an xmlBuffer. */ void xmlAttrSerializeTxtContent(xmlBufferPtr buf, xmlDocPtr doc, @@ -2302,12 +2287,6 @@ xmlAttrSerializeTxtContent(xmlBufferPtr buf, xmlDocPtr doc, } /** - * @param buf the XML buffer output - * @param doc the document - * @param cur the current node - * @param level the initial indenting level - * @param format is formatting allowed - * * Serialize an XML node to an xmlBuffer. * * Uses the document's encoding. If the document has no encoding, @@ -2319,6 +2298,11 @@ xmlAttrSerializeTxtContent(xmlBufferPtr buf, xmlDocPtr doc, * Since this is using xmlBuffer structures it is limited to 2GB and * somewhat deprecated, use xmlNodeDumpOutput() instead. * + * @param buf the XML buffer output + * @param doc the document + * @param cur the current node + * @param level the initial indenting level + * @param format is formatting allowed * @returns the number of bytes written to the buffer or -1 in case of error */ int @@ -2346,12 +2330,6 @@ xmlNodeDump(xmlBufferPtr buf, xmlDocPtr doc, xmlNodePtr cur, int level, } /** - * @param buf the XML buffer output - * @param doc the document - * @param cur the current node - * @param level the imbrication level for indenting - * @param format is formatting allowed - * * Serialize an XML node to an xmlBuf. * * Uses the document's encoding. If the document has no encoding, @@ -2360,6 +2338,11 @@ xmlNodeDump(xmlBufferPtr buf, xmlDocPtr doc, xmlNodePtr cur, int level, * Note that `format` only works if the document was parsed with * XML_PARSE_NOBLANKS. * + * @param buf the XML buffer output + * @param doc the document + * @param cur the current node + * @param level the imbrication level for indenting + * @param format is formatting allowed * @returns the number of bytes written to the buffer, in case of error 0 * is returned or `buf` stores the error */ @@ -2404,14 +2387,13 @@ xmlBufNodeDump(xmlBufPtr buf, xmlDocPtr doc, xmlNodePtr cur, int level, } /** - * @param f the FILE * for the output - * @param doc the document - * @param cur the current node - * * Serialize an XML node to a `FILE`. * * Uses the document's encoding. If the document has no encoding, * uses ASCII without an encoding declaration. + * @param f the FILE * for the output + * @param doc the document + * @param cur the current node */ void xmlElemDump(FILE * f, xmlDocPtr doc, xmlNodePtr cur) @@ -2443,13 +2425,6 @@ xmlElemDump(FILE * f, xmlDocPtr doc, xmlNodePtr cur) ************************************************************************/ /** - * @param buf the XML buffer output - * @param doc the document - * @param cur the current node - * @param level the imbrication level for indenting - * @param format is formatting allowed - * @param encoding an optional encoding string - * * Serialize an XML node to an output buffer. * * If `encoding` is NULL, uses the document's encoding. If the @@ -2458,6 +2433,12 @@ xmlElemDump(FILE * f, xmlDocPtr doc, xmlNodePtr cur) * * Note that `format` only works if the document was parsed with * XML_PARSE_NOBLANKS. + * @param buf the XML buffer output + * @param doc the document + * @param cur the current node + * @param level the imbrication level for indenting + * @param format is formatting allowed + * @param encoding an optional encoding string */ void xmlNodeDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr doc, xmlNodePtr cur, @@ -2535,12 +2516,6 @@ xmlDocDumpInternal(xmlOutputBufferPtr buf, xmlDocPtr doc, const char *encoding, } /** - * @param out_doc Document to generate XML text from - * @param doc_txt_ptr Memory pointer for allocated XML text - * @param doc_txt_len Length of the generated XML text - * @param txt_encoding Character encoding to use when generating XML text - * @param format should formatting spaces been added - * * Serialize an XML document to memory. * * If `encoding` is NULL, uses the document's encoding. If the @@ -2552,6 +2527,11 @@ xmlDocDumpInternal(xmlOutputBufferPtr buf, xmlDocPtr doc, const char *encoding, * * Note that `format` only works if the document was parsed with * XML_PARSE_NOBLANKS. + * @param out_doc Document to generate XML text from + * @param doc_txt_ptr Memory pointer for allocated XML text + * @param doc_txt_len Length of the generated XML text + * @param txt_encoding Character encoding to use when generating XML text + * @param format should formatting spaces been added */ void @@ -2590,12 +2570,12 @@ xmlDocDumpFormatMemoryEnc(xmlDocPtr out_doc, xmlChar **doc_txt_ptr, } /** + * Same as xmlDocDumpFormatMemoryEnc() with `encoding` set to + * NULL and `format` set to 0. + * * @param cur the document * @param mem OUT: the memory pointer * @param size OUT: the memory length - * - * Same as xmlDocDumpFormatMemoryEnc() with `encoding` set to - * NULL and `format` set to 0. */ void xmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int *size) { @@ -2603,13 +2583,13 @@ xmlDocDumpMemory(xmlDocPtr cur, xmlChar**mem, int *size) { } /** + * Same as xmlDocDumpFormatMemoryEnc() with `encoding` set to + * NULL. + * * @param cur the document * @param mem OUT: the memory pointer * @param size OUT: the memory length * @param format should formatting spaces been added - * - * Same as xmlDocDumpFormatMemoryEnc() with `encoding` set to - * NULL. */ void xmlDocDumpFormatMemory(xmlDocPtr cur, xmlChar**mem, int *size, int format) { @@ -2617,12 +2597,12 @@ xmlDocDumpFormatMemory(xmlDocPtr cur, xmlChar**mem, int *size, int format) { } /** + * Same as xmlDocDumpFormatMemoryEnc() with `format` set to 0. + * * @param out_doc Document to generate XML text from * @param doc_txt_ptr Memory pointer for allocated XML text * @param doc_txt_len Length of the generated XML text * @param txt_encoding Character encoding to use when generating XML text - * - * Same as xmlDocDumpFormatMemoryEnc() with `format` set to 0. */ void @@ -2633,10 +2613,6 @@ xmlDocDumpMemoryEnc(xmlDocPtr out_doc, xmlChar **doc_txt_ptr, } /** - * @param f the FILE* - * @param cur the document - * @param format should formatting spaces been added - * * Serialize an XML document to a `FILE`. * * Uses the document's encoding. If the document has no encoding, @@ -2645,6 +2621,9 @@ xmlDocDumpMemoryEnc(xmlDocPtr out_doc, xmlChar **doc_txt_ptr, * Note that `format` only works if the document was parsed with * XML_PARSE_NOBLANKS. * + * @param f the FILE* + * @param cur the document + * @param format should formatting spaces been added * @returns the number of bytes written or -1 in case of failure. */ int @@ -2664,14 +2643,13 @@ xmlDocFormatDump(FILE *f, xmlDocPtr cur, int format) { } /** - * @param f the FILE* - * @param cur the document - * * Serialize an XML document to a `FILE`. * * Uses the document's encoding. If the document has no encoding, * uses ASCII without an encoding declaration. * + * @param f the FILE* + * @param cur the document * @returns the number of bytes written or -1 in case of failure. */ int @@ -2680,14 +2658,13 @@ xmlDocDump(FILE *f, xmlDocPtr cur) { } /** - * @param buf an output I/O buffer - * @param cur the document - * @param encoding the encoding if any assuming the I/O layer handles the transcoding - * * Same as xmlSaveFormatFileTo() with `format` set to 0. * * WARNING: This calls xmlOutputBufferClose() and frees `buf`. * + * @param buf an output I/O buffer + * @param cur the document + * @param encoding the encoding if any assuming the I/O layer handles the transcoding * @returns the number of bytes written or -1 in case of failure. */ int @@ -2696,11 +2673,6 @@ xmlSaveFileTo(xmlOutputBufferPtr buf, xmlDocPtr cur, const char *encoding) { } /** - * @param buf an output I/O buffer - * @param cur the document - * @param encoding the encoding if any assuming the I/O layer handles the transcoding - * @param format should formatting spaces been added - * * Serialize an XML document to an output buffer. * * If the output buffer already uses a (non-default) encoding, @@ -2713,6 +2685,10 @@ xmlSaveFileTo(xmlOutputBufferPtr buf, xmlDocPtr cur, const char *encoding) { * * WARNING: This calls xmlOutputBufferClose() and frees `buf`. * + * @param buf an output I/O buffer + * @param cur the document + * @param encoding the encoding if any assuming the I/O layer handles the transcoding + * @param format should formatting spaces been added * @returns the number of bytes written or -1 in case of failure. */ int @@ -2733,11 +2709,6 @@ xmlSaveFormatFileTo(xmlOutputBufferPtr buf, xmlDocPtr cur, } /** - * @param filename the filename or URL to output - * @param cur the document being saved - * @param encoding the name of the encoding to use or NULL. - * @param format should formatting spaces be added. - * * Serialize an XML document to a file using the given encoding. * If `filename` is `"-"`, stdout is used. This is potentially * insecure and might be changed in a future version. @@ -2749,6 +2720,10 @@ xmlSaveFormatFileTo(xmlOutputBufferPtr buf, xmlDocPtr cur, * Note that `format` only works if the document was parsed with * XML_PARSE_NOBLANKS. * + * @param filename the filename or URL to output + * @param cur the document being saved + * @param encoding the name of the encoding to use or NULL. + * @param format should formatting spaces be added. * @returns the number of bytes written or -1 in case of error. */ int @@ -2775,12 +2750,11 @@ xmlSaveFormatFileEnc( const char * filename, xmlDocPtr cur, /** + * Same as xmlSaveFormatFileEnc() with `format` set to 0. + * * @param filename the filename (or URL) * @param cur the document * @param encoding the name of an encoding (or NULL) - * - * Same as xmlSaveFormatFileEnc() with `format` set to 0. - * * @returns the number of bytes written or -1 in case of failure. */ int @@ -2789,12 +2763,11 @@ xmlSaveFileEnc(const char *filename, xmlDocPtr cur, const char *encoding) { } /** + * Same as xmlSaveFormatFileEnc() with `encoding` set to NULL. + * * @param filename the filename (or URL) * @param cur the document * @param format should formatting spaces been added - * - * Same as xmlSaveFormatFileEnc() with `encoding` set to NULL. - * * @returns the number of bytes written or -1 in case of failure. */ int @@ -2803,12 +2776,11 @@ xmlSaveFormatFile(const char *filename, xmlDocPtr cur, int format) { } /** - * @param filename the filename (or URL) - * @param cur the document - * * Same as xmlSaveFormatFileEnc() with `encoding` set to NULL * and `format` set to 0. * + * @param filename the filename (or URL) + * @param cur the document * @returns the number of bytes written or -1 in case of failure. */ int diff --git a/xmlschemas.c b/xmlschemas.c index 71bff12b..bd846ac0 100644 --- a/xmlschemas.c +++ b/xmlschemas.c @@ -1085,7 +1085,6 @@ xmlSchemaParseAttributeGroupRef(xmlSchemaParserCtxtPtr pctxt, /** * @param type the type of the schema item - * * @returns the component name of a schema item. */ static const xmlChar * @@ -1140,7 +1139,6 @@ xmlSchemaItemTypeToStr(xmlSchemaTypeType type) /** * @param item the type of the schema item - * * @returns the component name of a schema item. */ static const xmlChar * @@ -1159,7 +1157,6 @@ xmlSchemaGetComponentTypeStr(xmlSchemaBasicItemPtr item) /** * @param item a schema component - * * @returns node associated with the schema component. * NOTE that such a node need not be available; plus, a component's * node need not to reflect the component directly, since there is no @@ -1210,7 +1207,6 @@ xmlSchemaGetComponentNode(xmlSchemaBasicItemPtr item) #if 0 /** * @param item a schema component - * * @returns the next sibling of the schema component. */ static xmlSchemaBasicItemPtr @@ -1252,10 +1248,8 @@ xmlSchemaGetNextComponent(xmlSchemaBasicItemPtr item) * @param buf the string buffer * @param namespaceName the namespace name * @param localName the local name - * * @returns the given QName in the format "{namespaceName}localName" or * just "localName" if `namespaceName` is NULL. - * * @returns the localName if `namespaceName` is NULL, a formatted * string otherwise. */ @@ -1422,7 +1416,6 @@ xmlSchemaGetIDCDesignation(xmlChar **buf, xmlSchemaIDCPtr idc) /** * @param pc the type of processContents - * * @returns a string representation of the type of * processContents. */ @@ -1442,14 +1435,13 @@ xmlSchemaWildcardPCToString(int pc) } /** + * Get a the canonical representation of the value. + * The caller has to free the returned retValue. + * * @param val the precomputed value * @param retValue the returned value * @param ws the whitespace type of the value * @param for_hash non-zero if this is supposed to generate a string for hashing - * - * Get a the canonical representation of the value. - * The caller has to free the returned retValue. - * * @returns 0 if the value could be built and -1 in case of * API errors or if the value type is not supported yet. */ @@ -1548,14 +1540,6 @@ xmlSchemaGetCanonValueHash(xmlSchemaValPtr val, } /** - * @param buf the string buffer - * @param itemDes the designation of the item - * @param item the item as an object - * @param itemNode the node of the item - * - * @returns a representation of the given item used - * for error reports. - * * The following order is used to build the resulting * designation if the arguments are not NULL: * 1a. If itemDes not NULL -> itemDes @@ -1567,6 +1551,12 @@ xmlSchemaGetCanonValueHash(xmlSchemaValPtr val, * If the itemNode is an attribute node, the name of the attribute * will be appended to the result. * + * @param buf the string buffer + * @param itemDes the designation of the item + * @param item the item as an object + * @param itemNode the node of the item + * @returns a representation of the given item used + * for error reports. * @returns the formatted string and sets `buf` to the resulting value. */ static xmlChar* @@ -1777,12 +1767,11 @@ xmlSchemaFormatItemForReport(xmlChar **buf, } /** + * Builds a string consisting of all enumeration elements. + * * @param actxt schema context * @param buf the string buffer * @param type the type holding the enumeration facets - * - * Builds a string consisting of all enumeration elements. - * * @returns a string of all enumeration elements. */ static const xmlChar * @@ -1850,9 +1839,9 @@ xmlSchemaFormatFacetEnumSet(xmlSchemaAbstractCtxtPtr actxt, ************************************************************************/ /** - * @param ctxt schema parser context - * * Handle an out of memory condition + * + * @param ctxt schema parser context */ static void xmlSchemaPErrMemory(xmlSchemaParserCtxtPtr ctxt) @@ -1918,14 +1907,14 @@ xmlSchemaPErrFull(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, int code, } /** + * Handle a parser error + * * @param ctxt the parsing context * @param node the context node * @param code the error code * @param msg the error message * @param str1 extra data * @param str2 extra data - * - * Handle a parser error */ static void LIBXML_ATTR_FORMAT(4,0) xmlSchemaPErr(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, int code, @@ -1936,6 +1925,8 @@ xmlSchemaPErr(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, int code, } /** + * Handle a parser error + * * @param ctxt the parsing context * @param node the context node * @param child the current child @@ -1943,8 +1934,6 @@ xmlSchemaPErr(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, int code, * @param msg the error message * @param str1 extra data * @param str2 extra data - * - * Handle a parser error */ static void LIBXML_ATTR_FORMAT(5,0) xmlSchemaPErr2(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, @@ -1959,6 +1948,8 @@ xmlSchemaPErr2(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, /** + * Handle a parser error + * * @param ctxt the parsing context * @param node the context node * @param code the error code @@ -1971,8 +1962,6 @@ xmlSchemaPErr2(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, * @param str3 extra parameter for the message display * @param str4 extra parameter for the message display * @param str5 extra parameter for the message display - * - * Handle a parser error */ static void LIBXML_ATTR_FORMAT(7,0) xmlSchemaPErrExt(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, int code, @@ -1993,9 +1982,9 @@ xmlSchemaPErrExt(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, int code, ************************************************************************/ /** - * @param ctxt schema validation context - * * Handle an out of memory condition + * + * @param ctxt schema validation context */ static void xmlSchemaVErrMemory(xmlSchemaValidCtxtPtr ctxt) @@ -2063,6 +2052,8 @@ xmlSchemaVErrFull(xmlSchemaValidCtxtPtr ctxt, xmlNodePtr node, int code, #define WXS_ERROR_TYPE_ERROR 1 #define WXS_ERROR_TYPE_WARNING 2 /** + * Handle a validation error + * * @param ctxt the validation context * @param errorLevel the error level * @param code the error code @@ -2073,8 +2064,6 @@ xmlSchemaVErrFull(xmlSchemaValidCtxtPtr ctxt, xmlNodePtr node, int code, * @param str2 extra data * @param str3 extra data * @param str4 extra data - * - * Handle a validation error */ static void LIBXML_ATTR_FORMAT(6,0) xmlSchemaErr4Line(xmlSchemaAbstractCtxtPtr ctxt, @@ -2158,6 +2147,8 @@ xmlSchemaErr4Line(xmlSchemaAbstractCtxtPtr ctxt, } /** + * Handle a validation error + * * @param actxt the validation context * @param error the error code * @param node the context node @@ -2165,8 +2156,6 @@ xmlSchemaErr4Line(xmlSchemaAbstractCtxtPtr ctxt, * @param str1 extra data * @param str2 extra data * @param str3 extra data - * - * Handle a validation error */ static void LIBXML_ATTR_FORMAT(4,0) xmlSchemaErr3(xmlSchemaAbstractCtxtPtr actxt, @@ -2795,14 +2784,14 @@ xmlSchemaFacetErr(xmlSchemaAbstractCtxtPtr actxt, /** + * Reports an illegal attribute. + * * @param ctxt the schema validation context * @param error the error code * @param ownerItem the owner as a schema object * @param ownerElem the owner as an element node * @param name name of the attribute * @param message the error message - * - * Reports an illegal attribute. */ static void xmlSchemaPMissingAttrErr(xmlSchemaParserCtxtPtr ctxt, @@ -2827,6 +2816,9 @@ xmlSchemaPMissingAttrErr(xmlSchemaParserCtxtPtr ctxt, /** + * Used to report QName attribute values that failed to resolve + * to schema components. + * * @param ctxt the schema validation context * @param error the error code * @param ownerItem the owner as a schema object @@ -2836,9 +2828,6 @@ xmlSchemaPMissingAttrErr(xmlSchemaParserCtxtPtr ctxt, * @param refURI the referenced namespace URI * @param refType the referenced type * @param refTypeStr the referenced type string - * - * Used to report QName attribute values that failed to resolve - * to schema components. */ static void xmlSchemaPResCompAttrErr(xmlSchemaParserCtxtPtr ctxt, @@ -2867,14 +2856,14 @@ xmlSchemaPResCompAttrErr(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports an illegal attribute during the parse. + * * @param ctxt the schema parser context * @param error the error code * @param ownerDes the designation of the owner * @param ownerItem the owner as a schema object * @param attr the illegal attribute node * @param msg the error message - * - * Reports an illegal attribute during the parse. */ static void xmlSchemaPCustomAttrErr(xmlSchemaParserCtxtPtr ctxt, @@ -2908,12 +2897,12 @@ xmlSchemaPCustomAttrErr(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports an illegal attribute during the parse. + * * @param ctxt the schema parser context * @param error the error code * @param ownerComp the attribute's owner item (unused) * @param attr the illegal attribute node - * - * Reports an illegal attribute during the parse. */ static void xmlSchemaPIllegalAttrErr(xmlSchemaParserCtxtPtr ctxt, @@ -2933,6 +2922,8 @@ xmlSchemaPIllegalAttrErr(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports an error during parsing. + * * @param ctxt the schema parser context * @param error the error code * @param item the schema item @@ -2941,8 +2932,6 @@ xmlSchemaPIllegalAttrErr(xmlSchemaParserCtxtPtr ctxt, * @param str1 an optional param for the error message * @param str2 an optional param for the error message * @param str3 an optional param for the error message - * - * Reports an error during parsing. */ static void LIBXML_ATTR_FORMAT(5,0) xmlSchemaPCustomErrExt(xmlSchemaParserCtxtPtr ctxt, @@ -2969,14 +2958,14 @@ xmlSchemaPCustomErrExt(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports an error during parsing. + * * @param ctxt the schema parser context * @param error the error code * @param item the schema item * @param itemElem the node of the schema item * @param message the error message * @param str1 the optional param for the error message - * - * Reports an error during parsing. */ static void LIBXML_ATTR_FORMAT(5,0) xmlSchemaPCustomErr(xmlSchemaParserCtxtPtr ctxt, @@ -2991,6 +2980,8 @@ xmlSchemaPCustomErr(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports an attribute use error during parsing. + * * @param ctxt the schema parser context * @param error the error code * @param node the context node @@ -3001,8 +2992,6 @@ xmlSchemaPCustomErr(xmlSchemaParserCtxtPtr ctxt, * @param str2 the optional param for the error message * @param str3 the optional param for the error message * @param str4 the optional param for the error message - * - * Reports an attribute use error during parsing. */ static void LIBXML_ATTR_FORMAT(6,0) xmlSchemaPAttrUseErr4(xmlSchemaParserCtxtPtr ctxt, @@ -3031,13 +3020,13 @@ xmlSchemaPAttrUseErr4(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports an illegal facet for atomic simple types. + * * @param ctxt the schema parser context * @param error the error code * @param type the schema type * @param baseType the base type of type * @param facet the illegal facet - * - * Reports an illegal facet for atomic simple types. */ static void xmlSchemaPIllegalFacetAtomicErr(xmlSchemaParserCtxtPtr ctxt, @@ -3060,12 +3049,12 @@ xmlSchemaPIllegalFacetAtomicErr(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports an illegal facet for `` and ``. + * * @param ctxt the schema parser context * @param error the error code * @param type the schema type * @param facet the illegal facet - * - * Reports an illegal facet for `` and ``. */ static void xmlSchemaPIllegalFacetListUnionErr(xmlSchemaParserCtxtPtr ctxt, @@ -3084,14 +3073,14 @@ xmlSchemaPIllegalFacetListUnionErr(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports an illegal attribute. + * * @param ctxt the schema validation context * @param error the error code * @param ownerItem the owner as a schema object * @param attr the bad attribute node * @param name1 first mutually exclusive name * @param name2 second mutually exclusive name - * - * Reports an illegal attribute. */ static void xmlSchemaPMutualExclAttrErr(xmlSchemaParserCtxtPtr ctxt, @@ -3111,6 +3100,9 @@ xmlSchemaPMutualExclAttrErr(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports a simple type validation error. + * TODO: Should this report the value of an element as well? + * * @param ctxt the schema validation context * @param error the error code * @param ownerItem the schema object if existent @@ -3121,9 +3113,6 @@ xmlSchemaPMutualExclAttrErr(xmlSchemaParserCtxtPtr ctxt, * @param message error message * @param str1 extra data * @param str2 extra data - * - * Reports a simple type validation error. - * TODO: Should this report the value of an element as well? */ static void LIBXML_ATTR_FORMAT(8,0) xmlSchemaPSimpleTypeErr(xmlSchemaParserCtxtPtr ctxt, @@ -3207,6 +3196,8 @@ xmlSchemaPSimpleTypeErr(xmlSchemaParserCtxtPtr ctxt, } /** + * Reports an error concerning the content of a schema element. + * * @param ctxt the schema parser context * @param error the error code * @param ownerItem the owner item of the holder of the content @@ -3214,8 +3205,6 @@ xmlSchemaPSimpleTypeErr(xmlSchemaParserCtxtPtr ctxt, * @param child the invalid child node * @param message the optional error message * @param content the optional string describing the correct content - * - * Reports an error concerning the content of a schema element. */ static void xmlSchemaPContentErr(xmlSchemaParserCtxtPtr ctxt, @@ -3270,10 +3259,9 @@ xmlSchemaPContentErr(xmlSchemaParserCtxtPtr ctxt, ************************************************************************/ /** - * @param ctxt a schema validation context - * * Allocate a new Schema structure. * + * @param ctxt a schema validation context * @returns the newly allocated structure or NULL in case or error */ static xmlSchemaPtr @@ -3313,11 +3301,10 @@ xmlSchemaNewFacet(void) } /** - * @param ctxt a schema validation context - * @param node a node - * * Allocate a new annotation structure. * + * @param ctxt a schema validation context + * @param node a node * @returns the newly allocated structure or NULL in case or error */ static xmlSchemaAnnotPtr @@ -3452,9 +3439,9 @@ xmlSchemaItemListRemove(xmlSchemaItemListPtr list, int idx) } /** - * @param list a schema type structure - * * Deallocate a annotation structure + * + * @param list a schema type structure */ static void xmlSchemaItemListFree(xmlSchemaItemListPtr list) @@ -3652,9 +3639,9 @@ xmlSchemaAddItemSize(xmlSchemaItemListPtr *list, int initialSize, void *item) } /** - * @param annot a schema type structure - * * Deallocate a annotation structure + * + * @param annot a schema type structure */ static void xmlSchemaFreeAnnot(xmlSchemaAnnotPtr annot) @@ -3675,9 +3662,9 @@ xmlSchemaFreeAnnot(xmlSchemaAnnotPtr annot) } /** - * @param nota a schema notation structure - * * Deallocate a Schema Notation structure. + * + * @param nota a schema notation structure */ static void xmlSchemaFreeNotation(xmlSchemaNotationPtr nota) @@ -3690,9 +3677,9 @@ xmlSchemaFreeNotation(xmlSchemaNotationPtr nota) } /** - * @param attr an attribute declaration - * * Deallocates an attribute declaration structure. + * + * @param attr an attribute declaration */ static void xmlSchemaFreeAttribute(xmlSchemaAttributePtr attr) @@ -3707,9 +3694,9 @@ xmlSchemaFreeAttribute(xmlSchemaAttributePtr attr) } /** - * @param use an attribute use - * * Deallocates an attribute use structure. + * + * @param use an attribute use */ static void xmlSchemaFreeAttributeUse(xmlSchemaAttributeUsePtr use) @@ -3724,9 +3711,9 @@ xmlSchemaFreeAttributeUse(xmlSchemaAttributeUsePtr use) } /** - * @param prohib an attribute use prohibition - * * Deallocates an attribute use structure. + * + * @param prohib an attribute use prohibition */ static void xmlSchemaFreeAttributeUseProhib(xmlSchemaAttributeUseProhibPtr prohib) @@ -3754,9 +3741,9 @@ xmlSchemaFreeWildcardNsSet(xmlSchemaWildcardNsPtr set) } /** - * @param wildcard a wildcard structure - * * Deallocates a wildcard structure. + * + * @param wildcard a wildcard structure */ void xmlSchemaFreeWildcard(xmlSchemaWildcardPtr wildcard) @@ -3773,9 +3760,9 @@ xmlSchemaFreeWildcard(xmlSchemaWildcardPtr wildcard) } /** - * @param attrGr a schema attribute group structure - * * Deallocate a Schema Attribute Group structure. + * + * @param attrGr a schema attribute group structure */ static void xmlSchemaFreeAttributeGroup(xmlSchemaAttributeGroupPtr attrGr) @@ -3790,9 +3777,9 @@ xmlSchemaFreeAttributeGroup(xmlSchemaAttributeGroupPtr attrGr) } /** - * @param item a QName reference structure - * * Deallocatea a QName reference structure. + * + * @param item a QName reference structure */ static void xmlSchemaFreeQNameRef(xmlSchemaQNameRefPtr item) @@ -3801,9 +3788,9 @@ xmlSchemaFreeQNameRef(xmlSchemaQNameRefPtr item) } /** - * @param link a type link - * * Deallocate a list of types. + * + * @param link a type link */ static void xmlSchemaFreeTypeLinkList(xmlSchemaTypeLinkPtr link) @@ -3833,9 +3820,9 @@ xmlSchemaFreeIDCStateObjList(xmlSchemaIDCStateObjPtr sto) } /** - * @param idcDef a identity-constraint definition - * * Deallocates an identity-constraint definition. + * + * @param idcDef a identity-constraint definition */ static void xmlSchemaFreeIDC(xmlSchemaIDCPtr idcDef) @@ -3867,9 +3854,9 @@ xmlSchemaFreeIDC(xmlSchemaIDCPtr idcDef) } /** - * @param elem a schema element structure - * * Deallocate a Schema Element structure. + * + * @param elem a schema element structure */ static void xmlSchemaFreeElement(xmlSchemaElementPtr elem) @@ -3886,9 +3873,9 @@ xmlSchemaFreeElement(xmlSchemaElementPtr elem) } /** - * @param facet a schema facet structure - * * Deallocate a Schema Facet structure. + * + * @param facet a schema facet structure */ void xmlSchemaFreeFacet(xmlSchemaFacetPtr facet) @@ -3905,9 +3892,9 @@ xmlSchemaFreeFacet(xmlSchemaFacetPtr facet) } /** - * @param type a schema type structure - * * Deallocate a Schema Type structure. + * + * @param type a schema type structure */ void xmlSchemaFreeType(xmlSchemaTypePtr type) @@ -3946,9 +3933,9 @@ xmlSchemaFreeType(xmlSchemaTypePtr type) } /** - * @param item a schema model group definition - * * Deallocates a schema model group definition. + * + * @param item a schema model group definition */ static void xmlSchemaFreeModelGroupDef(xmlSchemaModelGroupDefPtr item) @@ -3959,9 +3946,9 @@ xmlSchemaFreeModelGroupDef(xmlSchemaModelGroupDefPtr item) } /** - * @param item a schema model group - * * Deallocates a schema model group structure. + * + * @param item a schema model group */ static void xmlSchemaFreeModelGroup(xmlSchemaModelGroupPtr item) @@ -4046,9 +4033,9 @@ xmlSchemaComponentListFree(xmlSchemaItemListPtr list) } /** - * @param schema a schema structure - * * Deallocate a Schema structure. + * + * @param schema a schema structure */ void xmlSchemaFree(xmlSchemaPtr schema) @@ -4105,13 +4092,13 @@ static void xmlSchemaTypeDump(xmlSchemaTypePtr type, FILE * output); /* forward */ /** + * Dump the element + * * @param payload an element * @param data the file output * @param name unused * @param namespace unused * @param context unused - * - * Dump the element */ static void xmlSchemaElementDump(void *payload, void *data, @@ -4194,10 +4181,10 @@ xmlSchemaElementDump(void *payload, void *data, } /** + * Dump the annotation + * * @param output the file output * @param annot a annotation - * - * Dump the annotation */ static void xmlSchemaAnnotDump(FILE * output, xmlSchemaAnnotPtr annot) @@ -4216,11 +4203,11 @@ xmlSchemaAnnotDump(FILE * output, xmlSchemaAnnotPtr annot) } /** + * Dump a SchemaType structure + * * @param particle the schema particle * @param output the file output * @param depth the depth used for indentation - * - * Dump a SchemaType structure */ static void xmlSchemaContentModelDump(xmlSchemaParticlePtr particle, FILE * output, int depth) @@ -4289,10 +4276,10 @@ xmlSchemaContentModelDump(xmlSchemaParticlePtr particle, FILE * output, int dept } /** + * Dumps a list of attribute use components. + * * @param uses attribute uses list * @param output the file output - * - * Dumps a list of attribute use components. */ static void xmlSchemaAttrUsesDump(xmlSchemaItemListPtr uses, FILE * output) @@ -4332,10 +4319,10 @@ xmlSchemaAttrUsesDump(xmlSchemaItemListPtr uses, FILE * output) } /** + * Dump a SchemaType structure + * * @param output the file output * @param type a type structure - * - * Dump a SchemaType structure */ static void xmlSchemaTypeDump(xmlSchemaTypePtr type, FILE * output) @@ -4439,10 +4426,10 @@ xmlSchemaTypeDumpEntry(void *type, void *output, } /** + * Dump a Schema structure. + * * @param output the file output * @param schema a schema structure - * - * Dump a Schema structure. */ void xmlSchemaDump(FILE * output, xmlSchemaPtr schema) @@ -4478,12 +4465,11 @@ xmlSchemaDump(FILE * output, xmlSchemaPtr schema) ************************************************************************/ /** - * @param node the element node - * @param name the name of the attribute - * * Seeks an attribute with a name of `name` in * no namespace. * + * @param node the element node + * @param name the name of the attribute * @returns the attribute or NULL if not present. */ static xmlAttrPtr @@ -4503,13 +4489,12 @@ xmlSchemaGetPropNode(xmlNodePtr node, const char *name) } /** - * @param node the element node - * @param uri the uri - * @param name the name of the attribute - * * Seeks an attribute with a local name of `name` and * a namespace URI of `uri`. * + * @param node the element node + * @param uri the uri + * @param name the name of the attribute * @returns the attribute or NULL if not present. */ static xmlAttrPtr @@ -4553,12 +4538,11 @@ xmlSchemaGetNodeContentNoDict(xmlNodePtr node) } /** + * Read a attribute value and internalize the string + * * @param ctxt the parser context * @param node the node * @param name the property name - * - * Read a attribute value and internalize the string - * * @returns the string or NULL if not present. */ static const xmlChar * @@ -4600,12 +4584,11 @@ xmlSchemaGetProp(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, } /** + * Lookup a global element declaration in the schema. + * * @param schema the schema context * @param name the element name * @param nsName the element namespace - * - * Lookup a global element declaration in the schema. - * * @returns the element declaration or NULL if not found. */ static xmlSchemaElementPtr @@ -4624,12 +4607,11 @@ exit: } /** + * Lookup a type in the schemas or the predefined types + * * @param schema the main schema * @param name the type's name * @param nsName the type's namespace - * - * Lookup a type in the schemas or the predefined types - * * @returns the group definition or NULL if not found. */ static xmlSchemaTypePtr @@ -4661,12 +4643,11 @@ exit: } /** + * Lookup a an attribute in the schema or imported schemas + * * @param schema the context of the schema * @param name the name of the attribute * @param nsName the target namespace of the attribute - * - * Lookup a an attribute in the schema or imported schemas - * * @returns the attribute declaration or NULL if not found. */ static xmlSchemaAttributePtr @@ -4685,12 +4666,11 @@ exit: } /** + * Lookup a an attribute group in the schema or imported schemas + * * @param schema the context of the schema * @param name the name of the attribute group * @param nsName the target namespace of the attribute group - * - * Lookup a an attribute group in the schema or imported schemas - * * @returns the attribute group definition or NULL if not found. */ static xmlSchemaAttributeGroupPtr @@ -4715,12 +4695,11 @@ exit: } /** + * Lookup a group in the schema or imported schemas + * * @param schema the context of the schema * @param name the name of the group * @param nsName the target namespace of the group - * - * Lookup a group in the schema or imported schemas - * * @returns the group definition or NULL if not found. */ static xmlSchemaModelGroupDefPtr @@ -4772,13 +4751,12 @@ exit: } /** + * Lookup a group in the schema or imported schemas + * * @param schema the schema * @param itemType the item type * @param name the name of the group * @param targetNs the target namespace of the group - * - * Lookup a group in the schema or imported schemas - * * @returns the group definition or NULL if not found. */ static xmlSchemaBasicItemPtr @@ -4810,11 +4788,10 @@ xmlSchemaGetNamedComponent(xmlSchemaPtr schema, (((n)->type == XML_TEXT_NODE) && (xmlSchemaIsBlank((n)->content, -1))) /** - * @param str a string - * @param len the length of the string or -1 - * * Check if a string is ignorable * + * @param str a string + * @param len the length of the string or -1 * @returns 1 if the string is NULL or made of blanks chars, 0 otherwise */ static int @@ -4926,15 +4903,14 @@ subschemas: } /** + * Add an XML schema annotation declaration + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema parser context * @param schema the schema being built * @param name the item name * @param nsName the element namespace * @param node unused - * - * Add an XML schema annotation declaration - * *WARNING* this interface is highly subject to change - * * @returns the new structure or NULL in case of error */ static xmlSchemaNotationPtr @@ -4963,16 +4939,15 @@ xmlSchemaAddNotation(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** + * Add an XML schema Attribute declaration + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema parser context * @param schema the schema being built * @param name the item name * @param nsName the item namespace * @param node the context node * @param topLevel whether this is a top-level element - * - * Add an XML schema Attribute declaration - * *WARNING* this interface is highly subject to change - * * @returns the new structure or NULL in case of error */ static xmlSchemaAttributePtr @@ -5005,12 +4980,11 @@ xmlSchemaAddAttribute(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** - * @param pctxt a schema parser context - * @param node the context node - * * Add an XML schema Attribute declaration * *WARNING* this interface is highly subject to change * + * @param pctxt a schema parser context + * @param node the context node * @returns the new structure or NULL in case of error */ static xmlSchemaAttributeUsePtr @@ -5071,14 +5045,13 @@ xmlSchemaAddRedef(xmlSchemaParserCtxtPtr pctxt, } /** + * Add an XML schema Attribute Group definition. + * * @param pctxt a schema parser context * @param schema the schema being built * @param name the item name * @param nsName the target namespace * @param node the corresponding node - * - * Add an XML schema Attribute Group definition. - * * @returns the new structure or NULL in case of error */ static xmlSchemaAttributeGroupPtr @@ -5122,15 +5095,14 @@ xmlSchemaAddAttributeGroupDefinition(xmlSchemaParserCtxtPtr pctxt, } /** + * Add an XML schema Element declaration + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema parser context * @param name the type name * @param nsName the type namespace * @param node the context node * @param topLevel whether this is a top-level element - * - * Add an XML schema Element declaration - * *WARNING* this interface is highly subject to change - * * @returns the new structure or NULL in case of error */ static xmlSchemaElementPtr @@ -5163,6 +5135,9 @@ xmlSchemaAddElement(xmlSchemaParserCtxtPtr ctxt, } /** + * Add an XML schema item + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema parser context * @param schema the schema being built * @param type the type @@ -5170,10 +5145,6 @@ xmlSchemaAddElement(xmlSchemaParserCtxtPtr ctxt, * @param nsName the namespace * @param node the context node * @param topLevel whether this is a top-level element - * - * Add an XML schema item - * *WARNING* this interface is highly subject to change - * * @returns the new structure or NULL in case of error */ static xmlSchemaTypePtr @@ -5260,14 +5231,13 @@ xmlSchemaAddAttributeUseProhib(xmlSchemaParserCtxtPtr pctxt) /** + * Adds a schema model group + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema parser context * @param schema the schema being built * @param type the "compositor" type of the model group * @param node the node in the schema doc - * - * Adds a schema model group - * *WARNING* this interface is highly subject to change - * * @returns the new structure or NULL in case of error */ static xmlSchemaModelGroupPtr @@ -5299,14 +5269,13 @@ xmlSchemaAddModelGroup(xmlSchemaParserCtxtPtr ctxt, /** + * Adds an XML schema particle component. + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema parser context * @param node the corresponding node in the schema doc * @param min the minOccurs * @param max the maxOccurs - * - * Adds an XML schema particle component. - * *WARNING* this interface is highly subject to change - * * @returns the new structure or NULL in case of error */ static xmlSchemaParticlePtr @@ -5342,14 +5311,13 @@ xmlSchemaAddParticle(xmlSchemaParserCtxtPtr ctxt, } /** + * Add an XML schema Group definition + * * @param ctxt a schema validation context * @param schema the schema being built * @param name the group name * @param nsName the group namespace * @param node the context node - * - * Add an XML schema Group definition - * * @returns the new structure or NULL in case of error */ static xmlSchemaModelGroupDefPtr @@ -5391,10 +5359,9 @@ xmlSchemaAddModelGroupDefinition(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt a schema validation context - * * Creates a new wildcard namespace constraint. * + * @param ctxt a schema validation context * @returns the new structure or NULL in case of error */ static xmlSchemaWildcardNsPtr @@ -5445,14 +5412,13 @@ xmlSchemaAddIDC(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** + * Adds a wildcard. + * It corresponds to a xsd:anyAttribute and xsd:any. + * * @param ctxt a schema validation context * @param schema a schema * @param type the type * @param node the context node - * - * Adds a wildcard. - * It corresponds to a xsd:anyAttribute and xsd:any. - * * @returns the new structure or NULL in case of error */ static xmlSchemaWildcardPtr @@ -5541,12 +5507,11 @@ xmlSchemaSubstGroupGet(xmlSchemaParserCtxtPtr pctxt, } /** + * Allocate a new annotation structure. + * * @param pctxt a schema parser context * @param head the head of the substitution group * @param member the new member of the substitution group - * - * Allocate a new annotation structure. - * * @returns the newly allocated structure or NULL in case or error */ static int @@ -5576,6 +5541,10 @@ xmlSchemaAddElementSubstitutionMember(xmlSchemaParserCtxtPtr pctxt, ************************************************************************/ /** + * Extracts the local name and the URI of a QName value and validates it. + * This one is intended to be used on attribute values that + * should resolve to schema components. + * * @param ctxt a schema parser context * @param schema the schema context * @param attr the attribute node @@ -5583,11 +5552,6 @@ xmlSchemaAddElementSubstitutionMember(xmlSchemaParserCtxtPtr pctxt, * @param value the QName value * @param uri the resulting namespace URI if found * @param local the resulting local part if found, the attribute value otherwise - * - * Extracts the local name and the URI of a QName value and validates it. - * This one is intended to be used on attribute values that - * should resolve to schema components. - * * @returns 0, in case the QName is valid, a positive error code * if not valid and -1 if an internal error occurs. */ @@ -5656,17 +5620,16 @@ xmlSchemaPValAttrNodeQNameValue(xmlSchemaParserCtxtPtr ctxt, } /** + * Extracts and validates the QName of an attribute value. + * This one is intended to be used on attribute values that + * should resolve to schema components. + * * @param ctxt a schema parser context * @param schema the schema context * @param ownerItem the owner as a schema object * @param attr the attribute node * @param uri the resulting namespace URI if found * @param local the resulting local part if found, the attribute value otherwise - * - * Extracts and validates the QName of an attribute value. - * This one is intended to be used on attribute values that - * should resolve to schema components. - * * @returns 0, in case the QName is valid, a positive error code * if not valid and -1 if an internal error occurs. */ @@ -5686,6 +5649,8 @@ xmlSchemaPValAttrNodeQName(xmlSchemaParserCtxtPtr ctxt, } /** + * Extracts and validates the QName of an attribute value. + * * @param ctxt a schema parser context * @param schema the schema context * @param ownerItem the owner as a schema object @@ -5693,9 +5658,6 @@ xmlSchemaPValAttrNodeQName(xmlSchemaParserCtxtPtr ctxt, * @param name the name of the attribute * @param uri the resulting namespace URI if found * @param local the resulting local part if found, the attribute value otherwise - * - * Extracts and validates the QName of an attribute value. - * * @returns 0, in case the QName is valid, a positive error code * if not valid and -1 if an internal error occurs. */ @@ -5721,11 +5683,10 @@ xmlSchemaPValAttrQName(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt a schema parser context - * @param attr attribute node - * * Extracts and validates the ID of an attribute value. * + * @param ctxt a schema parser context + * @param attr attribute node * @returns 0, in case the ID is valid, a positive error code * if not valid and -1 if an internal error occurs. */ @@ -5800,15 +5761,14 @@ xmlSchemaPValAttrID(xmlSchemaParserCtxtPtr ctxt, } /** + * Get the maxOccurs property + * * @param ctxt a schema validation context * @param node a subtree containing XML Schema information * @param min minimum * @param max maximum * @param def default * @param expected expected - * - * Get the maxOccurs property - * * @returns the default if not found, or the value */ static int @@ -5879,15 +5839,14 @@ xmlGetMaxOccurs(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, } /** + * Get the minOccurs property + * * @param ctxt a schema validation context * @param node a subtree containing XML Schema information * @param min minimum * @param max maximum * @param def default * @param expected expected - * - * Get the minOccurs property - * * @returns the default if not found, or the value */ static int @@ -5945,12 +5904,11 @@ xmlGetMinOccurs(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, } /** + * Converts a boolean string value into 1 or 0. + * * @param ctxt a schema validation context * @param ownerItem the owner as a schema item * @param node the node holding the value - * - * Converts a boolean string value into 1 or 0. - * * @returns 0 or 1. */ static int @@ -5989,13 +5947,12 @@ xmlSchemaPGetBoolNodeValue(xmlSchemaParserCtxtPtr ctxt, } /** + * Evaluate if a boolean property is set + * * @param ctxt a schema validation context * @param node a subtree containing XML Schema information * @param name the attribute name * @param def the default value - * - * Evaluate if a boolean property is set - * * @returns the default if not found, 0 if found to be false, * 1 if found to be true */ @@ -6066,16 +6023,15 @@ xmlSchemaParseAnyAttribute(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, xmlNodePtr node); /** + * Validates a value against the given built-in type. + * This one is intended to be used internally for validation + * of schema attribute values during parsing of the schema. + * * @param pctxt a schema parser context * @param ownerItem the schema object owner if existent * @param attr the schema attribute node being validated * @param value the value * @param type the built-in type to be validated against - * - * Validates a value against the given built-in type. - * This one is intended to be used internally for validation - * of schema attribute values during parsing of the schema. - * * @returns 0 if the value is valid, a positive error code * number otherwise and -1 in case of an internal or API error. */ @@ -6136,16 +6092,15 @@ xmlSchemaPValAttrNodeValue(xmlSchemaParserCtxtPtr pctxt, } /** + * Extracts and validates a value against the given built-in type. + * This one is intended to be used internally for validation + * of schema attribute values during parsing of the schema. + * * @param ctxt a schema parser context * @param ownerItem the schema object owner if existent * @param attr the schema attribute node being validated * @param type the built-in type to be validated against * @param value the resulting value if any - * - * Extracts and validates a value against the given built-in type. - * This one is intended to be used internally for validation - * of schema attribute values during parsing of the schema. - * * @returns 0 if the value is valid, a positive error code * number otherwise and -1 in case of an internal or API error. */ @@ -6170,17 +6125,16 @@ xmlSchemaPValAttrNode(xmlSchemaParserCtxtPtr ctxt, } /** + * Extracts and validates a value against the given built-in type. + * This one is intended to be used internally for validation + * of schema attribute values during parsing of the schema. + * * @param ctxt a schema parser context * @param ownerItem the schema object owner if existent * @param ownerElem the owner element node * @param name the name of the schema attribute node * @param type the built-in type to be validated against * @param value the resulting value if any - * - * Extracts and validates a value against the given built-in type. - * This one is intended to be used internally for validation - * of schema attribute values during parsing of the schema. - * * @returns 0 if the value is valid, a positive error code * number otherwise and -1 in case of an internal or API error. */ @@ -6268,15 +6222,15 @@ xmlSchemaCheckReference(xmlSchemaParserCtxtPtr pctxt, } /** + * Parses attribute uses and attribute declarations and + * attribute group references. + * * @param ctxt a schema validation context * @param schema the schema being built * @param child a subtree containing XML Schema information * @param list an item list * @param parentType the hosting type where the attributes will be anchored * @param hasRefs set if references were found - * - * Parses attribute uses and attribute declarations and - * attribute group references. */ static int xmlSchemaParseLocalAttributes(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, @@ -6311,13 +6265,12 @@ xmlSchemaParseLocalAttributes(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** - * @param ctxt a schema validation context - * @param node a subtree containing XML Schema information - * @param needed needed - * * parse a XML schema Attribute declaration * *WARNING* this interface is highly subject to change * + * @param ctxt a schema validation context + * @param node a subtree containing XML Schema information + * @param needed needed * @returns -1 in case of error, 0 if the declaration is improper and * 1 in case of success. */ @@ -6430,13 +6383,12 @@ xmlSchemaParseAnnotation(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr node, int neede } /** - * @param ctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * * parse a XML schema Facet declaration * *WARNING* this interface is highly subject to change * + * @param ctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information * @returns the new type structure or NULL in case of error */ static xmlSchemaFacetPtr @@ -6520,15 +6472,14 @@ xmlSchemaParseFacet(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** - * @param ctxt a schema parser context - * @param schema unused - * @param wildc the wildcard, already created - * @param node a subtree containing XML Schema information - * * Parses the attribute "processContents" and "namespace" * of a xsd:anyAttribute and xsd:any. * *WARNING* this interface is highly subject to change * + * @param ctxt a schema parser context + * @param schema unused + * @param wildc the wildcard, already created + * @param node a subtree containing XML Schema information * @returns 0 if everything goes fine, a positive error code * if something is not valid and -1 if an internal error occurs. */ @@ -6689,15 +6640,14 @@ xmlSchemaPCheckParticleCorrect_2(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * * Parsea a XML schema `` element. A particle and wildcard * will be created (except if minOccurs==maxOccurs==0, in this case * nothing will be created). * *WARNING* this interface is highly subject to change * + * @param ctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information * @returns the particle or NULL in case of error or if minOccurs==maxOccurs==0 */ static xmlSchemaParticlePtr @@ -6783,12 +6733,11 @@ xmlSchemaParseAny(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** + * parse a XML schema Notation declaration + * * @param ctxt a schema validation context * @param schema the schema being built * @param node a subtree containing XML Schema information - * - * parse a XML schema Notation declaration - * * @returns the new structure or NULL in case of error */ static xmlSchemaNotationPtr @@ -6829,13 +6778,12 @@ xmlSchemaParseNotation(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** - * @param ctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * * parse a XML schema AnyAttribute declaration * *WARNING* this interface is highly subject to change * + * @param ctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information * @returns a wildcard or NULL. */ static xmlSchemaWildcardPtr @@ -6898,15 +6846,14 @@ xmlSchemaParseAnyAttribute(xmlSchemaParserCtxtPtr ctxt, /** + * parse a XML schema Attribute declaration + * *WARNING* this interface is highly subject to change + * * @param pctxt a schema validation context * @param schema the schema being built * @param node a subtree containing XML Schema information * @param uses attribute uses list * @param parentType parent type - * - * parse a XML schema Attribute declaration - * *WARNING* this interface is highly subject to change - * * @returns the attribute declaration. */ static xmlSchemaBasicItemPtr @@ -7442,15 +7389,14 @@ xmlSchemaParseGlobalAttribute(xmlSchemaParserCtxtPtr pctxt, } /** - * @param pctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * * Parse an attribute group definition reference. * Note that a reference to an attribute group does not * correspond to any component at all. * *WARNING* this interface is highly subject to change * + * @param pctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information * @returns the attribute group or NULL in case of error. */ static xmlSchemaQNameRefPtr @@ -7574,13 +7520,12 @@ xmlSchemaParseAttributeGroupRef(xmlSchemaParserCtxtPtr pctxt, } /** - * @param pctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * * parse a XML schema Attribute Group declaration * *WARNING* this interface is highly subject to change * + * @param pctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information * @returns the attribute group definition or NULL in case of error. */ static xmlSchemaAttributeGroupPtr @@ -7676,7 +7621,6 @@ xmlSchemaParseAttributeGroupDefinition(xmlSchemaParserCtxtPtr pctxt, * @param value the value * @param flags the flags to be modified * @param flagQualified the specific flag for "qualified" - * * @returns 0 if the value is valid, 1 otherwise. */ static int @@ -7694,6 +7638,9 @@ xmlSchemaPValAttrFormDefault(const xmlChar *value, } /** + * Validates the value of the attribute "final" and "block". The value + * is converted into the specified flag values and returned in `flags`. + * * @param value the value * @param flags the flags to be modified * @param flagAll the specific flag for "\#all" @@ -7702,10 +7649,6 @@ xmlSchemaPValAttrFormDefault(const xmlChar *value, * @param flagSubstitution the specific flag for "substitution" * @param flagList the specific flag for "list" * @param flagUnion the specific flag for "union" - * - * Validates the value of the attribute "final" and "block". The value - * is converted into the specified flag values and returned in `flags`. - * * @returns 0 if the value is valid, 1 otherwise. */ @@ -7907,11 +7850,10 @@ xmlSchemaCheckCSelectorXPath(xmlSchemaParserCtxtPtr ctxt, cur->next = annot; /** - * @param annItem the schema component - * @param annot the annotation - * * Adds the annotation to the given schema component. * + * @param annItem the schema component + * @param annot the annotation * @returns the given annotation. */ static xmlSchemaAnnotPtr @@ -8002,14 +7944,13 @@ xmlSchemaAddAnnotation(xmlSchemaAnnotItemPtr annItem, } /** + * Parses a XML Schema identity-constraint definition's + * `` and `` elements. + * * @param ctxt a schema validation context * @param idc the identity-constraint definition * @param node a subtree containing XML Schema information * @param isField field indicator - * - * Parses a XML Schema identity-constraint definition's - * `` and `` elements. - * * @returns the parsed identity-constraint definition. */ static xmlSchemaIDCSelectPtr @@ -8098,14 +8039,13 @@ xmlSchemaParseIDCSelectorAndField(xmlSchemaParserCtxtPtr ctxt, } /** + * Parses a XML Schema identity-constraint definition. + * * @param ctxt a schema validation context * @param schema the schema being built * @param node a subtree containing XML Schema information * @param idcCategory the IDC category * @param targetNamespace the target namespace - * - * Parses a XML Schema identity-constraint definition. - * * @returns the parsed identity-constraint definition. */ static xmlSchemaIDCPtr @@ -8246,15 +8186,14 @@ xmlSchemaParseIDC(xmlSchemaParserCtxtPtr ctxt, } /** + * Parses a XML schema element declaration. + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema validation context * @param schema the schema being built * @param node a subtree containing XML Schema information * @param isElemRef set if the element is a reference * @param topLevel indicates if this is global declaration - * - * Parses a XML schema element declaration. - * *WARNING* this interface is highly subject to change - * * @returns the element declaration or a particle; NULL in case * of an error or if the particle has minOccurs==maxOccurs==0. */ @@ -8645,13 +8584,12 @@ return_null: } /** - * @param ctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * * parse a XML schema Union definition * *WARNING* this interface is highly subject to change * + * @param ctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information * @returns -1 in case of internal error, 0 in case of success and a positive * error code otherwise. */ @@ -8822,13 +8760,12 @@ xmlSchemaParseUnion(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** - * @param ctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * * parse a XML schema List definition * *WARNING* this interface is highly subject to change * + * @param ctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information * @returns -1 in case of error, 0 if the declaration is improper and * 1 in case of success. */ @@ -8932,14 +8869,13 @@ xmlSchemaParseList(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** + * parse a XML schema Simple Type definition + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema validation context * @param schema the schema being built * @param node a subtree containing XML Schema information * @param topLevel whether this is a top-level element - * - * parse a XML schema Simple Type definition - * *WARNING* this interface is highly subject to change - * * @returns -1 in case of error, 0 if the declaration is improper and * 1 in case of success. */ @@ -9147,14 +9083,13 @@ xmlSchemaParseSimpleType(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** - * @param ctxt the parser context - * @param schema the schema being built - * @param node the node - * * Parses a reference to a model group definition. * * We will return a particle component with a qname-component or * NULL in case of an error. + * @param ctxt the parser context + * @param schema the schema being built + * @param node the node */ static xmlSchemaTreeItemPtr xmlSchemaParseModelGroupDefRef(xmlSchemaParserCtxtPtr ctxt, @@ -9242,10 +9177,6 @@ xmlSchemaParseModelGroupDefRef(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * * Parses a XML schema model group definition. * * Note that the constraint src-redefine (6.2) can't be applied until @@ -9254,6 +9185,9 @@ xmlSchemaParseModelGroupDefRef(xmlSchemaParserCtxtPtr ctxt, * * *WARNING* this interface is highly subject to change * + * @param ctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information * @returns -1 in case of error, 0 if the declaration is improper and * 1 in case of success. */ @@ -9337,10 +9271,10 @@ xmlSchemaParseModelGroupDefinition(xmlSchemaParserCtxtPtr ctxt, } /** + * removes unwanted nodes in a schemas document tree + * * @param ctxt a schema validation context * @param root the root of the document. - * - * removes unwanted nodes in a schemas document tree */ static void xmlSchemaCleanupDoc(xmlSchemaParserCtxtPtr ctxt, xmlNodePtr root) @@ -9549,7 +9483,6 @@ exit_failure: * @param ctxt a schema validation context * @param schema the schemas * @param nodes the list of top level nodes - * * @returns the internal XML Schema structure built from the resource or * NULL in case of error */ @@ -9764,12 +9697,11 @@ xmlSchemaParserCtxtCreate(void) } /** - * @param URL the location of the schema - * @param dict the dictionary to be used - * * Create an XML Schemas parse context for that file/resource expected * to contain an XML Schemas file. * + * @param URL the location of the schema + * @param dict the dictionary to be used * @returns the parser context or NULL in case of error */ static xmlSchemaParserCtxtPtr @@ -9813,9 +9745,7 @@ xmlSchemaCreatePCtxtOnVCtxt(xmlSchemaValidCtxtPtr vctxt) /** * @param pctxt the schema parser context * @param schemaLocation the URI of the schema document - * * @returns a schema bucket if it was already parsed. - * * @returns a schema bucket if it was already parsed from * `schemaLocation`, NULL otherwise. */ @@ -10071,6 +10001,8 @@ xmlSchemaBuildAbsoluteURI(xmlDictPtr dict, const xmlChar* location, /** + * Parse an included (and to-be-redefined) XML schema document. + * * @param pctxt a schema validation context * @param type import or include or redefine * @param schemaLocation schema location @@ -10081,9 +10013,6 @@ xmlSchemaBuildAbsoluteURI(xmlDictPtr dict, const xmlChar* location, * @param sourceTargetNamespace source target namespace * @param importNamespace import namespace * @param bucket bucket - * - * Parse an included (and to-be-redefined) XML schema document. - * * @returns 0 on success, a positive error code on errors and * -1 in case of an internal or API error. */ @@ -10507,13 +10436,12 @@ exit_failure: } /** - * @param pctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * * parse a XML schema Import definition * *WARNING* this interface is highly subject to change * + * @param pctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information * @returns 0 in case of success, a positive error code if * not valid and -1 in case of an internal error. */ @@ -10987,12 +10915,6 @@ xmlSchemaParseInclude(xmlSchemaParserCtxtPtr pctxt, xmlSchemaPtr schema, } /** - * @param ctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * @param type the "compositor" type - * @param withParticle if a a model group with a particle - * * parse a XML schema Sequence definition. * Applies parts of: * Schema Representation Constraint: @@ -11007,6 +10929,11 @@ xmlSchemaParseInclude(xmlSchemaParserCtxtPtr pctxt, xmlSchemaPtr schema, * * *WARNING* this interface is highly subject to change * + * @param ctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information + * @param type the "compositor" type + * @param withParticle if a a model group with a particle * @returns -1 in case of error, 0 if the declaration is improper and * 1 in case of success. */ @@ -11266,14 +11193,13 @@ xmlSchemaParseModelGroup(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** + * parse a XML schema Restriction definition + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema validation context * @param schema the schema being built * @param node a subtree containing XML Schema information * @param parentType the parent type - * - * parse a XML schema Restriction definition - * *WARNING* this interface is highly subject to change - * * @returns the type definition or NULL in case of error */ static xmlSchemaTypePtr @@ -11569,15 +11495,14 @@ xmlSchemaParseRestriction(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** - * @param ctxt a schema validation context - * @param schema the schema being built - * @param node a subtree containing XML Schema information - * @param parentType parent type - * * Parses an ``, which is found inside a * `` or ``. * *WARNING* this interface is highly subject to change. * + * @param ctxt a schema validation context + * @param schema the schema being built + * @param node a subtree containing XML Schema information + * @param parentType parent type * @returns the type definition or NULL in case of error */ static xmlSchemaTypePtr @@ -11705,14 +11630,13 @@ xmlSchemaParseExtension(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, } /** + * parse a XML schema SimpleContent definition + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema validation context * @param schema the schema being built * @param node a subtree containing XML Schema information * @param hasRestrictionOrExtension set if restriction or extension was found - * - * parse a XML schema SimpleContent definition - * *WARNING* this interface is highly subject to change - * * @returns the type definition or NULL in case of error */ static int @@ -11795,14 +11719,13 @@ xmlSchemaParseSimpleContent(xmlSchemaParserCtxtPtr ctxt, } /** + * parse a XML schema ComplexContent definition + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema validation context * @param schema the schema being built * @param node a subtree containing XML Schema information * @param hasRestrictionOrExtension set if restriction or extension was found - * - * parse a XML schema ComplexContent definition - * *WARNING* this interface is highly subject to change - * * @returns the type definition or NULL in case of error */ static int @@ -11890,14 +11813,13 @@ xmlSchemaParseComplexContent(xmlSchemaParserCtxtPtr ctxt, } /** + * parse a XML schema Complex Type definition + * *WARNING* this interface is highly subject to change + * * @param ctxt a schema validation context * @param schema the schema being built * @param node a subtree containing XML Schema information * @param topLevel whether this is a top-level element - * - * parse a XML schema Complex Type definition - * *WARNING* this interface is highly subject to change - * * @returns the type definition or NULL in case of error */ static xmlSchemaTypePtr @@ -12188,11 +12110,10 @@ xmlSchemaParseComplexType(xmlSchemaParserCtxtPtr ctxt, xmlSchemaPtr schema, #if 0 /* Will be enabled if it is clear what options are needed. */ /** - * @param ctxt a schema parser context - * @param options a combination of xmlSchemaParserOption - * * Sets the options to be used during the parse. * + * @param ctxt a schema parser context + * @param options a combination of xmlSchemaParserOption * @returns 0 in case of success, -1 in case of an * API error. */ @@ -12220,7 +12141,6 @@ xmlSchemaParserCtxtSetOptions(xmlSchemaParserCtxtPtr ctxt, /** * @param ctxt a schema parser context - * * @returns the option combination of the parser context. */ static int @@ -12235,11 +12155,10 @@ xmlSchemaParserCtxtGetOptions(xmlSchemaParserCtxtPtr ctxt) #endif /** - * @param URL the location of the schema - * * Create an XML Schemas parse context for that file/resource expected * to contain an XML Schemas file. * + * @param URL the location of the schema * @returns the parser context or NULL in case of error */ xmlSchemaParserCtxtPtr @@ -12259,12 +12178,11 @@ xmlSchemaNewParserCtxt(const char *URL) } /** - * @param buffer a pointer to a char array containing the schemas - * @param size the size of the array - * * Create an XML Schemas parse context for that memory buffer expected * to contain an XML Schemas file. * + * @param buffer a pointer to a char array containing the schemas + * @param size the size of the array * @returns the parser context or NULL in case of error */ xmlSchemaParserCtxtPtr @@ -12284,11 +12202,10 @@ xmlSchemaNewMemParserCtxt(const char *buffer, int size) } /** - * @param doc a preparsed document tree - * * Create an XML Schemas parse context for that document. * NB. The document may be modified during the parsing process. * + * @param doc a preparsed document tree * @returns the parser context or NULL in case of error */ xmlSchemaParserCtxtPtr @@ -12310,9 +12227,9 @@ xmlSchemaNewDocParserCtxt(xmlDocPtr doc) } /** - * @param ctxt the schema parser context - * * Free the resources associated to the schema parser context + * + * @param ctxt the schema parser context */ void xmlSchemaFreeParserCtxt(xmlSchemaParserCtxtPtr ctxt) @@ -12515,11 +12432,10 @@ xmlSchemaBuildContentModelForElement(xmlSchemaParserCtxtPtr ctxt, } /** - * @param pctxt the schema parser context - * @param particle the particle component - * * Create the automaton for the {content type} of a complex type. * + * @param pctxt the schema parser context + * @param particle the particle component * @returns 1 if the content is nillable, 0 otherwise */ static int @@ -12922,10 +12838,10 @@ xmlSchemaBuildAContentModel(xmlSchemaParserCtxtPtr pctxt, } /** + * Builds the content model of the complex type. + * * @param type the complex type definition * @param ctxt the schema parser context - * - * Builds the content model of the complex type. */ static void xmlSchemaBuildContentModel(xmlSchemaTypePtr type, @@ -12969,12 +12885,12 @@ xmlSchemaBuildContentModel(xmlSchemaTypePtr type, } /** - * @param elemDecl the schema element context - * @param ctxt the schema parser context - * * Resolves the references of an element declaration * or particle, which has an element declaration as it's * term. + * + * @param elemDecl the schema element context + * @param ctxt the schema parser context */ static void xmlSchemaResolveElementReferences(xmlSchemaElementPtr elemDecl, @@ -13057,13 +12973,12 @@ xmlSchemaResolveElementReferences(xmlSchemaElementPtr elemDecl, } /** - * @param ctxt the schema parser context - * @param type the schema simple type definition - * * Checks and builds the "member type definitions" property of the union * simple type. This handles part (1), part (2) is done in * xmlSchemaFinishMemberTypeDefinitionsProperty() * + * @param ctxt the schema parser context + * @param type the schema simple type definition * @returns -1 in case of an internal error, 0 otherwise. */ static int @@ -13136,10 +13051,9 @@ xmlSchemaResolveUnionMemberTypes(xmlSchemaParserCtxtPtr ctxt, } /** + * * @param type the type definition * @param valType the value type - * - * * @returns 1 if the type has the given value type, or * is derived from such a type. */ @@ -13163,11 +13077,10 @@ xmlSchemaIsDerivedFromBuiltInType(xmlSchemaTypePtr type, int valType) #if 0 /** + * * @param ctxt the schema parser context * @param type the type definition * @param valType the value type - * - * * @returns 1 if the type has the given value type, or * is derived from such a type. */ @@ -13203,7 +13116,6 @@ xmlSchemaQueryBuiltInType(xmlSchemaTypePtr type) /** * @param type the simpleType definition - * * @returns the primitive type of the given type or * NULL in case of error. */ @@ -13228,7 +13140,6 @@ xmlSchemaGetPrimitiveType(xmlSchemaTypePtr type) #if 0 /** * @param type the simpleType definition - * * @returns the primitive type of the given type or * NULL in case of error. */ @@ -13248,12 +13159,12 @@ xmlSchemaGetBuiltInTypeAncestor(xmlSchemaTypePtr type) #endif /** + * Clones the namespace constraints of source + * and assigns them to dest. + * * @param ctxt the schema parser context * @param dest the destination wildcard * @param source the source wildcard - * - * Clones the namespace constraints of source - * and assigns them to dest. * @returns -1 on internal error, 0 otherwise. */ static int @@ -13293,12 +13204,12 @@ xmlSchemaCloneWildcardNsConstraints(xmlSchemaParserCtxtPtr ctxt, } /** + * Unions the namespace constraints of the given wildcards. + * `completeWild` will hold the resulting union. + * * @param ctxt the schema parser context * @param completeWild the first wildcard * @param curWild the second wildcard - * - * Unions the namespace constraints of the given wildcards. - * `completeWild` will hold the resulting union. * @returns a positive error code on failure, -1 in case of an * internal error, 0 otherwise. */ @@ -13552,12 +13463,12 @@ xmlSchemaUnionWildcards(xmlSchemaParserCtxtPtr ctxt, } /** + * Intersects the namespace constraints of the given wildcards. + * `completeWild` will hold the resulting intersection. + * * @param ctxt the schema parser context * @param completeWild the first wildcard * @param curWild the second wildcard - * - * Intersects the namespace constraints of the given wildcards. - * `completeWild` will hold the resulting intersection. * @returns a positive error code on failure, -1 in case of an * internal error, 0 otherwise. */ @@ -13729,11 +13640,10 @@ xmlSchemaIntersectWildcards(xmlSchemaParserCtxtPtr ctxt, } /** - * @param sub the first wildcard - * @param super the second wildcard - * * Schema Component Constraint: Wildcard Subset (cos-ns-subset) * + * @param sub the first wildcard + * @param super the second wildcard * @returns 0 if the namespace constraint of `sub` is an intensional * subset of `super`, 1 otherwise. */ @@ -13830,12 +13740,11 @@ xmlSchemaGetEffectiveValueConstraint(xmlSchemaAttributeUsePtr attruse, return(0); } /** - * @param wild the wildcard - * @param ns the namespace - * * Validation Rule: Wildcard allows Namespace Name * (cvc-wildcard-namespace) * + * @param wild the wildcard + * @param ns the namespace * @returns 0 if the given namespace matches the wildcard, * 1 otherwise and -1 on API errors. */ @@ -14171,17 +14080,16 @@ xmlSchemaExpandAttributeGroupRefs(xmlSchemaParserCtxtPtr pctxt, xmlSchemaItemListPtr list, xmlSchemaItemListPtr prohibs); /** - * @param pctxt the schema parser context - * @param type the complex type definition - * - * * Builds the wildcard and the attribute uses on the given complex type. - * @returns -1 if an internal error occurs, 0 otherwise. + * * * ATTENTION TODO: Experimentally this uses pointer comparisons for * strings, so recheck this if we start to hardcode some schemata, since * they might not be in the same dict. * NOTE: It is allowed to "extend" the xs:anyType type. + * @param pctxt the schema parser context + * @param type the complex type definition + * @returns -1 if an internal error occurs, 0 otherwise. */ static int xmlSchemaFixupTypeAttributeUses(xmlSchemaParserCtxtPtr pctxt, @@ -14372,12 +14280,11 @@ exit_failure: } /** - * @param type the type definition - * @param final the final - * * Evaluates if a type definition contains the given "final". * This does take "finalDefault" into account as well. * + * @param type the type definition + * @param final the final * @returns 1 if the type does contain the given "final", * 0 otherwise. */ @@ -14394,7 +14301,6 @@ xmlSchemaTypeFinalContains(xmlSchemaTypePtr type, int final) /** * @param type the Union Simple Type - * * @returns a list of member types of `type` if existing, * @returns NULL otherwise. */ @@ -14412,11 +14318,10 @@ xmlSchemaGetUnionSimpleTypeMemberTypes(xmlSchemaTypePtr type) #if 0 /** - * @param particle the particle - * * Schema Component Constraint: Effective Total Range * (all and sequence) + (choice) * + * @param particle the particle * @returns the minimum Effective Total Range. */ static int @@ -14466,11 +14371,10 @@ xmlSchemaGetParticleTotalRangeMin(xmlSchemaParticlePtr particle) } /** - * @param particle the particle - * * Schema Component Constraint: Effective Total Range * (all and sequence) + (choice) * + * @param particle the particle * @returns the maximum Effective Total Range. */ static int @@ -14527,7 +14431,6 @@ xmlSchemaGetParticleTotalRangeMax(xmlSchemaParticlePtr particle) /** * @param particle the particle - * * @returns 1 if emptiable, 0 otherwise. */ static int @@ -14567,11 +14470,10 @@ xmlSchemaGetParticleEmptiable(xmlSchemaParticlePtr particle) } /** - * @param particle the particle - * * Schema Component Constraint: Particle Emptiable * Checks whether the given particle is emptiable. * + * @param particle the particle * @returns 1 if emptiable, 0 otherwise. */ static int @@ -14593,17 +14495,16 @@ xmlSchemaIsParticleEmptiable(xmlSchemaParticlePtr particle) } /** - * @param actxt a context - * @param type the derived simple type definition - * @param baseType the base type definition - * @param subset the subset of ('restriction', etc.) - * * Schema Component Constraint: * Type Derivation OK (Simple) (cos-st-derived-OK) * * Checks whether `type` can be validly * derived from `baseType`. * + * @param actxt a context + * @param type the derived simple type definition + * @param baseType the base type definition + * @param subset the subset of ('restriction', etc.) * @returns 0 on success, an positive error code otherwise. */ static int @@ -14695,13 +14596,12 @@ xmlSchemaCheckCOSSTDerivedOK(xmlSchemaAbstractCtxtPtr actxt, } /** - * @param pctxt the schema parser context - * @param ctxtType the type definition - * @param ancestor an ancestor of `ctxtType` - * * Checks st-props-correct (2) + ct-props-correct (3). * Circular type definitions are not allowed. * + * @param pctxt the schema parser context + * @param ctxtType the type definition + * @param ancestor an ancestor of `ctxtType` * @returns XML_SCHEMAP_ST_PROPS_CORRECT_2 if the given type is * circular, 0 otherwise. */ @@ -14736,10 +14636,10 @@ xmlSchemaCheckTypeDefCircularInternal(xmlSchemaParserCtxtPtr pctxt, } /** + * Checks for circular type definitions. + * * @param item the complex/simple type definition * @param ctxt the parser context - * - * Checks for circular type definitions. */ static void xmlSchemaCheckTypeDefCircular(xmlSchemaTypePtr item, @@ -14816,10 +14716,10 @@ xmlSchemaCheckUnionTypeDefCircular(xmlSchemaParserCtxtPtr pctxt, } /** + * Resolves type definition references + * * @param typeDef the complex/simple type definition * @param ctxt the parser context - * - * Resolves type definition references */ static void xmlSchemaResolveTypeReferences(xmlSchemaTypePtr typeDef, @@ -14940,11 +14840,10 @@ xmlSchemaResolveTypeReferences(xmlSchemaTypePtr typeDef, /** - * @param ctxt the schema parser context - * @param type the simple type definition - * * Checks st-props-correct. * + * @param ctxt the schema parser context + * @param type the simple type definition * @returns 0 if the properties are correct, * if not, a positive error code and -1 on internal * errors. @@ -15041,15 +14940,14 @@ xmlSchemaCheckSTPropsCorrect(xmlSchemaParserCtxtPtr ctxt, } /** - * @param pctxt the schema parser context - * @param type the simple type definition - * * Schema Component Constraint: * Derivation Valid (Restriction, Simple) (cos-st-restricts) * Checks if the given `type` (simpleType) is derived validly by restriction. * STATUS: * + * @param pctxt the schema parser context + * @param type the simple type definition * @returns -1 on internal errors, 0 if the type is validly derived, * a positive error code otherwise. */ @@ -15509,11 +15407,10 @@ xmlSchemaCheckCOSSTRestricts(xmlSchemaParserCtxtPtr pctxt, #if 0 /** - * @param ctxt the schema parser context - * @param type the simple type definition - * * Checks crc-simple-type constraints. * + * @param ctxt the schema parser context + * @param type the simple type definition * @returns 0 if the constraints are satisfied, * if not a positive error code and -1 on internal * errors. @@ -15586,17 +15483,16 @@ xmlSchemaVCheckCVCSimpleType(xmlSchemaAbstractCtxtPtr actxt, int isNormalized); /** - * @param pctxt the schema parser context - * @param node an optional node (the holder of the value) - * @param type the simple type definition - * @param value the default value - * @param val resulting value - * * Schema Component Constraint: Element Default Valid (Immediate) * (cos-valid-default) * This will be used by the parser only. For the validator there's * an other version. * + * @param pctxt the schema parser context + * @param node an optional node (the holder of the value) + * @param type the simple type definition + * @param value the default value + * @param val resulting value * @returns 0 if the constraints are satisfied, * if not, a positive error code and -1 on internal * errors. @@ -15667,14 +15563,13 @@ xmlSchemaParseCheckCOSValidDefault(xmlSchemaParserCtxtPtr pctxt, } /** - * @param pctxt the schema parser context - * @param type the complex type definition - * - *.(4.6) Constraints on Complex Type Definition Schema Components + * (4.6) Constraints on Complex Type Definition Schema Components * Schema Component Constraint: * Complex Type Definition Properties Correct (ct-props-correct) * STATUS: (seems) complete * + * @param pctxt the schema parser context + * @param type the complex type definition * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -15811,16 +15706,15 @@ xmlSchemaAreEqualTypes(xmlSchemaTypePtr typeA, } /** - * @param actxt the schema parser context - * @param type the to-be derived complex type definition - * @param baseType the base complex type definition - * @param set the given set - * * Schema Component Constraint: * Type Derivation OK (Complex) (cos-ct-derived-ok) * * STATUS: completed * + * @param actxt the schema parser context + * @param type the to-be derived complex type definition + * @param baseType the base complex type definition + * @param set the given set * @returns 0 if the constraints are satisfied, or 1 * if not. */ @@ -15884,16 +15778,15 @@ xmlSchemaCheckCOSCTDerivedOK(xmlSchemaAbstractCtxtPtr actxt, } /** - * @param actxt the schema parser context - * @param type the derived simple type definition - * @param baseType the base type definition - * @param set the given set - * * Calls: * Type Derivation OK (Simple) AND Type Derivation OK (Complex) * * Checks whether `type` can be validly derived from `baseType`. * + * @param actxt the schema parser context + * @param type the derived simple type definition + * @param baseType the base type definition + * @param set the given set * @returns 0 on success, an positive error code otherwise. */ static int @@ -15909,9 +15802,6 @@ xmlSchemaCheckCOSDerivedOK(xmlSchemaAbstractCtxtPtr actxt, } /** - * @param ctxt the schema parser context - * @param type the complex type definition - * * (3.4.6) Constraints on Complex Type Definition Schema Components * Schema Component Constraint: * Derivation Valid (Extension) (cos-ct-extends) @@ -15921,6 +15811,8 @@ xmlSchemaCheckCOSDerivedOK(xmlSchemaAbstractCtxtPtr actxt, * (1.5) * (1.4.3.2.2.2) "Particle Valid (Extension)" * + * @param ctxt the schema parser context + * @param type the complex type definition * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16162,9 +16054,6 @@ xmlSchemaCheckCOSCTExtends(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt the schema parser context - * @param type the complex type definition - * * (3.4.6) Constraints on Complex Type Definition Schema Components * Schema Component Constraint: * Derivation Valid (Restriction, Complex) (derivation-ok-restriction) @@ -16177,6 +16066,8 @@ xmlSchemaCheckCOSCTExtends(xmlSchemaParserCtxtPtr ctxt, * In XML Schema 1.1 this will be: * Validation Rule: Checking complex type subsumption * + * @param ctxt the schema parser context + * @param type the complex type definition * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16361,11 +16252,10 @@ xmlSchemaCheckDerivationOKRestriction(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt the schema parser context - * @param type the complex type definition - * * (3.4.6) Constraints on Complex Type Definition Schema Components * + * @param ctxt the schema parser context + * @param type the complex type definition * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16388,13 +16278,12 @@ xmlSchemaCheckCTComponent(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt the schema parser context - * @param type the complex type definition - * * (3.4.3) Constraints on XML Representations of Complex Type Definitions: * Schema Representation Constraint: * Complex Type Definition Representation OK (src-ct) * + * @param ctxt the schema parser context + * @param type the complex type definition * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16554,15 +16443,14 @@ xmlSchemaCheckSRCCT(xmlSchemaParserCtxtPtr ctxt, #ifdef ENABLE_PARTICLE_RESTRICTION /** - * @param ctxt the schema parser context - * @param type the complex type definition - * * (3.9.6) Constraints on Particle Schema Components * Schema Component Constraint: * Occurrence Range OK (range-ok) * * STATUS: complete * + * @param ctxt the schema parser context + * @param type the complex type definition * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16579,10 +16467,6 @@ xmlSchemaCheckParticleRangeOK(int rmin, int rmax, } /** - * @param ctxt the schema parser context - * @param r the restricting element declaration particle - * @param b the base element declaration particle - * * (3.9.6) Constraints on Particle Schema Components * Schema Component Constraint: * Particle Restriction OK (Elt:Elt -- NameAndTypeOK) @@ -16592,6 +16476,9 @@ xmlSchemaCheckParticleRangeOK(int rmin, int rmax, * MISSING (3.2.3) * CLARIFY: (3.2.2) * + * @param ctxt the schema parser context + * @param r the restricting element declaration particle + * @param b the base element declaration particle * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16685,10 +16572,6 @@ xmlSchemaCheckRCaseNameAndTypeOK(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt the schema parser context - * @param r the restricting element declaration particle - * @param b the base wildcard particle - * * (3.9.6) Constraints on Particle Schema Components * Schema Component Constraint: * Particle Derivation OK (Elt:Any -- NSCompat) @@ -16696,6 +16579,9 @@ xmlSchemaCheckRCaseNameAndTypeOK(xmlSchemaParserCtxtPtr ctxt, * * STATUS: complete * + * @param ctxt the schema parser context + * @param r the restricting element declaration particle + * @param b the base wildcard particle * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16728,10 +16614,6 @@ xmlSchemaCheckRCaseNSCompat(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt the schema parser context - * @param r the restricting element declaration particle - * @param b the base model group particle - * * (3.9.6) Constraints on Particle Schema Components * Schema Component Constraint: * Particle Derivation OK (Elt:All/Choice/Sequence -- RecurseAsIfGroup) @@ -16739,6 +16621,9 @@ xmlSchemaCheckRCaseNSCompat(xmlSchemaParserCtxtPtr ctxt, * * STATUS: TODO * + * @param ctxt the schema parser context + * @param r the restricting element declaration particle + * @param b the base model group particle * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16753,10 +16638,6 @@ xmlSchemaCheckRCaseRecurseAsIfGroup(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt the schema parser context - * @param r the restricting wildcard particle - * @param b the base wildcard particle - * * (3.9.6) Constraints on Particle Schema Components * Schema Component Constraint: * Particle Derivation OK (Any:Any -- NSSubset) @@ -16764,6 +16645,9 @@ xmlSchemaCheckRCaseRecurseAsIfGroup(xmlSchemaParserCtxtPtr ctxt, * * STATUS: complete * + * @param ctxt the schema parser context + * @param r the restricting wildcard particle + * @param b the base wildcard particle * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16804,15 +16688,14 @@ xmlSchemaCheckRCaseNSSubset(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt the schema parser context - * @param type the complex type definition - * * (3.9.6) Constraints on Particle Schema Components * Schema Component Constraint: * Particle Valid (Restriction) (cos-particle-restrict) * * STATUS: TODO * + * @param ctxt the schema parser context + * @param type the complex type definition * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16841,10 +16724,6 @@ xmlSchemaCheckCOSParticleRestrict(xmlSchemaParserCtxtPtr ctxt, #if 0 /** - * @param ctxt the schema parser context - * @param r the model group particle - * @param b the base wildcard particle - * * (3.9.6) Constraints on Particle Schema Components * Schema Component Constraint: * Particle Derivation OK (All/Choice/Sequence:Any -- @@ -16853,6 +16732,9 @@ xmlSchemaCheckCOSParticleRestrict(xmlSchemaParserCtxtPtr ctxt, * * STATUS: TODO: subst-groups * + * @param ctxt the schema parser context + * @param r the model group particle + * @param b the base wildcard particle * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -16894,10 +16776,6 @@ xmlSchemaCheckRCaseNSRecurseCheckCardinality(xmlSchemaParserCtxtPtr ctxt, #endif /** - * @param ctxt the schema parser context - * @param r the or model group particle - * @param b the base or model group particle - * * (3.9.6) Constraints on Particle Schema Components * Schema Component Constraint: * Particle Derivation OK (All:All,Sequence:Sequence -- @@ -16907,6 +16785,9 @@ xmlSchemaCheckRCaseNSRecurseCheckCardinality(xmlSchemaParserCtxtPtr ctxt, * STATUS: ? * TODO: subst-groups * + * @param ctxt the schema parser context + * @param r the or model group particle + * @param b the base or model group particle * @returns 0 if the constraints are satisfied, a positive * error code if not and -1 if an internal error occurred. */ @@ -18304,11 +18185,11 @@ exit_failure: /** - * @param type the schema type definition - * @param actxt the schema parser context - * * Fixes the content model of the type. * URGENT TODO: We need an int result! + * + * @param type the schema type definition + * @param actxt the schema parser context */ static int xmlSchemaTypeFixup(xmlSchemaTypePtr type, @@ -18331,13 +18212,12 @@ xmlSchemaTypeFixup(xmlSchemaTypePtr type, } /** + * Checks and computes the values of facets. + * * @param facet the facet * @param typeDecl the schema type definition * @param pctxt the schema parser context or NULL * @param name the optional name of the type - * - * Checks and computes the values of facets. - * * @returns 0 if valid, a positive error code if not valid and * -1 in case of an internal or API error. */ @@ -18543,10 +18423,10 @@ internal_error: } /** + * Checks the default values types, especially for facets + * * @param typeDecl the schema type definition * @param pctxt the schema parser context - * - * Checks the default values types, especially for facets */ static int xmlSchemaCheckFacetValues(xmlSchemaTypePtr typeDecl, @@ -18585,12 +18465,11 @@ exit_failure: } /** - * @param groupDef the searched model group - * @param particle the first particle - * * This one is intended to be used by * xmlSchemaCheckGroupDefCircular only. * + * @param groupDef the searched model group + * @param particle the first particle * @returns the particle with the circular model group definition reference, * otherwise NULL. */ @@ -18641,10 +18520,10 @@ xmlSchemaGetCircModelGrDefRef(xmlSchemaModelGroupDefPtr groupDef, } /** + * Checks for circular references to model group definitions. + * * @param item the model group definition * @param ctxt the parser context - * - * Checks for circular references to model group definitions. */ static void xmlSchemaCheckGroupDefCircular(xmlSchemaModelGroupDefPtr item, @@ -18690,9 +18569,6 @@ xmlSchemaCheckGroupDefCircular(xmlSchemaModelGroupDefPtr item, } /** - * @param ctxt the parser context - * @param mg the model group - * * Assigns the model group of model group definitions to the "term" * of the referencing particle. * In xmlSchemaResolveModelGroupParticleReferences the model group @@ -18701,6 +18577,8 @@ xmlSchemaCheckGroupDefCircular(xmlSchemaModelGroupDefPtr item, * * Schema Component Constraint: * All Group Limited (cos-all-limited) (1.2) + * @param ctxt the parser context + * @param mg the model group */ static void xmlSchemaModelGroupToModelGroupDefFixup( @@ -18736,12 +18614,11 @@ xmlSchemaModelGroupToModelGroupDefFixup( } /** - * @param ctxtGr the searched attribute group - * @param list the current attribute list to be processed - * * This one is intended to be used by * xmlSchemaCheckAttrGroupCircular only. * + * @param ctxtGr the searched attribute group + * @param list the current attribute list to be processed * @returns the circular attribute group reference, otherwise NULL. */ static xmlSchemaQNameRefPtr @@ -18787,10 +18664,10 @@ xmlSchemaCheckAttrGroupCircularRecur(xmlSchemaAttributeGroupPtr ctxtGr, } /** + * Checks for circular references of attribute groups. + * * @param attrGr the attribute group definition * @param ctxt the parser context - * - * Checks for circular references of attribute groups. */ static int xmlSchemaCheckAttrGroupCircular(xmlSchemaAttributeGroupPtr attrGr, @@ -18847,18 +18724,18 @@ xmlSchemaAttributeGroupExpandRefs(xmlSchemaParserCtxtPtr pctxt, xmlSchemaAttributeGroupPtr attrGr); /** - * @param pctxt the parser context - * @param item the schema item - * @param completeWild the intersected wildcard to be returned - * @param list the attribute uses - * @param prohibs the attribute prohibitions - * * Substitutes contained attribute group references * for their attribute uses. Wildcards are intersected. * Attribute use prohibitions are removed from the list * and returned via the `prohibs` list. * Pointlessness of attr. prohibs, if a matching attr. decl * is existent a well, are checked. + * + * @param pctxt the parser context + * @param item the schema item + * @param completeWild the intersected wildcard to be returned + * @param list the attribute uses + * @param prohibs the attribute prohibitions */ static int xmlSchemaExpandAttributeGroupRefs(xmlSchemaParserCtxtPtr pctxt, @@ -19019,15 +18896,14 @@ xmlSchemaExpandAttributeGroupRefs(xmlSchemaParserCtxtPtr pctxt, } /** - * @param pctxt the parser context - * @param attrGr the attribute group definition - * * Computation of: * {attribute uses} property * {attribute wildcard} property * * Substitutes contained attribute group references * for their attribute uses. Wildcards are intersected. + * @param pctxt the parser context + * @param attrGr the attribute group definition */ static int xmlSchemaAttributeGroupExpandRefs(xmlSchemaParserCtxtPtr pctxt, @@ -19045,14 +18921,13 @@ xmlSchemaAttributeGroupExpandRefs(xmlSchemaParserCtxtPtr pctxt, } /** - * @param pctxt the parser context - * @param attrGr the attribute group definition - * * Substitutes contained attribute group references * for their attribute uses. Wildcards are intersected. * * Schema Component Constraint: * Attribute Group Definition Properties Correct (ag-props-correct) + * @param pctxt the parser context + * @param attrGr the attribute group definition */ static int xmlSchemaCheckAGPropsCorrect(xmlSchemaParserCtxtPtr pctxt, @@ -19144,10 +19019,10 @@ next_use: {} } /** + * Resolves references to attribute group definitions. + * * @param ref the schema attribute definition * @param ctxt the schema parser context - * - * Resolves references to attribute group definitions. */ static int xmlSchemaResolveAttrGroupReferences(xmlSchemaQNameRefPtr ref, @@ -19173,15 +19048,14 @@ xmlSchemaResolveAttrGroupReferences(xmlSchemaQNameRefPtr ref, } /** - * @param pctxt a schema parser context - * @param attr an schema attribute declaration/use - * * Schema Component Constraint: * Attribute Declaration Properties Correct (a-props-correct) * * Validates the value constraints of an attribute declaration/use. * NOTE that this needs the simple type definitions to be already * built and checked. + * @param pctxt a schema parser context + * @param attr an schema attribute declaration/use */ static int xmlSchemaCheckAttrPropsCorrect(xmlSchemaParserCtxtPtr pctxt, @@ -19270,14 +19144,13 @@ xmlSchemaCheckSubstGroupCircular(xmlSchemaElementPtr elemDecl, } /** - * @param pctxt a schema parser context - * @param elemDecl the element declaration - * * Schema Component Constraint: * Element Declaration Properties Correct (e-props-correct) * * STATUS: * missing: (6) + * @param pctxt a schema parser context + * @param elemDecl the element declaration */ static int xmlSchemaCheckElemPropsCorrect(xmlSchemaParserCtxtPtr pctxt, @@ -19443,9 +19316,6 @@ xmlSchemaCheckElemPropsCorrect(xmlSchemaParserCtxtPtr pctxt, } /** - * @param ctxt a schema parser context - * @param elemDecl the element declaration - * * Schema Component Constraint: * Substitution Group (cos-equiv-class) * @@ -19458,6 +19328,8 @@ xmlSchemaCheckElemPropsCorrect(xmlSchemaParserCtxtPtr pctxt, * * STATUS: * + * @param ctxt a schema parser context + * @param elemDecl the element declaration */ static void xmlSchemaCheckElemSubstGroup(xmlSchemaParserCtxtPtr ctxt, @@ -19562,14 +19434,14 @@ add_member: #ifdef WXS_ELEM_DECL_CONS_ENABLED /* enable when finished */ /** * xmlSchemaCheckElementDeclComponent + * + * Schema Component Constraint: Element Declarations Consistent * @param pctxt the schema parser context * @param ctxtComponent the context component (an element declaration) * @param ctxtParticle the first particle of the context component * @param searchParticle the element declaration particle to be analysed * @param curParticle the current particle * @param search search flag - * - * Schema Component Constraint: Element Declarations Consistent */ static int xmlSchemaCheckElementDeclConsistent(xmlSchemaParserCtxtPtr pctxt, @@ -19680,11 +19552,11 @@ exit: /** * xmlSchemaCheckElementDeclComponent - * @param elemDecl an schema element declaration/particle - * @param ctxt a schema parser context * * Validates the value constraints of an element declaration. * Adds substitution group members. + * @param elemDecl an schema element declaration/particle + * @param ctxt a schema parser context */ static void xmlSchemaCheckElementDeclComponent(xmlSchemaElementPtr elemDecl, @@ -19704,11 +19576,11 @@ xmlSchemaCheckElementDeclComponent(xmlSchemaElementPtr elemDecl, } /** - * @param ctxt a parser context - * @param mg a model group - * * Resolves references of a model group's {particles} to * model group definitions and to element declarations. + * + * @param ctxt a parser context + * @param mg a model group */ static void xmlSchemaResolveModelGroupParticleReferences( @@ -19852,10 +19724,10 @@ xmlSchemaAreValuesEqual(xmlSchemaValPtr x, } /** + * Resolves the referenced attribute declaration. + * * @param ause an attribute use * @param ctxt a parser context - * - * Resolves the referenced attribute declaration. */ static int xmlSchemaResolveAttrUseReferences(xmlSchemaAttributeUsePtr ause, @@ -19889,12 +19761,11 @@ xmlSchemaResolveAttrUseReferences(xmlSchemaAttributeUsePtr ause, } /** - * @param ctxt a parser context - * @param use an attribute use - * * Schema Component Constraint: * Attribute Use Correct (au-props-correct) * + * @param ctxt a parser context + * @param use an attribute use */ static int xmlSchemaCheckAttrUsePropsCorrect(xmlSchemaParserCtxtPtr ctxt, @@ -19999,10 +19870,10 @@ xmlSchemaCheckAttrUsePropsCorrect(xmlSchemaParserCtxtPtr ctxt, /** + * Resolves the referenced type definition component. + * * @param item an attribute declaration * @param ctxt a parser context - * - * Resolves the referenced type definition component. */ static int xmlSchemaResolveAttrTypeReferences(xmlSchemaAttributePtr item, @@ -20044,12 +19915,12 @@ xmlSchemaResolveAttrTypeReferences(xmlSchemaAttributePtr item, } /** - * @param idc the identity-constraint definition - * @param pctxt the schema parser context - * * Resolve keyRef references to key/unique IDCs. * Schema Component Constraint: * Identity-constraint Definition Properties Correct (c-props-correct) + * + * @param idc the identity-constraint definition + * @param pctxt the schema parser context */ static int xmlSchemaResolveIDCKeyReferences(xmlSchemaIDCPtr idc, @@ -20972,11 +20843,10 @@ exit: return(ret); } /** - * @param ctxt a schema validation context - * * parse a schema definition resource and build an internal * XML Schema structure which can be used to validate instances. * + * @param ctxt a schema validation context * @returns the internal XML Schema structure built from the resource or * NULL in case of error */ @@ -21096,14 +20966,14 @@ exit_failure: } /** + * Set the callback functions used to handle errors for a validation context + * + * @deprecated Use xmlSchemaSetParserStructuredErrors. + * * @param ctxt a schema validation context * @param err the error callback * @param warn the warning callback * @param ctx contextual data for the callbacks - * - * @deprecated Use xmlSchemaSetParserStructuredErrors. - * - * Set the callback functions used to handle errors for a validation context */ void xmlSchemaSetParserErrors(xmlSchemaParserCtxtPtr ctxt, @@ -21120,11 +20990,11 @@ xmlSchemaSetParserErrors(xmlSchemaParserCtxtPtr ctxt, } /** + * Set the structured error callback + * * @param ctxt a schema parser context * @param serror the structured error function * @param ctx the functions context - * - * Set the structured error callback */ void xmlSchemaSetParserStructuredErrors(xmlSchemaParserCtxtPtr ctxt, @@ -21140,13 +21010,12 @@ xmlSchemaSetParserStructuredErrors(xmlSchemaParserCtxtPtr ctxt, } /** + * Get the callback information used to handle errors for a parser context + * * @param ctxt a XMl-Schema parser context * @param err the error callback result * @param warn the warning callback result * @param ctx contextual data for the callbacks result - * - * Get the callback information used to handle errors for a parser context - * * @returns -1 in case of failure, 0 otherwise */ int @@ -21166,14 +21035,13 @@ xmlSchemaGetParserErrors(xmlSchemaParserCtxtPtr ctxt, } /** - * @param ctxt schema parser - * @param loader resource loader - * @param data user data which will be passed to the loader - * * Register a callback function that will be called to load documents * or external entities. * * @since 2.14.0 + * @param ctxt schema parser + * @param loader resource loader + * @param data user data which will be passed to the loader */ void xmlSchemaSetResourceLoader(xmlSchemaParserCtxtPtr ctxt, @@ -21185,10 +21053,9 @@ xmlSchemaSetResourceLoader(xmlSchemaParserCtxtPtr ctxt, } /** - * @param type the facet type - * * Convert the xmlSchemaTypeType to a char string. * + * @param type the facet type * @returns the char string representation of the facet type if the * type is a facet and an "Internal Error" string otherwise. */ @@ -21283,14 +21150,13 @@ xmlSchemaGetWhiteSpaceFacetValue(xmlSchemaTypePtr type) ************************************************************************/ /** + * Expands an existing schema by an additional schema. + * * @param vctxt a schema validation context * @param schema the existing schema * @param node the node that fired the assembling * @param nsName the namespace name of the new schema * @param location the location of the schema - * - * Expands an existing schema by an additional schema. - * * @returns 0 if the new schema is correct, a positive error code * number otherwise and -1 in case of an internal or API error. */ @@ -21421,13 +21287,12 @@ xmlSchemaGetMetaAttrInfo(xmlSchemaValidCtxtPtr vctxt, } /** - * @param vctxt a schema validation context - * * Expands an existing schema by an additional schema using * the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute * of an instance. If xsi:noNamespaceSchemaLocation is used, `noNamespace` * must be set to 1. * + * @param vctxt a schema validation context * @returns 0 if the new schema is correct, a positive error code * number otherwise and -1 in case of an internal or API error. */ @@ -21682,12 +21547,11 @@ xmlSchemaVAddNodeQName(xmlSchemaValidCtxtPtr vctxt, ************************************************************************/ /** + * Creates an augmented IDC definition item. + * * @param payload the IDC definition * @param data validation context * @param name unused - * - * Creates an augmented IDC definition item. - * * @returns the item, or NULL on internal errors. */ static void @@ -21721,11 +21585,11 @@ xmlSchemaAugmentIDC(void *payload, void *data, } /** + * Creates an augmented IDC definition for the imported schema. + * * @param payload the imported schema * @param data validation context * @param name unused - * - * Creates an augmented IDC definition for the imported schema. */ static void xmlSchemaAugmentImportedIDC(void *payload, void *data, @@ -21738,10 +21602,9 @@ xmlSchemaAugmentImportedIDC(void *payload, void *data, } /** - * @param idcDef the IDC definition of this binding - * * Creates a new IDC binding. * + * @param idcDef the IDC definition of this binding * @returns the new IDC binding, NULL on internal errors. */ static xmlSchemaPSVIIDCBindingPtr @@ -21761,13 +21624,12 @@ xmlSchemaIDCNewBinding(xmlSchemaIDCPtr idcDef) } /** - * @param vctxt the WXS validation context - * @param item the IDC node table item - * * The validation context is used to store IDC node table items. * They are stored to avoid copying them if IDC node-tables are merged * with corresponding parent IDC node-tables (bubbling). * + * @param vctxt the WXS validation context + * @param item the IDC node table item * @returns 0 if succeeded, -1 on internal errors. */ static int @@ -21802,11 +21664,10 @@ xmlSchemaIDCStoreNodeTableItem(xmlSchemaValidCtxtPtr vctxt, } /** - * @param vctxt the WXS validation context - * @param key the IDC key - * * The validation context is used to store an IDC key. * + * @param vctxt the WXS validation context + * @param key the IDC key * @returns 0 if succeeded, -1 on internal errors. */ static int @@ -21841,11 +21702,10 @@ xmlSchemaIDCStoreKey(xmlSchemaValidCtxtPtr vctxt, } /** - * @param bind the IDC binding - * @param ntItem the node-table item - * * Appends the IDC node-table item to the binding. * + * @param bind the IDC binding + * @param ntItem the node-table item * @returns 0 on success and -1 on internal errors. */ static int @@ -21877,13 +21737,12 @@ xmlSchemaIDCAppendNodeTableItem(xmlSchemaPSVIIDCBindingPtr bind, } /** - * @param vctxt the WXS validation context - * @param matcher the IDC matcher - * * Looks up an PSVI IDC binding, for the IDC definition and * of the given matcher. If none found, a new one is created * and added to the IDC table. * + * @param vctxt the WXS validation context + * @param matcher the IDC matcher * @returns an IDC binding or NULL on internal errors. */ static xmlSchemaPSVIIDCBindingPtr @@ -21931,9 +21790,9 @@ xmlSchemaIDCAcquireTargetList(xmlSchemaValidCtxtPtr vctxt, } /** - * @param key the IDC key - * * Frees an IDC key together with its compiled value. + * + * @param key the IDC key */ static void xmlSchemaIDCFreeKey(xmlSchemaPSVIIDCKeyPtr key) @@ -21958,9 +21817,9 @@ xmlSchemaIDCFreeBinding(xmlSchemaPSVIIDCBindingPtr bind) } /** - * @param bind the first IDC binding in the list - * * Frees an IDC table, i.e. all the IDC bindings in the list. + * + * @param bind the first IDC binding in the list */ static void xmlSchemaIDCFreeIDCTable(xmlSchemaPSVIIDCBindingPtr bind) @@ -21986,9 +21845,9 @@ xmlFreeIDCHashEntry (void *payload, const xmlChar *name ATTRIBUTE_UNUSED) } /** - * @param matcher the first IDC matcher in the list - * * Frees a list of IDC matchers. + * + * @param matcher the first IDC matcher in the list */ static void xmlSchemaIDCFreeMatcherList(xmlSchemaIDCMatcherPtr matcher) @@ -22030,10 +21889,10 @@ xmlSchemaIDCFreeMatcherList(xmlSchemaIDCMatcherPtr matcher) } /** + * Caches a list of IDC matchers for reuse. + * * @param vctxt the WXS validation context * @param matcher the first IDC matcher in the list - * - * Caches a list of IDC matchers for reuse. */ static void xmlSchemaIDCReleaseMatcherList(xmlSchemaValidCtxtPtr vctxt, @@ -22090,15 +21949,14 @@ xmlSchemaIDCReleaseMatcherList(xmlSchemaValidCtxtPtr vctxt, } /** - * @param vctxt the WXS validation context - * @param matcher the IDC matcher - * @param sel the XPath information - * @param type "selector" or "field" - * * Creates/reuses and activates state objects for the given * XPath information; if the XPath expression consists of unions, * multiple state objects are created for every unioned expression. * + * @param vctxt the WXS validation context + * @param matcher the IDC matcher + * @param sel the XPath information + * @param type "selector" or "field" * @returns 0 on success and -1 on internal errors. */ static int @@ -22160,11 +22018,10 @@ xmlSchemaIDCAddStateObject(xmlSchemaValidCtxtPtr vctxt, } /** - * @param vctxt the WXS validation context - * @param nodeType the nodeType of the current node - * * Evaluates all active XPath state objects. * + * @param vctxt the WXS validation context + * @param nodeType the nodeType of the current node * @returns the number of IC "field" state objects which resolved to * this node, 0 if none resolved and -1 on internal errors. */ @@ -22327,10 +22184,9 @@ xmlSchemaHashKeySequence(xmlSchemaValidCtxtPtr vctxt, } /** - * @param vctxt the WXS validation context - * * Pops all XPath states. * + * @param vctxt the WXS validation context * @returns 0 on success and -1 on internal errors. */ static int @@ -22352,12 +22208,11 @@ xmlSchemaXPathPop(xmlSchemaValidCtxtPtr vctxt) } /** - * @param vctxt the WXS validation context - * @param depth depth - * * Processes and pops the history items of the IDC state objects. * IDC key-sequences are validated/created on IDC bindings. * + * @param vctxt the WXS validation context + * @param depth depth * @returns 0 on success and -1 on internal errors. */ static int @@ -22862,12 +22717,11 @@ deregister_check: } /** - * @param vctxt the WXS validation context - * @param elemDecl the element declaration - * * Creates helper objects to evaluate IDC selectors/fields * successively. * + * @param vctxt the WXS validation context + * @param elemDecl the element declaration * @returns 0 if OK and -1 on internal errors. */ static int @@ -23172,13 +23026,12 @@ internal_error: } /** - * @param vctxt the WXS validation context - * * Merges IDC bindings of an element at `depth` into the corresponding IDC * bindings of its parent element. If a duplicate note-table entry is found, * both, the parent node-table entry and child entry are discarded from the * node-table of the parent. * + * @param vctxt the WXS validation context * @returns 0 if OK and -1 on internal errors. */ static int @@ -23471,9 +23324,9 @@ internal_error: } /** - * @param vctxt the WXS validation context - * * Check the cvc-idc-keyref constraints. + * + * @param vctxt the WXS validation context */ static int xmlSchemaCheckCVCIDCKeyRef(xmlSchemaValidCtxtPtr vctxt) @@ -23811,11 +23664,10 @@ xmlSchemaClearElemInfo(xmlSchemaValidCtxtPtr vctxt, } /** - * @param vctxt the schema validation context - * * Creates/reuses and initializes the element info item for * the current tree depth. * + * @param vctxt the schema validation context * @returns the element info item or NULL on API or internal errors. */ static xmlSchemaNodeInfoPtr @@ -27161,10 +27013,9 @@ internal_error: ************************************************************************/ /** - * @param schema a precompiled XML Schemas - * * Create an XML Schemas validation context based on the given schema. * + * @param schema a precompiled XML Schemas * @returns the validation context or NULL in case of error */ xmlSchemaValidCtxtPtr @@ -27194,11 +27045,11 @@ xmlSchemaNewValidCtxt(xmlSchemaPtr schema) } /** - * @param vctxt the schema validation context - * @param filename the file name - * * Workaround to provide file error reporting information when this is * not provided by current APIs + * + * @param vctxt the schema validation context + * @param filename the file name */ void xmlSchemaValidateSetFilename(xmlSchemaValidCtxtPtr vctxt, const char *filename) { @@ -27213,10 +27064,10 @@ xmlSchemaValidateSetFilename(xmlSchemaValidCtxtPtr vctxt, const char *filename) } /** - * @param vctxt the schema validation context - * * Free the resources associated to the schema validation context; * leaves some fields alive intended for reuse of the context. + * + * @param vctxt the schema validation context */ static void xmlSchemaClearValidCtxt(xmlSchemaValidCtxtPtr vctxt) @@ -27337,9 +27188,9 @@ xmlSchemaClearValidCtxt(xmlSchemaValidCtxtPtr vctxt) } /** - * @param ctxt the schema validation context - * * Free the resources associated to the schema validation context + * + * @param ctxt the schema validation context */ void xmlSchemaFreeValidCtxt(xmlSchemaValidCtxtPtr ctxt) @@ -27424,10 +27275,9 @@ xmlSchemaFreeValidCtxt(xmlSchemaValidCtxtPtr ctxt) } /** - * @param ctxt the schema validation context - * * Check if any error was detected during validation. * + * @param ctxt the schema validation context * @returns 1 if valid so far, 0 if errors were detected, and -1 in case * of internal error. */ @@ -27440,14 +27290,14 @@ xmlSchemaIsValid(xmlSchemaValidCtxtPtr ctxt) } /** + * Set the error and warning callback information + * + * @deprecated Use xmlSchemaSetValidStructuredErrors. + * * @param ctxt a schema validation context * @param err the error function * @param warn the warning function * @param ctx the functions context - * - * @deprecated Use xmlSchemaSetValidStructuredErrors. - * - * Set the error and warning callback information */ void xmlSchemaSetValidErrors(xmlSchemaValidCtxtPtr ctxt, @@ -27464,11 +27314,11 @@ xmlSchemaSetValidErrors(xmlSchemaValidCtxtPtr ctxt, } /** + * Set the structured error callback + * * @param ctxt a schema validation context * @param serror the structured error function * @param ctx the functions context - * - * Set the structured error callback */ void xmlSchemaSetValidStructuredErrors(xmlSchemaValidCtxtPtr ctxt, @@ -27485,13 +27335,12 @@ xmlSchemaSetValidStructuredErrors(xmlSchemaValidCtxtPtr ctxt, } /** + * Get the error and warning callback information + * * @param ctxt a XML-Schema validation context * @param err the error function result * @param warn the warning function result * @param ctx the functions context result - * - * Get the error and warning callback information - * * @returns -1 in case of error and 0 otherwise */ int @@ -27512,11 +27361,10 @@ xmlSchemaGetValidErrors(xmlSchemaValidCtxtPtr ctxt, /** - * @param ctxt a schema validation context - * @param options a combination of xmlSchemaValidOption - * * Sets the options to be used during the validation. * + * @param ctxt a schema validation context + * @param options a combination of xmlSchemaValidOption * @returns 0 in case of success, -1 in case of an * API error. */ @@ -27544,10 +27392,9 @@ xmlSchemaSetValidOptions(xmlSchemaValidCtxtPtr ctxt, } /** - * @param ctxt a schema validation context - * * Get the validation context options. * + * @param ctxt a schema validation context * @returns the option combination or -1 on error. */ int @@ -27844,11 +27691,10 @@ xmlSchemaVStart(xmlSchemaValidCtxtPtr vctxt) } /** - * @param ctxt a schema validation context - * @param elem an element node - * * Validate a branch of a tree, starting with the given `elem`. * + * @param ctxt a schema validation context + * @param elem an element node * @returns 0 if the element and its subtree is valid, a positive error * code number otherwise and -1 in case of an internal or API error. */ @@ -27868,11 +27714,10 @@ xmlSchemaValidateOneElement(xmlSchemaValidCtxtPtr ctxt, xmlNodePtr elem) } /** - * @param ctxt a schema validation context - * @param doc a parsed document tree - * * Validate a document tree in memory. * + * @param ctxt a schema validation context + * @param doc a parsed document tree * @returns 0 if the document is schemas valid, a positive error code * number otherwise and -1 in case of internal or API error. */ @@ -28237,14 +28082,13 @@ endElementNsSplit(void *ctx, const xmlChar * localname, } /** - * @param ctxt a schema validation context - * @param sax a pointer to the original xmlSAXHandlerPtr - * @param user_data a pointer to the original SAX user data pointer - * * Plug a SAX based validation layer in a SAX parsing event flow. * The original `saxptr` and `dataptr` data are replaced by new pointers * but the calls to the original will be maintained. * + * @param ctxt a schema validation context + * @param sax a pointer to the original xmlSAXHandlerPtr + * @param user_data a pointer to the original SAX user data pointer * @returns a pointer to a data structure needed to unplug the validation layer * or NULL in case of errors. */ @@ -28382,11 +28226,10 @@ xmlSchemaSAXPlug(xmlSchemaValidCtxtPtr ctxt, } /** - * @param plug a data structure returned by xmlSchemaSAXPlug - * * Unplug a SAX based validation layer in a SAX parsing event flow. * The original pointers used in the call are restored. * + * @param plug a data structure returned by xmlSchemaSAXPlug * @returns 0 in case of success and -1 in case of failure. */ int @@ -28414,14 +28257,14 @@ xmlSchemaSAXUnplug(xmlSchemaSAXPlugPtr plug) } /** - * @param vctxt a schema validation context - * @param f the locator function pointer - * @param ctxt the locator context - * * Allows to set a locator function to the validation context, * which will be used to provide file and line information since * those are not provided as part of the SAX validation flow * Setting `f` to NULL disable the locator. + * + * @param vctxt a schema validation context + * @param f the locator function pointer + * @param ctxt the locator context */ void @@ -28435,12 +28278,11 @@ xmlSchemaValidateSetLocator(xmlSchemaValidCtxtPtr vctxt, } /** + * Internal locator function for the readers + * * @param ctx the xmlTextReaderPtr used * @param file returned file information * @param line returned line information - * - * Internal locator function for the readers - * * @returns 0 in case the Schema validation could be (de)activated and * -1 in case of error. */ @@ -28471,7 +28313,6 @@ xmlSchemaValidateStreamLocator(void *ctx, const char **file, /** * @param ctxt a schema validation context * @param pctxt a parser context - * * @returns 0 if the document is schemas valid, a positive error code * number otherwise and -1 in case of internal or API error. */ @@ -28517,16 +28358,15 @@ done: } /** + * Validate an input based on a flow of SAX event from the parser + * and forward the events to the `sax` handler with the provided `user_data` + * the user provided `sax` handler must be a SAX2 one. + * * @param ctxt a schema validation context * @param input the input to use for reading the data * @param enc an optional encoding information * @param sax a SAX handler for the resulting events * @param user_data the context to provide to the SAX handler. - * - * Validate an input based on a flow of SAX event from the parser - * and forward the events to the `sax` handler with the provided `user_data` - * the user provided `sax` handler must be a SAX2 one. - * * @returns 0 if the document is schemas valid, a positive error code * number otherwise and -1 in case of internal or API error. */ @@ -28586,13 +28426,12 @@ done: } /** - * @param ctxt a schema validation context - * @param filename the URI of the instance - * @param options a future set of options, currently unused - * * Do a schemas validation of the given resource, it will use the * SAX streamable validation internally. * + * @param ctxt a schema validation context + * @param filename the URI of the instance + * @param options a future set of options, currently unused * @returns 0 if the document is valid, a positive error code * number otherwise and -1 in case of an internal or API error. */ @@ -28619,10 +28458,9 @@ xmlSchemaValidateFile(xmlSchemaValidCtxtPtr ctxt, } /** - * @param ctxt a schema validation context - * * allow access to the parser context of the schema validation context * + * @param ctxt a schema validation context * @returns the parser context of the schema validation context or NULL * in case of error. */ diff --git a/xmlschemastypes.c b/xmlschemastypes.c index 6274f995..465901f0 100644 --- a/xmlschemastypes.c +++ b/xmlschemastypes.c @@ -204,10 +204,9 @@ xmlSchemaTypeErrMemory(void) ************************************************************************/ /** - * @param type the value type - * * Allocate a new simple type value * + * @param type the value type * @returns a pointer to the new value or NULL in case of error */ static xmlSchemaValPtr @@ -861,12 +860,13 @@ error: } /** + * Cleanup the default XML Schemas type library + * * @deprecated This function will be made private. Call xmlCleanupParser() * to free global state but see the warnings there. xmlCleanupParser() * should be only called once at program exit. In most cases, you don't * have to call cleanup functions at all. * - * Cleanup the default XML Schemas type library */ void xmlSchemaCleanupTypes(void) { @@ -877,12 +877,11 @@ xmlSchemaCleanupTypes(void) { } /** - * @param type the built-in type - * @param facetType the facet type - * * Evaluates if a specific facet can be * used in conjunction with a type. * + * @param type the built-in type + * @param facetType the facet type * @returns 1 if the facet can be used with the given built-in type, * 0 otherwise and -1 in case the type is not a built-in type. */ @@ -956,11 +955,10 @@ xmlSchemaIsBuiltInTypeFacet(xmlSchemaTypePtr type, int facetType) } /** - * @param type the type of the built in type - * * Gives you the type struct for a built-in * type by its type id. * + * @param type the type of the built in type * @returns the type if found, NULL otherwise. */ xmlSchemaTypePtr @@ -1069,11 +1067,10 @@ xmlSchemaGetBuiltInType(xmlSchemaValType type) } /** - * @param prev the value - * @param cur the value to be appended - * * Appends a next sibling to a list of computed values. * + * @param prev the value + * @param cur the value to be appended * @returns 0 if succeeded and -1 on API errors. */ int @@ -1086,10 +1083,9 @@ xmlSchemaValueAppend(xmlSchemaValPtr prev, xmlSchemaValPtr cur) { } /** - * @param cur the value - * * Accessor for the next sibling of a list of computed values. * + * @param cur the value * @returns the next value or NULL if there was none, or on * API errors. */ @@ -1102,10 +1098,9 @@ xmlSchemaValueGetNext(xmlSchemaValPtr cur) { } /** - * @param val the value - * * Accessor for the string value of a computed value. * + * @param val the value * @returns the string value or NULL if there was none, or on * API errors. */ @@ -1135,10 +1130,9 @@ xmlSchemaValueGetAsString(xmlSchemaValPtr val) } /** - * @param val the value - * * Accessor for the boolean value of a computed value. * + * @param val the value * @returns 1 if true and 0 if false, or in case of an error. Hmm. */ int @@ -1150,15 +1144,14 @@ xmlSchemaValueGetAsBoolean(xmlSchemaValPtr val) } /** - * @param type the value type - * @param value the value - * * Allocate a new simple type value. The type can be * of XML_SCHEMAS_STRING. * WARNING: This one is intended to be expanded for other * string based types. We need this for anySimpleType as well. * The given value is consumed and freed with the struct. * + * @param type the value type + * @param value the value * @returns a pointer to the new value or NULL in case of error */ xmlSchemaValPtr @@ -1180,12 +1173,11 @@ xmlSchemaNewStringValue(xmlSchemaValType type, } /** - * @param name the notation name - * @param ns the notation namespace name or NULL - * * Allocate a new NOTATION value. * The given values are consumed and freed with the struct. * + * @param name the notation name + * @param ns the notation namespace name or NULL * @returns a pointer to the new value or NULL in case of error */ xmlSchemaValPtr @@ -1205,12 +1197,11 @@ xmlSchemaNewNOTATIONValue(const xmlChar *name, } /** - * @param namespaceName the namespace name - * @param localName the local name - * * Allocate a new QName value. * The given values are consumed and freed with the struct. * + * @param namespaceName the namespace name + * @param localName the local name * @returns a pointer to the new value or NULL in case of an error. */ xmlSchemaValPtr @@ -1229,9 +1220,9 @@ xmlSchemaNewQNameValue(const xmlChar *namespaceName, } /** - * @param value the value to free - * * Cleanup the default XML Schemas type library + * + * @param value the value to free */ void xmlSchemaFreeValue(xmlSchemaValPtr value) { @@ -1299,11 +1290,10 @@ xmlSchemaFreeValue(xmlSchemaValPtr value) { } /** - * @param name the type name - * @param ns the URI of the namespace usually "http://www.w3.org/2001/XMLSchema" - * * Lookup a type in the default XML Schemas type library * + * @param name the type name + * @param ns the URI of the namespace usually "http://www.w3.org/2001/XMLSchema" * @returns the type if found, NULL otherwise */ xmlSchemaTypePtr @@ -1317,10 +1307,9 @@ xmlSchemaGetPredefinedType(const xmlChar *name, const xmlChar *ns) { } /** - * @param type the built-in simple type. - * * Lookup function * + * @param type the built-in simple type. * @returns the item type of `type` as defined by the built-in datatype * hierarchy of XML Schema Part 2: Datatypes, or NULL in case of an error. */ @@ -1406,14 +1395,13 @@ static const long dayInLeapYearByMonth[12] = dayInYearByMonth[month - 1]) + day) /** - * @param dt pointer to a date structure - * @param str pointer to the string to analyze - * * Parses a xs:gYear without time zone and fills in the appropriate * field of the `dt` structure. `str` is updated to point just after the * xs:gYear. It is supposed that `dt`->year is big enough to contain * the year. * + * @param dt pointer to a date structure + * @param str pointer to the string to analyze * @returns 0 or the error code */ static int @@ -1461,14 +1449,14 @@ _xmlSchemaParseGYear (xmlSchemaValDatePtr dt, const xmlChar **str) { } /** - * @param num the integer to fill in - * @param cur an \#xmlChar * - * @param invalid an integer - * * Parses a 2-digits integer and updates `num` with the value. `cur` is * updated to point just after the integer. * In case of error, `invalid` is set to %TRUE, values of `num` and * `cur` are undefined. + * + * @param num the integer to fill in + * @param cur an \#xmlChar * + * @param invalid an integer */ #define PARSE_2_DIGITS(num, cur, invalid) \ if ((cur[0] < '0') || (cur[0] > '9') || \ @@ -1479,15 +1467,15 @@ _xmlSchemaParseGYear (xmlSchemaValDatePtr dt, const xmlChar **str) { cur += 2; /** - * @param num the double to fill in - * @param cur an \#xmlChar * - * @param invalid an integer - * * Parses a float and updates `num` with the value. `cur` is * updated to point just after the float. The float must have a * 2-digits integer part and may or may not have a decimal part. * In case of error, `invalid` is set to %TRUE, values of `num` and * `cur` are undefined. + * + * @param num the double to fill in + * @param cur an \#xmlChar * + * @param invalid an integer */ #define PARSE_FLOAT(num, cur, invalid) \ PARSE_2_DIGITS(num, cur, invalid); \ @@ -1504,13 +1492,12 @@ _xmlSchemaParseGYear (xmlSchemaValDatePtr dt, const xmlChar **str) { } /** - * @param dt pointer to a date structure - * @param str pointer to the string to analyze - * * Parses a xs:gMonth without time zone and fills in the appropriate * field of the `dt` structure. `str` is updated to point just after the * xs:gMonth. * + * @param dt pointer to a date structure + * @param str pointer to the string to analyze * @returns 0 or the error code */ static int @@ -1533,13 +1520,12 @@ _xmlSchemaParseGMonth (xmlSchemaValDatePtr dt, const xmlChar **str) { } /** - * @param dt pointer to a date structure - * @param str pointer to the string to analyze - * * Parses a xs:gDay without time zone and fills in the appropriate * field of the `dt` structure. `str` is updated to point just after the * xs:gDay. * + * @param dt pointer to a date structure + * @param str pointer to the string to analyze * @returns 0 or the error code */ static int @@ -1561,14 +1547,13 @@ _xmlSchemaParseGDay (xmlSchemaValDatePtr dt, const xmlChar **str) { } /** - * @param dt pointer to a date structure - * @param str pointer to the string to analyze - * * Parses a xs:time without time zone and fills in the appropriate * fields of the `dt` structure. `str` is updated to point just after the * xs:time. * In case of error, values of `dt` fields are undefined. * + * @param dt pointer to a date structure + * @param str pointer to the string to analyze * @returns 0 or the error code */ static int @@ -1612,13 +1597,12 @@ _xmlSchemaParseTime (xmlSchemaValDatePtr dt, const xmlChar **str) { } /** - * @param dt pointer to a date structure - * @param str pointer to the string to analyze - * * Parses a time zone without time zone and fills in the appropriate * field of the `dt` structure. `str` is updated to point just after the * time zone. * + * @param dt pointer to a date structure + * @param str pointer to the string to analyze * @returns 0 or the error code */ static int @@ -1686,10 +1670,9 @@ _xmlSchemaParseTimeZone (xmlSchemaValDatePtr dt, const xmlChar **str) { } /** - * @param ch a character - * * Converts a base64 encoded character to its base 64 value. * + * @param ch a character * @returns 0-63 (value), 64 (pad), or -1 (not recognized) */ static int @@ -1710,14 +1693,14 @@ _xmlSchemaBase64Decode (const xmlChar ch) { ****************************************************************/ /** - * @param num the integer to fill in - * @param cur an \#xmlChar * - * @param num_type an integer flag - * * Parses a digits integer and updates `num` with the value. `cur` is * updated to point just after the integer. * In case of error, `num_type` is set to -1, values of `num` and * `cur` are undefined. + * + * @param num the integer to fill in + * @param cur an \#xmlChar * + * @param num_type an integer flag */ #define PARSE_DIGITS(num, cur, num_type) \ if ((*cur < '0') || (*cur > '9')) \ @@ -1729,16 +1712,16 @@ _xmlSchemaBase64Decode (const xmlChar ch) { } /** - * @param num the double to fill in - * @param cur an \#xmlChar * - * @param num_type an integer flag - * * Parses a float or integer and updates `num` with the value. `cur` is * updated to point just after the number. If the number is a float, * then it must have an integer part and a decimal part; `num_type` will * be set to 1. If there is no decimal part, `num_type` is set to zero. * In case of error, `num_type` is set to -1, values of `num` and * `cur` are undefined. + * + * @param num the double to fill in + * @param cur an \#xmlChar * + * @param num_type an integer flag */ #define PARSE_NUM(num, cur, num_type) \ num = 0; \ @@ -1758,14 +1741,13 @@ _xmlSchemaBase64Decode (const xmlChar ch) { } /** + * Check that `dateTime` conforms to the lexical space of one of the date types. + * if true a value is computed and returned in `val`. + * * @param type the expected type or XML_SCHEMAS_UNKNOWN * @param dateTime string to analyze * @param val the return computed value * @param collapse whether to collapse - * - * Check that `dateTime` conforms to the lexical space of one of the date types. - * if true a value is computed and returned in `val`. - * * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -1981,14 +1963,13 @@ error: } /** + * Check that `duration` conforms to the lexical space of the duration type. + * if true a value is computed and returned in `val`. + * * @param type the predefined type * @param duration string to analyze * @param val the return computed value * @param collapse whether to collapse - * - * Check that `duration` conforms to the lexical space of the duration type. - * if true a value is computed and returned in `val`. - * * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -2155,10 +2136,9 @@ error: } /** - * @param value a value - * * Removes the leading and ending spaces of a string * + * @param value a value * @returns the new string or NULL if no change was required. */ static xmlChar * @@ -2178,10 +2158,9 @@ xmlSchemaStrip(const xmlChar *value) { } /** - * @param value a value - * * Replaces 0xd, 0x9 and 0xa with a space. * + * @param value a value * @returns the new string or NULL if no change was required. */ xmlChar * @@ -2212,10 +2191,9 @@ xmlSchemaWhiteSpaceReplace(const xmlChar *value) { } /** - * @param value a value - * * Removes and normalize white spaces in the string * + * @param value a value * @returns the new string or NULL if no change was required. */ xmlChar * @@ -2263,14 +2241,13 @@ xmlSchemaCollapseString(const xmlChar *value) { } /** + * Check that a value conforms to the lexical space of the predefined + * list type. if true a value is computed and returned in `ret`. + * * @param type the predefined atomic type for a token in the list * @param value the list value to check * @param ret the return computed value * @param node the node containing the value - * - * Check that a value conforms to the lexical space of the predefined - * list type. if true a value is computed and returned in `ret`. - * * @returns the number of items if this validates, a negative error code * number otherwise */ @@ -2332,11 +2309,10 @@ xmlSchemaValAtomicListNode(xmlSchemaTypePtr type, const xmlChar *value, } /** - * @param str pointer to the string R/W - * @param val pointer to the resulting decimal - * * Parse an unsigned long into a decimal. * + * @param str pointer to the string R/W + * @param val pointer to the resulting decimal * @returns the number of significant digits in the number or * -1 if overflow of the capacity and -2 if it's not a number. */ @@ -2417,6 +2393,10 @@ xmlSchemaCheckLanguageType(const xmlChar* value) { } /** + * Check that a value conforms to the lexical space of the atomic type. + * if true a value is computed and returned in `val`. + * This checks the value space for list types as well (IDREFS, NMTOKENS). + * * @param type the predefined type * @param value the value to check * @param val the return computed value @@ -2426,11 +2406,6 @@ xmlSchemaCheckLanguageType(const xmlChar* value) { * @param normOnTheFly whether to normalize on the fly * @param applyNorm whether to apply normalization * @param createStringValue whether to create a string value - * - * Check that a value conforms to the lexical space of the atomic type. - * if true a value is computed and returned in `val`. - * This checks the value space for list types as well (IDREFS, NMTOKENS). - * * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -3603,14 +3578,13 @@ xmlSchemaValAtomicType(xmlSchemaTypePtr type, const xmlChar * value, } /** + * Check that a value conforms to the lexical space of the predefined type. + * if true a value is computed and returned in `val`. + * * @param type the predefined type * @param value the value to check * @param val the return computed value * @param node the node containing the value - * - * Check that a value conforms to the lexical space of the predefined type. - * if true a value is computed and returned in `val`. - * * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -3622,15 +3596,14 @@ xmlSchemaValPredefTypeNode(xmlSchemaTypePtr type, const xmlChar *value, } /** - * @param type the predefined type - * @param value the value to check - * @param val the return computed value - * @param node the node containing the value - * * Check that a value conforms to the lexical space of the predefined type. * if true a value is computed and returned in `val`. * This one does apply any normalization to the value. * + * @param type the predefined type + * @param value the value to check + * @param val the return computed value + * @param node the node containing the value * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -3642,13 +3615,12 @@ xmlSchemaValPredefTypeNodeNoNorm(xmlSchemaTypePtr type, const xmlChar *value, } /** - * @param type the predefined type - * @param value the value to check - * @param val the return computed value - * * Check that a value conforms to the lexical space of the predefined type. * if true a value is computed and returned in `val`. * + * @param type the predefined type + * @param value the value to check + * @param val the return computed value * @returns 0 if this validates, a positive error code number otherwise * and -1 in case of internal or API error. */ @@ -3659,11 +3631,10 @@ xmlSchemaValidatePredefinedType(xmlSchemaTypePtr type, const xmlChar *value, } /** - * @param x a first decimal value - * @param y a second decimal value - * * Compare 2 decimals * + * @param x a first decimal value + * @param y a second decimal value * @returns -1 if x < y, 0 if x == y, 1 if x > y and -2 in case of error */ static int @@ -3682,11 +3653,10 @@ xmlSchemaCompareDecimals(xmlSchemaValPtr x, xmlSchemaValPtr y) } /** - * @param x a first duration value - * @param y a second duration value - * * Compare 2 durations * + * @param x a first duration value + * @param y a second duration value * @returns -1 if x < y, 0 if x == y, 1 if x > y, 2 if x <> y, and -2 in * case of error */ @@ -3783,11 +3753,10 @@ xmlSchemaCompareDurations(xmlSchemaValPtr x, xmlSchemaValPtr y) #define MODULO_RANGE(a,low,high) ((MODULO((a-low),(high-low)))+low) /** - * @param v the \#xmlSchemaValPtr value to duplicate - * * Makes a copy of `v`. The calling program is responsible for freeing * the returned value. * + * @param v the \#xmlSchemaValPtr value to duplicate * @returns a pointer to a duplicated \#xmlSchemaValPtr or NULL if error. */ static xmlSchemaValPtr @@ -3803,10 +3772,9 @@ xmlSchemaDupVal (xmlSchemaValPtr v) } /** - * @param val the precomputed value to be copied - * * Copies the precomputed value. This duplicates any string within. * + * @param val the precomputed value to be copied * @returns the copy or NULL if a copy for a data-type is not implemented. */ xmlSchemaValPtr @@ -3895,14 +3863,13 @@ xmlSchemaCopyValue(xmlSchemaValPtr val) } /** - * @param dt an \#xmlSchemaValPtr - * @param dur an \#xmlSchemaValPtr of type \#XS_DURATION - * * Compute a new date/time from `dt` and `dur`. This function assumes `dt` * is either \#XML_SCHEMAS_DATETIME, \#XML_SCHEMAS_DATE, \#XML_SCHEMAS_GYEARMONTH, * or \#XML_SCHEMAS_GYEAR. The returned \#xmlSchemaVal is the same type as * `dt`. The calling program is responsible for freeing the returned value. * + * @param dt an \#xmlSchemaValPtr + * @param dur an \#xmlSchemaValPtr of type \#XS_DURATION * @returns a pointer to a new \#xmlSchemaVal or NULL if error. */ static xmlSchemaValPtr @@ -4049,12 +4016,11 @@ _xmlSchemaDateAdd (xmlSchemaValPtr dt, xmlSchemaValPtr dur) } /** - * @param dt an \#xmlSchemaValPtr of a date/time type value. - * @param offset number of seconds to adjust `dt` by. - * * Normalize `dt` to GMT time. The `offset` parameter is subtracted from * the return value is a time-zone offset is present on `dt`. * + * @param dt an \#xmlSchemaValPtr of a date/time type value. + * @param offset number of seconds to adjust `dt` by. * @returns a normalized copy of `dt` or NULL if error. */ static xmlSchemaValPtr @@ -4088,13 +4054,12 @@ xmlSchemaDateNormalize (xmlSchemaValPtr dt, double offset) } /** - * @param dt an \#xmlSchemaValPtr - * * Convert mon and year of `dt` to total number of days. Take the * number of years since (or before) 1 AD and add the number of leap * years. This is a function because negative * years must be handled a little differently and there is no zero year. * + * @param dt an \#xmlSchemaValPtr * @returns number of days. */ static long @@ -4121,10 +4086,9 @@ _xmlSchemaDateCastYMToDays (const xmlSchemaValPtr dt) } /** - * @param dt an \#xmlSchemaValPtr - * * Calculates the number of seconds in the time portion of `dt`. * + * @param dt an \#xmlSchemaValPtr * @returns seconds. */ #define TIME_TO_NUMBER(dt) \ @@ -4134,11 +4098,10 @@ _xmlSchemaDateCastYMToDays (const xmlSchemaValPtr dt) dt->value.date.sec) /** - * @param x a first date/time value - * @param y a second date/time value - * * Compare 2 date/times * + * @param x a first date/time value + * @param y a second date/time value * @returns -1 if x < y, 0 if x == y, 1 if x > y, 2 if x <> y, and -2 in * case of error */ @@ -4426,15 +4389,14 @@ xmlSchemaCompareDates (xmlSchemaValPtr x, xmlSchemaValPtr y) } /** - * @param x a first string value - * @param y a second string value - * @param invert inverts the result if x < y or x > y. - * * Compare 2 string for their normalized values. * `x` is a string with whitespace of "preserve", `y` is * a string with a whitespace of "replace". I.e. `x` could * be an "xsd:string" and `y` an "xsd:normalizedString". * + * @param x a first string value + * @param y a second string value + * @param invert inverts the result if x < y or x > y. * @returns -1 if x < y, 0 if x == y, 1 if x > y, and -2 in * case of error */ @@ -4494,15 +4456,14 @@ xmlSchemaComparePreserveReplaceStrings(const xmlChar *x, } /** - * @param x a first string value - * @param y a second string value - * @param invert whether to invert - * * Compare 2 string for their normalized values. * `x` is a string with whitespace of "preserve", `y` is * a string with a whitespace of "collapse". I.e. `x` could * be an "xsd:string" and `y` an "xsd:normalizedString". * + * @param x a first string value + * @param y a second string value + * @param invert whether to invert * @returns -1 if x < y, 0 if x == y, 1 if x > y, and -2 in * case of error */ @@ -4583,15 +4544,14 @@ xmlSchemaComparePreserveCollapseStrings(const xmlChar *x, } /** - * @param x a first string value - * @param y a second string value - * @param invert whether to invert - * * Compare 2 string for their normalized values. * `x` is a string with whitespace of "preserve", `y` is * a string with a whitespace of "collapse". I.e. `x` could * be an "xsd:string" and `y` an "xsd:normalizedString". * + * @param x a first string value + * @param y a second string value + * @param invert whether to invert * @returns -1 if x < y, 0 if x == y, 1 if x > y, and -2 in * case of error */ @@ -4681,11 +4641,10 @@ xmlSchemaCompareReplaceCollapseStrings(const xmlChar *x, /** - * @param x a first string value - * @param y a second string value - * * Compare 2 string for their normalized values. * + * @param x a first string value + * @param y a second string value * @returns -1 if x < y, 0 if x == y, 1 if x > y, and -2 in * case of error */ @@ -4727,11 +4686,10 @@ xmlSchemaCompareReplacedStrings(const xmlChar *x, } /** - * @param x a first string value - * @param y a second string value - * * Compare 2 string for their normalized values. * + * @param x a first string value + * @param y a second string value * @returns -1 if x < y, 0 if x == y, 1 if x > y, and -2 in * case of error */ @@ -4772,11 +4730,10 @@ xmlSchemaCompareNormStrings(const xmlChar *x, } /** - * @param x a first float or double value - * @param y a second float or double value - * * Compare 2 values * + * @param x a first float or double value + * @param y a second float or double value * @returns -1 if x < y, 0 if x == y, 1 if x > y, 2 if x <> y, and -2 in * case of error */ @@ -4830,6 +4787,8 @@ xmlSchemaCompareFloats(xmlSchemaValPtr x, xmlSchemaValPtr y) { } /** + * Compare 2 values + * * @param xtype first type * @param x a first value * @param xvalue the first value as a string (optional) @@ -4838,9 +4797,6 @@ xmlSchemaCompareFloats(xmlSchemaValPtr x, xmlSchemaValPtr y) { * @param y a second value * @param yvalue the second value as a string (optional) * @param yws the whitespace type - * - * Compare 2 values - * * @returns -1 if x < y, 0 if x == y, 1 if x > y, 2 if x <> y, 3 if not * comparable and -2 in case of error */ @@ -5081,11 +5037,10 @@ xmlSchemaCompareValuesInternal(xmlSchemaValType xtype, } /** - * @param x a first value - * @param y a second value - * * Compare 2 values * + * @param x a first value + * @param y a second value * @returns -1 if x < y, 0 if x == y, 1 if x > y, 2 if x <> y, and -2 in * case of error */ @@ -5114,13 +5069,12 @@ xmlSchemaCompareValues(xmlSchemaValPtr x, xmlSchemaValPtr y) { } /** + * Compare 2 values + * * @param x a first value * @param xws the whitespace value of x * @param y a second value * @param yws the whitespace value of y - * - * Compare 2 values - * * @returns -1 if x < y, 0 if x == y, 1 if x > y, 2 if x <> y, and -2 in * case of error */ @@ -5137,6 +5091,8 @@ xmlSchemaCompareValuesWhtsp(xmlSchemaValPtr x, } /** + * Compare 2 values + * * @param xtype first type * @param x a first value * @param xvalue the first value as a string (optional) @@ -5145,9 +5101,6 @@ xmlSchemaCompareValuesWhtsp(xmlSchemaValPtr x, * @param y a second value * @param yvalue the second value as a string (optional) * @param yws the whitespace type - * - * Compare 2 values - * * @returns -1 if x < y, 0 if x == y, 1 if x > y, 2 if x <> y, and -2 in * case of error */ @@ -5166,10 +5119,9 @@ xmlSchemaCompareValuesWhtspExt(xmlSchemaValType xtype, } /** - * @param value a string - * * Computes the UTF8 length of the normalized value of the string * + * @param value a string * @returns the length or -1 in case of error. */ static int @@ -5211,10 +5163,9 @@ xmlSchemaNormLen(const xmlChar *value) { } /** - * @param facet an schemas type facet - * * Extract the value of a facet * + * @param facet an schemas type facet * @returns the value as a long */ unsigned long @@ -5230,13 +5181,12 @@ xmlSchemaGetFacetValueAsULong(xmlSchemaFacetPtr facet) } /** + * Checks the value of a list simple type against a facet. + * * @param facet the facet to check * @param value the lexical repr of the value to validate * @param actualLen the number of list items * @param expectedLen the resulting expected number of list items - * - * Checks the value of a list simple type against a facet. - * * @returns 0 if the value is valid, a positive error code * number otherwise and -1 in case of an internal error. */ @@ -5281,16 +5231,15 @@ xmlSchemaValidateListSimpleTypeFacet(xmlSchemaFacetPtr facet, } /** + * Checka a value against a "length", "minLength" and "maxLength" + * facet; sets `length` to the computed length of `value`. + * * @param facet the facet to check * @param valType the built-in type * @param value the lexical repr. of the value to be validated * @param val the precomputed value * @param length the actual length of the value * @param ws the whitespace type of the value - * - * Checka a value against a "length", "minLength" and "maxLength" - * facet; sets `length` to the computed length of `value`. - * * @returns 0 if the value is valid, a positive error code * otherwise and -1 in case of an internal or API error. */ @@ -5397,15 +5346,14 @@ xmlSchemaValidateLengthFacetInternal(xmlSchemaFacetPtr facet, } /** + * Checka a value against a "length", "minLength" and "maxLength" + * facet; sets `length` to the computed length of `value`. + * * @param type the built-in type * @param facet the facet to check * @param value the lexical repr. of the value to be validated * @param val the precomputed value * @param length the actual length of the value - * - * Checka a value against a "length", "minLength" and "maxLength" - * facet; sets `length` to the computed length of `value`. - * * @returns 0 if the value is valid, a positive error code * otherwise and -1 in case of an internal or API error. */ @@ -5424,16 +5372,15 @@ xmlSchemaValidateLengthFacet(xmlSchemaTypePtr type, } /** + * Checka a value against a "length", "minLength" and "maxLength" + * facet; sets `length` to the computed length of `value`. + * * @param facet the facet to check * @param valType the built-in type * @param value the lexical repr. of the value to be validated * @param val the precomputed value * @param ws the whitespace type of the value * @param length the actual length of the value - * - * Checka a value against a "length", "minLength" and "maxLength" - * facet; sets `length` to the computed length of `value`. - * * @returns 0 if the value is valid, a positive error code * otherwise and -1 in case of an internal or API error. */ @@ -5450,15 +5397,14 @@ xmlSchemaValidateLengthFacetWhtsp(xmlSchemaFacetPtr facet, } /** + * Check a value against a facet condition + * * @param facet the facet to check * @param fws the whitespace type of the facet's value * @param valType the built-in type of the value * @param value the lexical repr of the value to validate * @param val the precomputed value * @param ws the whitespace type of the value - * - * Check a value against a facet condition - * * @returns 0 if the element is schemas valid, a positive error code * number otherwise and -1 in case of internal or API error. */ @@ -5685,13 +5631,12 @@ xmlSchemaValidateFacetInternal(xmlSchemaFacetPtr facet, } /** + * Check a value against a facet condition + * * @param base the base type * @param facet the facet to check * @param value the lexical repr of the value to validate * @param val the precomputed value - * - * Check a value against a facet condition - * * @returns 0 if the element is schemas valid, a positive error code * number otherwise and -1 in case of internal or API error. */ @@ -5718,18 +5663,17 @@ xmlSchemaValidateFacet(xmlSchemaTypePtr base, } /** + * Check a value against a facet condition. This takes value normalization + * according to the specified whitespace types into account. + * Note that `value` needs to be the *normalized* value if the facet + * is of type "pattern". + * * @param facet the facet to check * @param fws the whitespace type of the facet's value * @param valType the built-in type of the value * @param value the lexical (or normalized for pattern) repr of the value to validate * @param val the precomputed value * @param ws the whitespace type of the value - * - * Check a value against a facet condition. This takes value normalization - * according to the specified whitespace types into account. - * Note that `value` needs to be the *normalized* value if the facet - * is of type "pattern". - * * @returns 0 if the element is schemas valid, a positive error code * number otherwise and -1 in case of internal or API error. */ @@ -5746,9 +5690,6 @@ xmlSchemaValidateFacetWhtsp(xmlSchemaFacetPtr facet, } /** - * @param val the precomputed value - * @param retValue the returned value - * * Get the canonical lexical representation of the value. * The caller has to FREE the returned retValue. * @@ -5760,6 +5701,8 @@ xmlSchemaValidateFacetWhtsp(xmlSchemaFacetPtr facet, * anyURI, QName, NOTATION. This will be fixed in XML Schema 1.1. * * + * @param val the precomputed value + * @param retValue the returned value * @returns 0 if the value could be built, 1 if the value type is * not supported yet and -1 in case of API errors. */ @@ -6084,13 +6027,12 @@ xmlSchemaGetCanonValue(xmlSchemaValPtr val, const xmlChar **retValue) } /** - * @param val the precomputed value - * @param retValue the returned value - * @param ws the whitespace type of the value - * * Get the canonical representation of the value. * The caller has to free the returned `retValue`. * + * @param val the precomputed value + * @param retValue the returned value + * @param ws the whitespace type of the value * @returns 0 if the value could be built, 1 if the value type is * not supported yet and -1 in case of API errors. */ @@ -6136,10 +6078,9 @@ xmlSchemaGetCanonValueWhtsp(xmlSchemaValPtr val, } /** - * @param val a schemas value - * * Accessor for the type of a value * + * @param val a schemas value * @returns the xmlSchemaValType of the value */ xmlSchemaValType diff --git a/xmlstring.c b/xmlstring.c index fb8643cc..1c306d2e 100644 --- a/xmlstring.c +++ b/xmlstring.c @@ -40,11 +40,10 @@ ************************************************************************/ /** - * @param cur the input xmlChar * - * @param len the len of `cur` - * * a strndup for array of xmlChar's * + * @param cur the input xmlChar * + * @param len the len of `cur` * @returns a new xmlChar * or NULL */ xmlChar * @@ -62,12 +61,11 @@ xmlStrndup(const xmlChar *cur, int len) { } /** - * @param cur the input xmlChar * - * * a strdup for array of xmlChar's. Since they are supposed to be * encoded in UTF-8 or an encoding with 8bit based chars, we assume * a termination mark of '0'. * + * @param cur the input xmlChar * * @returns a new xmlChar * or NULL */ xmlChar * @@ -80,11 +78,10 @@ xmlStrdup(const xmlChar *cur) { } /** - * @param cur the input char * - * @param len the len of `cur` - * * a strndup for char's to xmlChar's * + * @param cur the input char * + * @param len the len of `cur` * @returns a new xmlChar * or NULL */ @@ -108,10 +105,9 @@ xmlCharStrndup(const char *cur, int len) { } /** - * @param cur the input char * - * * a strdup for char's to xmlChar's * + * @param cur the input char * * @returns a new xmlChar * or NULL */ @@ -125,11 +121,10 @@ xmlCharStrdup(const char *cur) { } /** - * @param str1 the first xmlChar * - * @param str2 the second xmlChar * - * * a strcmp for xmlChar's * + * @param str1 the first xmlChar * + * @param str2 the second xmlChar * * @returns the integer result of the comparison */ @@ -150,12 +145,11 @@ xmlStrcmp(const xmlChar *str1, const xmlChar *str2) { } /** - * @param str1 the first xmlChar * - * @param str2 the second xmlChar * - * * Check if both strings are equal of have same content. * Should be a bit more readable and faster than xmlStrcmp() * + * @param str1 the first xmlChar * + * @param str2 the second xmlChar * * @returns 1 if they are equal, 0 if they are different */ @@ -175,12 +169,11 @@ xmlStrEqual(const xmlChar *str1, const xmlChar *str2) { } /** + * Check if a QName is Equal to a given string + * * @param pref the prefix of the QName * @param name the localname of the QName * @param str the second xmlChar * - * - * Check if a QName is Equal to a given string - * * @returns 1 if they are equal, 0 if they are different */ @@ -201,12 +194,11 @@ xmlStrQEqual(const xmlChar *pref, const xmlChar *name, const xmlChar *str) { } /** + * a strncmp for xmlChar's + * * @param str1 the first xmlChar * * @param str2 the second xmlChar * * @param len the max comparison length - * - * a strncmp for xmlChar's - * * @returns the integer result of the comparison */ @@ -263,11 +255,10 @@ static const xmlChar casemap[256] = { }; /** - * @param str1 the first xmlChar * - * @param str2 the second xmlChar * - * * a strcasecmp for xmlChar's * + * @param str1 the first xmlChar * + * @param str2 the second xmlChar * * @returns the integer result of the comparison */ @@ -286,12 +277,11 @@ xmlStrcasecmp(const xmlChar *str1, const xmlChar *str2) { } /** + * a strncasecmp for xmlChar's + * * @param str1 the first xmlChar * * @param str2 the second xmlChar * * @param len the max comparison length - * - * a strncasecmp for xmlChar's - * * @returns the integer result of the comparison */ @@ -311,11 +301,10 @@ xmlStrncasecmp(const xmlChar *str1, const xmlChar *str2, int len) { } /** - * @param str the xmlChar * array - * @param val the xmlChar to search - * * a strchr for xmlChar's * + * @param str the xmlChar * array + * @param val the xmlChar to search * @returns the xmlChar * for the first occurrence or NULL. */ @@ -330,11 +319,10 @@ xmlStrchr(const xmlChar *str, xmlChar val) { } /** - * @param str the xmlChar * array (haystack) - * @param val the xmlChar to search (needle) - * * a strstr for xmlChar's * + * @param str the xmlChar * array (haystack) + * @param val the xmlChar to search (needle) * @returns the xmlChar * for the first occurrence or NULL. */ @@ -357,11 +345,10 @@ xmlStrstr(const xmlChar *str, const xmlChar *val) { } /** - * @param str the xmlChar * array (haystack) - * @param val the xmlChar to search (needle) - * * a case-ignoring strstr for xmlChar's * + * @param str the xmlChar * array (haystack) + * @param val the xmlChar to search (needle) * @returns the xmlChar * for the first occurrence or NULL. */ @@ -383,12 +370,11 @@ xmlStrcasestr(const xmlChar *str, const xmlChar *val) { } /** + * Extract a substring of a given string + * * @param str the xmlChar * array (haystack) * @param start the index of the first char (zero based) * @param len the length of the substring - * - * Extract a substring of a given string - * * @returns the xmlChar * for the first occurrence or NULL. */ @@ -409,10 +395,9 @@ xmlStrsub(const xmlChar *str, int start, int len) { } /** - * @param str the xmlChar * array - * * length of a xmlChar's string * + * @param str the xmlChar * array * @returns the number of xmlChar contained in the ARRAY. */ @@ -423,14 +408,13 @@ xmlStrlen(const xmlChar *str) { } /** - * @param cur the original xmlChar * array - * @param add the xmlChar * array added - * @param len the length of `add` - * * a strncat for array of xmlChar's, it will extend `cur` with the len * first bytes of `add`. Note that if `len` < 0 then this is an API error * and NULL will be returned. * + * @param cur the original xmlChar * array + * @param add the xmlChar * array added + * @param len the length of `add` * @returns a new xmlChar *, the original `cur` is reallocated and should * not be freed. */ @@ -461,14 +445,13 @@ xmlStrncat(xmlChar *cur, const xmlChar *add, int len) { } /** - * @param str1 first xmlChar string - * @param str2 second xmlChar string - * @param len the len of `str2` or < 0 - * * same as xmlStrncat(), but creates a new string. The original * two strings are not freed. If `len` is < 0 then the length * will be calculated automatically. * + * @param str1 first xmlChar string + * @param str2 second xmlChar string + * @param len the len of `str2` or < 0 * @returns a new xmlChar * or NULL */ xmlChar * @@ -499,13 +482,12 @@ xmlStrncatNew(const xmlChar *str1, const xmlChar *str2, int len) { } /** - * @param cur the original xmlChar * array - * @param add the xmlChar * array added - * * a strcat for array of xmlChar's. Since they are supposed to be * encoded in UTF-8 or an encoding with 8bit based chars, we assume * a termination mark of '0'. * + * @param cur the original xmlChar * array + * @param add the xmlChar * array added * @returns a new xmlChar * containing the concatenated string. The original * `cur` is reallocated and should not be freed. */ @@ -522,13 +504,13 @@ xmlStrcat(xmlChar *cur, const xmlChar *add) { } /** + * Formats `msg` and places result into `buf`. + * + * @...: extra parameters for the message. + * * @param buf the result buffer. * @param len the result buffer length. * @param msg the message with printf formatting. - * @...: extra parameters for the message. - * - * Formats `msg` and places result into `buf`. - * * @returns the number of characters written to `buf` or -1 if an error occurs. */ int @@ -549,13 +531,12 @@ xmlStrPrintf(xmlChar *buf, int len, const char *msg, ...) { } /** + * Formats `msg` and places result into `buf`. + * * @param buf the result buffer. * @param len the result buffer length. * @param msg the message with printf formatting. * @param ap extra parameters for the message. - * - * Formats `msg` and places result into `buf`. - * * @returns the number of characters written to `buf` or -1 if an error occurs. */ int @@ -573,13 +554,12 @@ xmlStrVPrintf(xmlChar *buf, int len, const char *msg, va_list ap) { } /** + * Creates a newly allocated string according to format. + * * @param out pointer to the resulting string * @param maxSize maximum size of the output buffer * @param msg printf format string * @param ap arguments for format string - * - * Creates a newly allocated string according to format. - * * @returns 0 on success, 1 if the result was truncated or on other * errors, -1 if a memory allocation failed. */ @@ -690,13 +670,13 @@ xmlStrVASPrintf(xmlChar **out, int maxSize, const char *msg, va_list ap) { } /** + * See xmlStrVASPrintf(). + * + * @...: arguments for format string + * * @param out pointer to the resulting string * @param maxSize maximum size of the output buffer * @param msg printf format string - * @...: arguments for format string - * - * See xmlStrVASPrintf(). - * * @returns 0 on success, 1 if the result was truncated or on other * errors, -1 if a memory allocation failed. */ @@ -729,10 +709,9 @@ xmlStrASPrintf(xmlChar **out, int maxSize, const char *msg, ...) { /** - * @param utf pointer to the UTF8 character - * * calculates the internal size of a UTF8 character * + * @param utf pointer to the UTF8 character * @returns the numbers of bytes in the character, -1 on format error */ int @@ -758,11 +737,10 @@ xmlUTF8Size(const xmlChar *utf) { } /** - * @param utf1 pointer to first UTF8 char - * @param utf2 pointer to second UTF8 char - * * compares the two UCS4 values * + * @param utf1 pointer to first UTF8 char + * @param utf2 pointer to second UTF8 char * @returns result of the compare as with xmlStrncmp() */ int @@ -777,11 +755,10 @@ xmlUTF8Charcmp(const xmlChar *utf1, const xmlChar *utf2) { } /** - * @param utf a sequence of UTF-8 encoded bytes - * * compute the length of an UTF8 string, it doesn't do a full UTF8 * checking of the content of the string. * + * @param utf a sequence of UTF-8 encoded bytes * @returns the number of characters in the string or -1 in case of error */ int @@ -817,13 +794,12 @@ xmlUTF8Strlen(const xmlChar *utf) { } /** + * Read the first UTF8 character from `utf` + * * @param utf a sequence of UTF-8 encoded bytes * @param len a pointer to the minimum number of bytes present in * the sequence. This is used to assure the next character * is completely contained within the sequence. - * - * Read the first UTF8 character from `utf` - * * @returns the char value or -1 in case of error, and sets *len to * the actual number of bytes consumed (0 in case of error) */ @@ -886,8 +862,6 @@ error: } /** - * @param utf Pointer to putative UTF-8 encoded string. - * * Checks `utf` for being valid UTF-8. `utf` is assumed to be * null-terminated. This function is not super-strict, as it will * allow longer UTF-8 sequences than necessary. Note that Java is @@ -895,6 +869,7 @@ error: * routine checks for the 4-byte maximum size, but does not check for * 0x10ffff maximum value. * + * @param utf Pointer to putative UTF-8 encoded string. * @returns value: true if `utf` is valid. **/ int @@ -940,12 +915,11 @@ xmlCheckUTF8(const unsigned char *utf) } /** - * @param utf a sequence of UTF-8 encoded bytes - * @param len the number of characters in the array - * * storage size of an UTF8 string * the behaviour is not guaranteed if the input string is not UTF-8 * + * @param utf a sequence of UTF-8 encoded bytes + * @param len the number of characters in the array * @returns the storage size of * the first 'len' characters of ARRAY */ @@ -978,11 +952,10 @@ xmlUTF8Strsize(const xmlChar *utf, int len) { /** - * @param utf the input UTF8 * - * @param len the len of `utf` (in chars) - * * a strndup for array of UTF8's * + * @param utf the input UTF8 * + * @param len the len of `utf` (in chars) * @returns a new UTF8 * or NULL */ xmlChar * @@ -1002,12 +975,11 @@ xmlUTF8Strndup(const xmlChar *utf, int len) { } /** - * @param utf the input UTF8 * - * @param pos the position of the desired UTF8 char (in chars) - * * a function to provide the equivalent of fetching a * character from a string array * + * @param utf the input UTF8 * + * @param pos the position of the desired UTF8 char (in chars) * @returns a pointer to the UTF8 character or NULL */ const xmlChar * @@ -1035,11 +1007,10 @@ xmlUTF8Strpos(const xmlChar *utf, int pos) { } /** - * @param utf the input UTF8 * - * @param utfchar the UTF8 character to be found - * * a function to provide the relative location of a UTF8 char * + * @param utf the input UTF8 * + * @param utfchar the UTF8 character to be found * @returns the relative character position of the desired char * or -1 if not found */ @@ -1069,13 +1040,12 @@ xmlUTF8Strloc(const xmlChar *utf, const xmlChar *utfchar) { return(-1); } /** - * @param utf a sequence of UTF-8 encoded bytes - * @param start relative pos of first char - * @param len total number to copy - * * Create a substring from a given UTF-8 string * Note: positions are given in units of UTF-8 chars * + * @param utf a sequence of UTF-8 encoded bytes + * @param start relative pos of first char + * @param len total number to copy * @returns a pointer to a newly created string or NULL if the * start index is out of bounds or a memory allocation failed. * If len is too large, the result is truncated. @@ -1112,11 +1082,11 @@ xmlUTF8Strsub(const xmlChar *utf, int start, int len) { } /** + * Replaces the string pointed to by 'msg' with an escaped string. + * * @param msg a pointer to the string in which to escape '%' characters. * Must be a heap-allocated buffer created by libxml2 that may be * returned, or that may be freed and replaced. - * - * Replaces the string pointed to by 'msg' with an escaped string. * @returns the same string with all '%' characters escaped. */ xmlChar * diff --git a/xmlunicode.c b/xmlunicode.c index c1a408b8..1826ac47 100644 --- a/xmlunicode.c +++ b/xmlunicode.c @@ -763,11 +763,10 @@ static const xmlChSRange xmlZS[] = {{0x20, 0x20}, {0xa0, 0xa0}, static const xmlChRangeGroup xmlZG = {9,0,xmlZS,NULL}; /** - * @param tptr pointer to the name table - * @param tname name to be found - * * binary table lookup for user-supplied name * + * @param tptr pointer to the name table + * @param tname name to be found * @returns pointer to range function if found, otherwise NULL */ static xmlIntFunc @@ -794,10 +793,9 @@ static xmlIntFunc } /** - * @param code UCS code point - * * Check whether the character is part of AegeanNumbers UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -806,10 +804,9 @@ xmlUCSIsAegeanNumbers(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of AlphabeticPresentationForms UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -818,10 +815,9 @@ xmlUCSIsAlphabeticPresentationForms(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Arabic UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -830,10 +826,9 @@ xmlUCSIsArabic(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of ArabicPresentationForms-A UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -842,10 +837,9 @@ xmlUCSIsArabicPresentationFormsA(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of ArabicPresentationForms-B UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -854,10 +848,9 @@ xmlUCSIsArabicPresentationFormsB(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Armenian UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -866,10 +859,9 @@ xmlUCSIsArmenian(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Arrows UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -878,10 +870,9 @@ xmlUCSIsArrows(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of BasicLatin UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -890,10 +881,9 @@ xmlUCSIsBasicLatin(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Bengali UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -902,10 +892,9 @@ xmlUCSIsBengali(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of BlockElements UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -914,10 +903,9 @@ xmlUCSIsBlockElements(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Bopomofo UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -926,10 +914,9 @@ xmlUCSIsBopomofo(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of BopomofoExtended UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -938,10 +925,9 @@ xmlUCSIsBopomofoExtended(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of BoxDrawing UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -950,10 +936,9 @@ xmlUCSIsBoxDrawing(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of BraillePatterns UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -962,10 +947,9 @@ xmlUCSIsBraillePatterns(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Buhid UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -974,10 +958,9 @@ xmlUCSIsBuhid(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of ByzantineMusicalSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -986,10 +969,9 @@ xmlUCSIsByzantineMusicalSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CJKCompatibility UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -998,10 +980,9 @@ xmlUCSIsCJKCompatibility(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CJKCompatibilityForms UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1010,10 +991,9 @@ xmlUCSIsCJKCompatibilityForms(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CJKCompatibilityIdeographs UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1022,10 +1002,9 @@ xmlUCSIsCJKCompatibilityIdeographs(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CJKCompatibilityIdeographsSupplement UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1034,10 +1013,9 @@ xmlUCSIsCJKCompatibilityIdeographsSupplement(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CJKRadicalsSupplement UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1046,10 +1024,9 @@ xmlUCSIsCJKRadicalsSupplement(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CJKSymbolsandPunctuation UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1058,10 +1035,9 @@ xmlUCSIsCJKSymbolsandPunctuation(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CJKUnifiedIdeographs UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1070,10 +1046,9 @@ xmlUCSIsCJKUnifiedIdeographs(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CJKUnifiedIdeographsExtensionA UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1082,10 +1057,9 @@ xmlUCSIsCJKUnifiedIdeographsExtensionA(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CJKUnifiedIdeographsExtensionB UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1094,10 +1068,9 @@ xmlUCSIsCJKUnifiedIdeographsExtensionB(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Cherokee UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1106,10 +1079,9 @@ xmlUCSIsCherokee(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CombiningDiacriticalMarks UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1118,10 +1090,9 @@ xmlUCSIsCombiningDiacriticalMarks(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CombiningDiacriticalMarksforSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1130,10 +1101,9 @@ xmlUCSIsCombiningDiacriticalMarksforSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CombiningHalfMarks UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1142,10 +1112,9 @@ xmlUCSIsCombiningHalfMarks(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CombiningMarksforSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1154,10 +1123,9 @@ xmlUCSIsCombiningMarksforSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of ControlPictures UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1166,10 +1134,9 @@ xmlUCSIsControlPictures(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CurrencySymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1178,10 +1145,9 @@ xmlUCSIsCurrencySymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CypriotSyllabary UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1190,10 +1156,9 @@ xmlUCSIsCypriotSyllabary(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Cyrillic UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1202,10 +1167,9 @@ xmlUCSIsCyrillic(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of CyrillicSupplement UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1214,10 +1178,9 @@ xmlUCSIsCyrillicSupplement(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Deseret UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1226,10 +1189,9 @@ xmlUCSIsDeseret(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Devanagari UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1238,10 +1200,9 @@ xmlUCSIsDevanagari(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Dingbats UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1250,10 +1211,9 @@ xmlUCSIsDingbats(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of EnclosedAlphanumerics UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1262,10 +1222,9 @@ xmlUCSIsEnclosedAlphanumerics(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of EnclosedCJKLettersandMonths UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1274,10 +1233,9 @@ xmlUCSIsEnclosedCJKLettersandMonths(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Ethiopic UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1286,10 +1244,9 @@ xmlUCSIsEthiopic(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of GeneralPunctuation UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1298,10 +1255,9 @@ xmlUCSIsGeneralPunctuation(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of GeometricShapes UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1310,10 +1266,9 @@ xmlUCSIsGeometricShapes(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Georgian UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1322,10 +1277,9 @@ xmlUCSIsGeorgian(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Gothic UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1334,10 +1288,9 @@ xmlUCSIsGothic(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Greek UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1346,10 +1299,9 @@ xmlUCSIsGreek(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of GreekExtended UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1358,10 +1310,9 @@ xmlUCSIsGreekExtended(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of GreekandCoptic UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1370,10 +1321,9 @@ xmlUCSIsGreekandCoptic(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Gujarati UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1382,10 +1332,9 @@ xmlUCSIsGujarati(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Gurmukhi UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1394,10 +1343,9 @@ xmlUCSIsGurmukhi(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of HalfwidthandFullwidthForms UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1406,10 +1354,9 @@ xmlUCSIsHalfwidthandFullwidthForms(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of HangulCompatibilityJamo UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1418,10 +1365,9 @@ xmlUCSIsHangulCompatibilityJamo(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of HangulJamo UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1430,10 +1376,9 @@ xmlUCSIsHangulJamo(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of HangulSyllables UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1442,10 +1387,9 @@ xmlUCSIsHangulSyllables(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Hanunoo UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1454,10 +1398,9 @@ xmlUCSIsHanunoo(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Hebrew UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1466,10 +1409,9 @@ xmlUCSIsHebrew(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of HighPrivateUseSurrogates UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1478,10 +1420,9 @@ xmlUCSIsHighPrivateUseSurrogates(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of HighSurrogates UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1490,10 +1431,9 @@ xmlUCSIsHighSurrogates(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Hiragana UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1502,10 +1442,9 @@ xmlUCSIsHiragana(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of IPAExtensions UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1514,10 +1453,9 @@ xmlUCSIsIPAExtensions(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of IdeographicDescriptionCharacters UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1526,10 +1464,9 @@ xmlUCSIsIdeographicDescriptionCharacters(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Kanbun UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1538,10 +1475,9 @@ xmlUCSIsKanbun(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of KangxiRadicals UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1550,10 +1486,9 @@ xmlUCSIsKangxiRadicals(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Kannada UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1562,10 +1497,9 @@ xmlUCSIsKannada(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Katakana UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1574,10 +1508,9 @@ xmlUCSIsKatakana(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of KatakanaPhoneticExtensions UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1586,10 +1519,9 @@ xmlUCSIsKatakanaPhoneticExtensions(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Khmer UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1598,10 +1530,9 @@ xmlUCSIsKhmer(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of KhmerSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1610,10 +1541,9 @@ xmlUCSIsKhmerSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Lao UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1622,10 +1552,9 @@ xmlUCSIsLao(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Latin-1Supplement UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1634,10 +1563,9 @@ xmlUCSIsLatin1Supplement(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of LatinExtended-A UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1646,10 +1574,9 @@ xmlUCSIsLatinExtendedA(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of LatinExtended-B UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1658,10 +1585,9 @@ xmlUCSIsLatinExtendedB(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of LatinExtendedAdditional UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1670,10 +1596,9 @@ xmlUCSIsLatinExtendedAdditional(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of LetterlikeSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1682,10 +1607,9 @@ xmlUCSIsLetterlikeSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Limbu UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1694,10 +1618,9 @@ xmlUCSIsLimbu(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of LinearBIdeograms UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1706,10 +1629,9 @@ xmlUCSIsLinearBIdeograms(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of LinearBSyllabary UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1718,10 +1640,9 @@ xmlUCSIsLinearBSyllabary(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of LowSurrogates UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1730,10 +1651,9 @@ xmlUCSIsLowSurrogates(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Malayalam UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1742,10 +1662,9 @@ xmlUCSIsMalayalam(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of MathematicalAlphanumericSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1754,10 +1673,9 @@ xmlUCSIsMathematicalAlphanumericSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of MathematicalOperators UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1766,10 +1684,9 @@ xmlUCSIsMathematicalOperators(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of MiscellaneousMathematicalSymbols-A UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1778,10 +1695,9 @@ xmlUCSIsMiscellaneousMathematicalSymbolsA(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of MiscellaneousMathematicalSymbols-B UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1790,10 +1706,9 @@ xmlUCSIsMiscellaneousMathematicalSymbolsB(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of MiscellaneousSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1802,10 +1717,9 @@ xmlUCSIsMiscellaneousSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of MiscellaneousSymbolsandArrows UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1814,10 +1728,9 @@ xmlUCSIsMiscellaneousSymbolsandArrows(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of MiscellaneousTechnical UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1826,10 +1739,9 @@ xmlUCSIsMiscellaneousTechnical(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Mongolian UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1838,10 +1750,9 @@ xmlUCSIsMongolian(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of MusicalSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1850,10 +1761,9 @@ xmlUCSIsMusicalSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Myanmar UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1862,10 +1772,9 @@ xmlUCSIsMyanmar(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of NumberForms UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1874,10 +1783,9 @@ xmlUCSIsNumberForms(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Ogham UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1886,10 +1794,9 @@ xmlUCSIsOgham(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of OldItalic UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1898,10 +1805,9 @@ xmlUCSIsOldItalic(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of OpticalCharacterRecognition UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1910,10 +1816,9 @@ xmlUCSIsOpticalCharacterRecognition(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Oriya UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1922,10 +1827,9 @@ xmlUCSIsOriya(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Osmanya UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1934,10 +1838,9 @@ xmlUCSIsOsmanya(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of PhoneticExtensions UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1946,10 +1849,9 @@ xmlUCSIsPhoneticExtensions(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of PrivateUse UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1960,10 +1862,9 @@ xmlUCSIsPrivateUse(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of PrivateUseArea UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1972,10 +1873,9 @@ xmlUCSIsPrivateUseArea(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Runic UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1984,10 +1884,9 @@ xmlUCSIsRunic(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Shavian UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -1996,10 +1895,9 @@ xmlUCSIsShavian(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Sinhala UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2008,10 +1906,9 @@ xmlUCSIsSinhala(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of SmallFormVariants UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2020,10 +1917,9 @@ xmlUCSIsSmallFormVariants(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of SpacingModifierLetters UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2032,10 +1928,9 @@ xmlUCSIsSpacingModifierLetters(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Specials UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2044,10 +1939,9 @@ xmlUCSIsSpecials(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of SuperscriptsandSubscripts UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2056,10 +1950,9 @@ xmlUCSIsSuperscriptsandSubscripts(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of SupplementalArrows-A UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2068,10 +1961,9 @@ xmlUCSIsSupplementalArrowsA(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of SupplementalArrows-B UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2080,10 +1972,9 @@ xmlUCSIsSupplementalArrowsB(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of SupplementalMathematicalOperators UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2092,10 +1983,9 @@ xmlUCSIsSupplementalMathematicalOperators(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of SupplementaryPrivateUseArea-A UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2104,10 +1994,9 @@ xmlUCSIsSupplementaryPrivateUseAreaA(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of SupplementaryPrivateUseArea-B UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2116,10 +2005,9 @@ xmlUCSIsSupplementaryPrivateUseAreaB(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Syriac UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2128,10 +2016,9 @@ xmlUCSIsSyriac(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Tagalog UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2140,10 +2027,9 @@ xmlUCSIsTagalog(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Tagbanwa UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2152,10 +2038,9 @@ xmlUCSIsTagbanwa(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Tags UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2164,10 +2049,9 @@ xmlUCSIsTags(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of TaiLe UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2176,10 +2060,9 @@ xmlUCSIsTaiLe(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of TaiXuanJingSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2188,10 +2071,9 @@ xmlUCSIsTaiXuanJingSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Tamil UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2200,10 +2082,9 @@ xmlUCSIsTamil(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Telugu UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2212,10 +2093,9 @@ xmlUCSIsTelugu(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Thaana UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2224,10 +2104,9 @@ xmlUCSIsThaana(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Thai UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2236,10 +2115,9 @@ xmlUCSIsThai(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Tibetan UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2248,10 +2126,9 @@ xmlUCSIsTibetan(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Ugaritic UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2260,10 +2137,9 @@ xmlUCSIsUgaritic(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of UnifiedCanadianAboriginalSyllabics UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2272,10 +2148,9 @@ xmlUCSIsUnifiedCanadianAboriginalSyllabics(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of VariationSelectors UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2284,10 +2159,9 @@ xmlUCSIsVariationSelectors(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of VariationSelectorsSupplement UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2296,10 +2170,9 @@ xmlUCSIsVariationSelectorsSupplement(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of YiRadicals UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2308,10 +2181,9 @@ xmlUCSIsYiRadicals(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of YiSyllables UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2320,10 +2192,9 @@ xmlUCSIsYiSyllables(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of YijingHexagramSymbols UCS Block * + * @param code UCS code point * @returns 1 if true 0 otherwise */ static int @@ -2332,10 +2203,9 @@ xmlUCSIsYijingHexagramSymbols(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of C UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2344,10 +2214,9 @@ xmlUCSIsCatC(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Cc UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2357,10 +2226,9 @@ xmlUCSIsCatCc(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Cf UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2369,10 +2237,9 @@ xmlUCSIsCatCf(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Co UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2386,10 +2253,9 @@ xmlUCSIsCatCo(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Cs UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2401,10 +2267,9 @@ xmlUCSIsCatCs(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of L UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2413,10 +2278,9 @@ xmlUCSIsCatL(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Ll UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2425,10 +2289,9 @@ xmlUCSIsCatLl(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Lm UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2437,10 +2300,9 @@ xmlUCSIsCatLm(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Lo UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2449,10 +2311,9 @@ xmlUCSIsCatLo(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Lt UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2461,10 +2322,9 @@ xmlUCSIsCatLt(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Lu UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2473,10 +2333,9 @@ xmlUCSIsCatLu(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of M UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2485,10 +2344,9 @@ xmlUCSIsCatM(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Mc UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2497,10 +2355,9 @@ xmlUCSIsCatMc(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Me UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2512,10 +2369,9 @@ xmlUCSIsCatMe(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Mn UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2524,10 +2380,9 @@ xmlUCSIsCatMn(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of N UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2536,10 +2391,9 @@ xmlUCSIsCatN(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Nd UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2548,10 +2402,9 @@ xmlUCSIsCatNd(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Nl UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2565,10 +2418,9 @@ xmlUCSIsCatNl(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of No UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2577,10 +2429,9 @@ xmlUCSIsCatNo(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of P UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2589,10 +2440,9 @@ xmlUCSIsCatP(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Pc UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2608,10 +2458,9 @@ xmlUCSIsCatPc(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Pd UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2620,10 +2469,9 @@ xmlUCSIsCatPd(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Pe UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2632,10 +2480,9 @@ xmlUCSIsCatPe(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Pf UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2647,10 +2494,9 @@ xmlUCSIsCatPf(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Pi UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2663,10 +2509,9 @@ xmlUCSIsCatPi(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Po UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2675,10 +2520,9 @@ xmlUCSIsCatPo(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Ps UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2687,10 +2531,9 @@ xmlUCSIsCatPs(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of S UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2699,10 +2542,9 @@ xmlUCSIsCatS(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Sc UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2711,10 +2553,9 @@ xmlUCSIsCatSc(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Sk UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2723,10 +2564,9 @@ xmlUCSIsCatSk(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Sm UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2735,10 +2575,9 @@ xmlUCSIsCatSm(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of So UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2747,10 +2586,9 @@ xmlUCSIsCatSo(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Z UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2759,10 +2597,9 @@ xmlUCSIsCatZ(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Zl UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2771,10 +2608,9 @@ xmlUCSIsCatZl(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Zp UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2783,10 +2619,9 @@ xmlUCSIsCatZp(int code) { } /** - * @param code UCS code point - * * Check whether the character is part of Zs UCS Category * + * @param code UCS code point * @returns 1 if true 0 otherwise */ int @@ -2972,11 +2807,10 @@ static const xmlUnicodeNameTable xmlUnicodeBlockTbl = {xmlUnicodeBlocks, 128}; static const xmlUnicodeNameTable xmlUnicodeCatTbl = {xmlUnicodeCats, 36}; /** - * @param code UCS code point - * @param block UCS block name - * * Check whether the character is part of the UCS Block * + * @param code UCS code point + * @param block UCS block name * @returns 1 if true, 0 if false and -1 on unknown block */ int @@ -2990,11 +2824,10 @@ xmlUCSIsBlock(int code, const char *block) { } /** - * @param code UCS code point - * @param cat UCS Category name - * * Check whether the character is part of the UCS Category * + * @param code UCS code point + * @param cat UCS Category name * @returns 1 if true, 0 if false and -1 on unknown category */ int diff --git a/xmlwriter.c b/xmlwriter.c index 17e2c615..4939baa0 100644 --- a/xmlwriter.c +++ b/xmlwriter.c @@ -112,11 +112,11 @@ static int xmlTextWriterStackEntry * p); /** + * Handle a writer error + * * @param ctxt a writer context * @param error the error number * @param msg the error message - * - * Handle a writer error */ static void xmlWriterErrMsg(xmlTextWriterPtr ctxt, xmlParserErrors error, @@ -133,12 +133,12 @@ xmlWriterErrMsg(xmlTextWriterPtr ctxt, xmlParserErrors error, } /** + * Handle a writer error + * * @param ctxt a writer context * @param error the error number * @param msg the error message * @param val an int - * - * Handle a writer error */ static void LIBXML_ATTR_FORMAT(3,0) xmlWriterErrMsgInt(xmlTextWriterPtr ctxt, xmlParserErrors error, @@ -155,12 +155,11 @@ xmlWriterErrMsgInt(xmlTextWriterPtr ctxt, xmlParserErrors error, } /** - * @param out an xmlOutputBufferPtr - * * Create a new xmlTextWriter structure using an xmlOutputBufferPtr * NOTE: the `out` parameter will be deallocated when the writer is closed * (if the call succeed.) * + * @param out an xmlOutputBufferPtr * @returns the new xmlTextWriterPtr or NULL in case of error */ xmlTextWriterPtr @@ -216,11 +215,10 @@ xmlNewTextWriter(xmlOutputBufferPtr out) } /** - * @param uri the URI of the resource for the output - * @param compression compress the output? - * * Create a new xmlTextWriter structure with `uri` as output * + * @param uri the URI of the resource for the output + * @param compression compress the output? * @returns the new xmlTextWriterPtr or NULL in case of error */ xmlTextWriterPtr @@ -250,12 +248,11 @@ xmlNewTextWriterFilename(const char *uri, int compression) } /** - * @param buf xmlBufferPtr - * @param compression compress the output? - * * Create a new xmlTextWriter structure with `buf` as output * TODO: handle compression * + * @param buf xmlBufferPtr + * @param compression compress the output? * @returns the new xmlTextWriterPtr or NULL in case of error */ xmlTextWriterPtr @@ -285,14 +282,13 @@ xmlNewTextWriterMemory(xmlBufferPtr buf, int compression ATTRIBUTE_UNUSED) } /** - * @param ctxt xmlParserCtxtPtr to hold the new XML document tree - * @param compression compress the output? - * * Create a new xmlTextWriter structure with `ctxt` as output * NOTE: the `ctxt` context will be freed with the resulting writer * (if the call succeeds). * TODO: handle compression * + * @param ctxt xmlParserCtxtPtr to hold the new XML document tree + * @param compression compress the output? * @returns the new xmlTextWriterPtr or NULL in case of error */ xmlTextWriterPtr @@ -331,11 +327,10 @@ xmlNewTextWriterPushParser(xmlParserCtxtPtr ctxt, } /** - * @param doc address of a xmlDocPtr to hold the new XML document tree - * @param compression compress the output? - * * Create a new xmlTextWriter structure with @*doc as output * + * @param doc address of a xmlDocPtr to hold the new XML document tree + * @param compression compress the output? * @returns the new xmlTextWriterPtr or NULL in case of error */ xmlTextWriterPtr @@ -389,13 +384,12 @@ xmlNewTextWriterDoc(xmlDocPtr * doc, int compression) } /** - * @param doc xmlDocPtr - * @param node xmlNodePtr or NULL for doc->children - * @param compression compress the output? - * * Create a new xmlTextWriter structure with `doc` as output * starting at `node` * + * @param doc xmlDocPtr + * @param node xmlNodePtr or NULL for doc->children + * @param compression compress the output? * @returns the new xmlTextWriterPtr or NULL in case of error */ xmlTextWriterPtr @@ -445,9 +439,9 @@ xmlNewTextWriterTree(xmlDocPtr doc, xmlNodePtr node, int compression) } /** - * @param writer the xmlTextWriterPtr - * * Deallocate all the resources associated to the writer + * + * @param writer the xmlTextWriterPtr */ void xmlFreeTextWriter(xmlTextWriterPtr writer) @@ -481,13 +475,12 @@ xmlFreeTextWriter(xmlTextWriterPtr writer) } /** + * Start a new xml document + * * @param writer the xmlTextWriterPtr * @param version the xml version ("1.0") or NULL for default ("1.0") * @param encoding the encoding or NULL for default * @param standalone "yes" or "no" or NULL for default - * - * Start a new xml document - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -602,11 +595,10 @@ xmlTextWriterStartDocument(xmlTextWriterPtr writer, const char *version, } /** - * @param writer the xmlTextWriterPtr - * * End an xml document. All open elements are closed, and * the content is flushed to the output. * + * @param writer the xmlTextWriterPtr * @returns the bytes written or -1 in case of error */ int @@ -692,10 +684,9 @@ xmlTextWriterEndDocument(xmlTextWriterPtr writer) } /** - * @param writer the xmlTextWriterPtr - * * Start an xml comment. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -775,10 +766,9 @@ xmlTextWriterStartComment(xmlTextWriterPtr writer) } /** - * @param writer the xmlTextWriterPtr - * * End the current xml comment. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -830,12 +820,12 @@ xmlTextWriterEndComment(xmlTextWriterPtr writer) } /** - * @param writer the xmlTextWriterPtr - * @param format format string (see printf) - * @...: extra parameters for the format - * * Write an xml comment. * + * @...: extra parameters for the format + * + * @param writer the xmlTextWriterPtr + * @param format format string (see printf) * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -854,12 +844,11 @@ xmlTextWriterWriteFormatComment(xmlTextWriterPtr writer, } /** + * Write an xml comment. + * * @param writer the xmlTextWriterPtr * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write an xml comment. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -886,11 +875,10 @@ xmlTextWriterWriteVFormatComment(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * @param content comment string - * * Write an xml comment. * + * @param writer the xmlTextWriterPtr + * @param content comment string * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -917,11 +905,10 @@ xmlTextWriterWriteComment(xmlTextWriterPtr writer, const xmlChar * content) } /** - * @param writer the xmlTextWriterPtr - * @param name element name - * * Start an xml element. * + * @param writer the xmlTextWriterPtr + * @param name element name * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1011,13 +998,12 @@ xmlTextWriterStartElement(xmlTextWriterPtr writer, const xmlChar * name) } /** + * Start an xml element with namespace support. + * * @param writer the xmlTextWriterPtr * @param prefix namespace prefix or NULL * @param name element local name * @param namespaceURI namespace URI or NULL - * - * Start an xml element with namespace support. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1078,10 +1064,9 @@ xmlTextWriterStartElementNS(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * * End the current xml element. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1169,10 +1154,9 @@ xmlTextWriterEndElement(xmlTextWriterPtr writer) } /** - * @param writer the xmlTextWriterPtr - * * End the current xml element. Writes an end tag even if the element is empty * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1251,12 +1235,12 @@ xmlTextWriterFullEndElement(xmlTextWriterPtr writer) } /** - * @param writer the xmlTextWriterPtr - * @param format format string (see printf) - * @...: extra parameters for the format - * * Write a formatted raw xml text. * + * @...: extra parameters for the format + * + * @param writer the xmlTextWriterPtr + * @param format format string (see printf) * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1275,12 +1259,11 @@ xmlTextWriterWriteFormatRaw(xmlTextWriterPtr writer, const char *format, } /** + * Write a formatted raw xml text. + * * @param writer the xmlTextWriterPtr * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted raw xml text. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1304,13 +1287,12 @@ xmlTextWriterWriteVFormatRaw(xmlTextWriterPtr writer, const char *format, } /** - * @param writer the xmlTextWriterPtr - * @param content text string - * @param len length of the text string - * * Write an xml text. * TODO: what about entities and special chars?? * + * @param writer the xmlTextWriterPtr + * @param content text string + * @param len length of the text string * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1359,11 +1341,10 @@ xmlTextWriterWriteRawLen(xmlTextWriterPtr writer, const xmlChar * content, } /** - * @param writer the xmlTextWriterPtr - * @param content text string - * * Write a raw xml text. * + * @param writer the xmlTextWriterPtr + * @param content text string * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1373,12 +1354,12 @@ xmlTextWriterWriteRaw(xmlTextWriterPtr writer, const xmlChar * content) } /** - * @param writer the xmlTextWriterPtr - * @param format format string (see printf) - * @...: extra parameters for the format - * * Write a formatted xml text. * + * @...: extra parameters for the format + * + * @param writer the xmlTextWriterPtr + * @param format format string (see printf) * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1400,12 +1381,11 @@ xmlTextWriterWriteFormatString(xmlTextWriterPtr writer, const char *format, } /** + * Write a formatted xml text. + * * @param writer the xmlTextWriterPtr * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted xml text. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1429,11 +1409,10 @@ xmlTextWriterWriteVFormatString(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * @param content text string - * * Write an xml text. * + * @param writer the xmlTextWriterPtr + * @param content text string * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1488,13 +1467,12 @@ xmlTextWriterWriteString(xmlTextWriterPtr writer, const xmlChar * content) } /** - * @param out the xmlOutputBufferPtr - * @param data binary data - * @param len the number of bytes to encode - * * Write base64 encoded data to an xmlOutputBuffer. * Adapted from John Walker's base64.c (http://www.fourmilab.ch/). * + * @param out the xmlOutputBufferPtr + * @param data binary data + * @param len the number of bytes to encode * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ static int @@ -1569,13 +1547,12 @@ xmlOutputBufferWriteBase64(xmlOutputBufferPtr out, int len, } /** + * Write an base64 encoded xml text. + * * @param writer the xmlTextWriterPtr * @param data binary data * @param start the position within the data of the first byte to encode * @param len the number of bytes to encode - * - * Write an base64 encoded xml text. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1616,12 +1593,11 @@ xmlTextWriterWriteBase64(xmlTextWriterPtr writer, const char *data, } /** + * Write hqx encoded data to an xmlOutputBuffer. + * * @param out the xmlOutputBufferPtr * @param data binary data * @param len the number of bytes to encode - * - * Write hqx encoded data to an xmlOutputBuffer. - * * @returns the bytes written (may be 0 because of buffering) * or -1 in case of error */ @@ -1659,13 +1635,12 @@ xmlOutputBufferWriteBinHex(xmlOutputBufferPtr out, } /** + * Write a BinHex encoded xml text. + * * @param writer the xmlTextWriterPtr * @param data binary data * @param start the position within the data of the first byte to encode * @param len the number of bytes to encode - * - * Write a BinHex encoded xml text. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1706,11 +1681,10 @@ xmlTextWriterWriteBinHex(xmlTextWriterPtr writer, const char *data, } /** - * @param writer the xmlTextWriterPtr - * @param name element name - * * Start an xml attribute. * + * @param writer the xmlTextWriterPtr + * @param name element name * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1769,13 +1743,12 @@ xmlTextWriterStartAttribute(xmlTextWriterPtr writer, const xmlChar * name) } /** + * Start an xml attribute with namespace support. + * * @param writer the xmlTextWriterPtr * @param prefix namespace prefix or NULL * @param name element local name * @param namespaceURI namespace URI or NULL - * - * Start an xml attribute with namespace support. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1860,10 +1833,9 @@ xmlTextWriterStartAttributeNS(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * * End the current xml element. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1906,13 +1878,13 @@ xmlTextWriterEndAttribute(xmlTextWriterPtr writer) } /** + * Write a formatted xml attribute. + * + * @...: extra parameters for the format + * * @param writer the xmlTextWriterPtr * @param name attribute name * @param format format string (see printf) - * @...: extra parameters for the format - * - * Write a formatted xml attribute. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1932,13 +1904,12 @@ xmlTextWriterWriteFormatAttribute(xmlTextWriterPtr writer, } /** + * Write a formatted xml attribute. + * * @param writer the xmlTextWriterPtr * @param name attribute name * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted xml attribute. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1963,12 +1934,11 @@ xmlTextWriterWriteVFormatAttribute(xmlTextWriterPtr writer, } /** + * Write an xml attribute. + * * @param writer the xmlTextWriterPtr * @param name attribute name * @param content attribute content - * - * Write an xml attribute. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -1996,15 +1966,15 @@ xmlTextWriterWriteAttribute(xmlTextWriterPtr writer, const xmlChar * name, } /** + * Write a formatted xml attribute.with namespace support + * + * @...: extra parameters for the format + * * @param writer the xmlTextWriterPtr * @param prefix namespace prefix * @param name attribute local name * @param namespaceURI namespace URI * @param format format string (see printf) - * @...: extra parameters for the format - * - * Write a formatted xml attribute.with namespace support - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2027,15 +1997,14 @@ xmlTextWriterWriteFormatAttributeNS(xmlTextWriterPtr writer, } /** + * Write a formatted xml attribute.with namespace support + * * @param writer the xmlTextWriterPtr * @param prefix namespace prefix * @param name attribute local name * @param namespaceURI namespace URI * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted xml attribute.with namespace support - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2063,14 +2032,13 @@ xmlTextWriterWriteVFormatAttributeNS(xmlTextWriterPtr writer, } /** + * Write an xml attribute. + * * @param writer the xmlTextWriterPtr * @param prefix namespace prefix * @param name attribute local name * @param namespaceURI namespace URI * @param content attribute content - * - * Write an xml attribute. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2103,13 +2071,13 @@ xmlTextWriterWriteAttributeNS(xmlTextWriterPtr writer, } /** + * Write a formatted xml element. + * + * @...: extra parameters for the format + * * @param writer the xmlTextWriterPtr * @param name element name * @param format format string (see printf) - * @...: extra parameters for the format - * - * Write a formatted xml element. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2129,13 +2097,12 @@ xmlTextWriterWriteFormatElement(xmlTextWriterPtr writer, } /** + * Write a formatted xml element. + * * @param writer the xmlTextWriterPtr * @param name element name * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted xml element. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2160,12 +2127,11 @@ xmlTextWriterWriteVFormatElement(xmlTextWriterPtr writer, } /** + * Write an xml element. + * * @param writer the xmlTextWriterPtr * @param name element name * @param content element content - * - * Write an xml element. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2195,15 +2161,15 @@ xmlTextWriterWriteElement(xmlTextWriterPtr writer, const xmlChar * name, } /** + * Write a formatted xml element with namespace support. + * + * @...: extra parameters for the format + * * @param writer the xmlTextWriterPtr * @param prefix namespace prefix * @param name element local name * @param namespaceURI namespace URI * @param format format string (see printf) - * @...: extra parameters for the format - * - * Write a formatted xml element with namespace support. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2226,15 +2192,14 @@ xmlTextWriterWriteFormatElementNS(xmlTextWriterPtr writer, } /** + * Write a formatted xml element with namespace support. + * * @param writer the xmlTextWriterPtr * @param prefix namespace prefix * @param name element local name * @param namespaceURI namespace URI * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted xml element with namespace support. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2262,14 +2227,13 @@ xmlTextWriterWriteVFormatElementNS(xmlTextWriterPtr writer, } /** + * Write an xml element with namespace support. + * * @param writer the xmlTextWriterPtr * @param prefix namespace prefix * @param name element local name * @param namespaceURI namespace URI * @param content element content - * - * Write an xml element with namespace support. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2303,11 +2267,10 @@ xmlTextWriterWriteElementNS(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * @param target PI target - * * Start an xml PI. * + * @param writer the xmlTextWriterPtr + * @param target PI target * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2399,10 +2362,9 @@ xmlTextWriterStartPI(xmlTextWriterPtr writer, const xmlChar * target) } /** - * @param writer the xmlTextWriterPtr - * * End the current xml PI. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2449,13 +2411,13 @@ xmlTextWriterEndPI(xmlTextWriterPtr writer) } /** + * Write a formatted PI. + * + * @...: extra parameters for the format + * * @param writer the xmlTextWriterPtr * @param target PI target * @param format format string (see printf) - * @...: extra parameters for the format - * - * Write a formatted PI. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2474,13 +2436,12 @@ xmlTextWriterWriteFormatPI(xmlTextWriterPtr writer, const xmlChar * target, } /** + * Write a formatted xml PI. + * * @param writer the xmlTextWriterPtr * @param target PI target * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted xml PI. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2505,12 +2466,11 @@ xmlTextWriterWriteVFormatPI(xmlTextWriterPtr writer, } /** + * Write an xml PI. + * * @param writer the xmlTextWriterPtr * @param target PI target * @param content PI content - * - * Write an xml PI. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2540,10 +2500,9 @@ xmlTextWriterWritePI(xmlTextWriterPtr writer, const xmlChar * target, } /** - * @param writer the xmlTextWriterPtr - * * Start an xml CDATA section. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2618,10 +2577,9 @@ xmlTextWriterStartCDATA(xmlTextWriterPtr writer) } /** - * @param writer the xmlTextWriterPtr - * * End an xml CDATA section. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2660,12 +2618,12 @@ xmlTextWriterEndCDATA(xmlTextWriterPtr writer) } /** - * @param writer the xmlTextWriterPtr - * @param format format string (see printf) - * @...: extra parameters for the format - * * Write a formatted xml CDATA. * + * @...: extra parameters for the format + * + * @param writer the xmlTextWriterPtr + * @param format format string (see printf) * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2684,12 +2642,11 @@ xmlTextWriterWriteFormatCDATA(xmlTextWriterPtr writer, const char *format, } /** + * Write a formatted xml CDATA. + * * @param writer the xmlTextWriterPtr * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted xml CDATA. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2713,11 +2670,10 @@ xmlTextWriterWriteVFormatCDATA(xmlTextWriterPtr writer, const char *format, } /** - * @param writer the xmlTextWriterPtr - * @param content CDATA content - * * Write an xml CDATA. * + * @param writer the xmlTextWriterPtr + * @param content CDATA content * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2746,13 +2702,12 @@ xmlTextWriterWriteCDATA(xmlTextWriterPtr writer, const xmlChar * content) } /** + * Start an xml DTD. + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD * @param pubid the public identifier, which is an alternative to the system identifier * @param sysid the system identifier, which is the URI of the DTD - * - * Start an xml DTD. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2885,10 +2840,9 @@ xmlTextWriterStartDTD(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * * End an xml DTD. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2961,15 +2915,15 @@ xmlTextWriterEndDTD(xmlTextWriterPtr writer) } /** + * Write a DTD with a formatted markup declarations part. + * + * @...: extra parameters for the format + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD * @param pubid the public identifier, which is an alternative to the system identifier * @param sysid the system identifier, which is the URI of the DTD * @param format format string (see printf) - * @...: extra parameters for the format - * - * Write a DTD with a formatted markup declarations part. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -2991,15 +2945,14 @@ xmlTextWriterWriteFormatDTD(xmlTextWriterPtr writer, } /** + * Write a DTD with a formatted markup declarations part. + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD * @param pubid the public identifier, which is an alternative to the system identifier * @param sysid the system identifier, which is the URI of the DTD * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a DTD with a formatted markup declarations part. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3026,14 +2979,13 @@ xmlTextWriterWriteVFormatDTD(xmlTextWriterPtr writer, } /** + * Write a DTD. + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD * @param pubid the public identifier, which is an alternative to the system identifier * @param sysid the system identifier, which is the URI of the DTD * @param subset string content of the DTD - * - * Write a DTD. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3065,11 +3017,10 @@ xmlTextWriterWriteDTD(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * @param name the name of the DTD element - * * Start an xml DTD element. * + * @param writer the xmlTextWriterPtr + * @param name the name of the DTD element * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3152,10 +3103,9 @@ xmlTextWriterStartDTDElement(xmlTextWriterPtr writer, const xmlChar * name) } /** - * @param writer the xmlTextWriterPtr - * * End an xml DTD element. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3202,13 +3152,13 @@ xmlTextWriterEndDTDElement(xmlTextWriterPtr writer) } /** + * Write a formatted DTD element. + * + * @...: extra parameters for the format + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD element * @param format format string (see printf) - * @...: extra parameters for the format - * - * Write a formatted DTD element. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3228,13 +3178,12 @@ xmlTextWriterWriteFormatDTDElement(xmlTextWriterPtr writer, } /** + * Write a formatted DTD element. + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD element * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted DTD element. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3259,12 +3208,11 @@ xmlTextWriterWriteVFormatDTDElement(xmlTextWriterPtr writer, } /** + * Write a DTD element. + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD element * @param content content of the element - * - * Write a DTD element. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3297,11 +3245,10 @@ xmlTextWriterWriteDTDElement(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * @param name the name of the DTD ATTLIST - * * Start an xml DTD ATTLIST. * + * @param writer the xmlTextWriterPtr + * @param name the name of the DTD ATTLIST * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3384,10 +3331,9 @@ xmlTextWriterStartDTDAttlist(xmlTextWriterPtr writer, const xmlChar * name) } /** - * @param writer the xmlTextWriterPtr - * * End an xml DTD attribute list. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3434,13 +3380,13 @@ xmlTextWriterEndDTDAttlist(xmlTextWriterPtr writer) } /** + * Write a formatted DTD ATTLIST. + * + * @...: extra parameters for the format + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD ATTLIST * @param format format string (see printf) - * @...: extra parameters for the format - * - * Write a formatted DTD ATTLIST. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3460,13 +3406,12 @@ xmlTextWriterWriteFormatDTDAttlist(xmlTextWriterPtr writer, } /** + * Write a formatted DTD ATTLIST. + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD ATTLIST * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted DTD ATTLIST. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3491,12 +3436,11 @@ xmlTextWriterWriteVFormatDTDAttlist(xmlTextWriterPtr writer, } /** + * Write a DTD ATTLIST. + * * @param writer the xmlTextWriterPtr * @param name the name of the DTD ATTLIST * @param content content of the ATTLIST - * - * Write a DTD ATTLIST. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3529,12 +3473,11 @@ xmlTextWriterWriteDTDAttlist(xmlTextWriterPtr writer, } /** + * Start an xml DTD ATTLIST. + * * @param writer the xmlTextWriterPtr * @param pe TRUE if this is a parameter entity, FALSE if not * @param name the name of the DTD ATTLIST - * - * Start an xml DTD ATTLIST. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3630,10 +3573,9 @@ xmlTextWriterStartDTDEntity(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * * End an xml DTD entity. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3686,14 +3628,14 @@ xmlTextWriterEndDTDEntity(xmlTextWriterPtr writer) } /** + * Write a formatted DTD internal entity. + * + * @...: extra parameters for the format + * * @param writer the xmlTextWriterPtr * @param pe TRUE if this is a parameter entity, FALSE if not * @param name the name of the DTD entity * @param format format string (see printf) - * @...: extra parameters for the format - * - * Write a formatted DTD internal entity. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3715,14 +3657,13 @@ xmlTextWriterWriteFormatDTDInternalEntity(xmlTextWriterPtr writer, } /** + * Write a formatted DTD internal entity. + * * @param writer the xmlTextWriterPtr * @param pe TRUE if this is a parameter entity, FALSE if not * @param name the name of the DTD entity * @param format format string (see printf) * @param argptr pointer to the first member of the variable argument list. - * - * Write a formatted DTD internal entity. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3749,6 +3690,8 @@ xmlTextWriterWriteVFormatDTDInternalEntity(xmlTextWriterPtr writer, } /** + * Write a DTD entity. + * * @param writer the xmlTextWriterPtr * @param pe TRUE if this is a parameter entity, FALSE if not * @param name the name of the DTD entity @@ -3756,9 +3699,6 @@ xmlTextWriterWriteVFormatDTDInternalEntity(xmlTextWriterPtr writer, * @param sysid the system identifier, which is the URI of the DTD * @param ndataid the xml notation name. * @param content content of the entity - * - * Write a DTD entity. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3784,13 +3724,12 @@ xmlTextWriterWriteDTDEntity(xmlTextWriterPtr writer, } /** + * Write a DTD internal entity. + * * @param writer the xmlTextWriterPtr * @param pe TRUE if this is a parameter entity, FALSE if not * @param name the name of the DTD entity * @param content content of the entity - * - * Write a DTD internal entity. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3825,15 +3764,14 @@ xmlTextWriterWriteDTDInternalEntity(xmlTextWriterPtr writer, } /** + * Write a DTD external entity. The entity must have been started with xmlTextWriterStartDTDEntity() + * * @param writer the xmlTextWriterPtr * @param pe TRUE if this is a parameter entity, FALSE if not * @param name the name of the DTD entity * @param pubid the public identifier, which is an alternative to the system identifier * @param sysid the system identifier, which is the URI of the DTD * @param ndataid the xml notation name. - * - * Write a DTD external entity. The entity must have been started with xmlTextWriterStartDTDEntity() - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -3874,13 +3812,12 @@ xmlTextWriterWriteDTDExternalEntity(xmlTextWriterPtr writer, } /** + * Write the contents of a DTD external entity. + * * @param writer the xmlTextWriterPtr * @param pubid the public identifier, which is an alternative to the system identifier * @param sysid the system identifier, which is the URI of the DTD * @param ndataid the xml notation name. - * - * Write the contents of a DTD external entity. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -4005,13 +3942,12 @@ xmlTextWriterWriteDTDExternalEntityContents(xmlTextWriterPtr writer, } /** + * Write a DTD entity. + * * @param writer the xmlTextWriterPtr * @param name the name of the xml notation * @param pubid the public identifier, which is an alternative to the system identifier * @param sysid the system identifier, which is the URI of the DTD - * - * Write a DTD entity. - * * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -4127,10 +4063,9 @@ xmlTextWriterWriteDTDNotation(xmlTextWriterPtr writer, } /** - * @param writer the xmlTextWriterPtr - * * Flush the output buffer. * + * @param writer the xmlTextWriterPtr * @returns the bytes written (may be 0 because of buffering) or -1 in case of error */ int @@ -4150,12 +4085,11 @@ xmlTextWriterFlush(xmlTextWriterPtr writer) } /** - * @param writer the xmlTextWriterPtr - * * Flushes and closes the output buffer. * * @since 2.13.0 * + * @param writer the xmlTextWriterPtr * @returns an xmlParserErrors code. */ int @@ -4182,9 +4116,9 @@ xmlTextWriterClose(xmlTextWriterPtr writer) */ /** - * @param lk the xmlLinkPtr - * * Free callback for the xmlList. + * + * @param lk the xmlLinkPtr */ static void xmlFreeTextWriterStackEntry(xmlLinkPtr lk) @@ -4201,11 +4135,10 @@ xmlFreeTextWriterStackEntry(xmlLinkPtr lk) } /** - * @param data0 the first data - * @param data1 the second data - * * Compare callback for the xmlList. * + * @param data0 the first data + * @param data1 the second data * @returns -1, 0, 1 */ static int @@ -4234,9 +4167,9 @@ xmlCmpTextWriterStackEntry(const void *data0, const void *data1) */ /** - * @param writer the xmlTextWriterPtr - * * Output the current namespace declarations. + * + * @param writer the xmlTextWriterPtr */ static int xmlTextWriterOutputNSDecl(xmlTextWriterPtr writer) @@ -4278,9 +4211,9 @@ xmlTextWriterOutputNSDecl(xmlTextWriterPtr writer) } /** - * @param lk the xmlLinkPtr - * * Free callback for the xmlList. + * + * @param lk the xmlLinkPtr */ static void xmlFreeTextWriterNsStackEntry(xmlLinkPtr lk) @@ -4300,11 +4233,10 @@ xmlFreeTextWriterNsStackEntry(xmlLinkPtr lk) } /** - * @param data0 the first data - * @param data1 the second data - * * Compare callback for the xmlList. * + * @param data0 the first data + * @param data1 the second data * @returns -1, 0, 1 */ static int @@ -4335,12 +4267,11 @@ xmlCmpTextWriterNsStackEntry(const void *data0, const void *data1) } /** + * Write callback for the xmlOutputBuffer with target xmlBuffer + * * @param context the xmlBufferPtr * @param str the data to write * @param len the length of the data - * - * Write callback for the xmlOutputBuffer with target xmlBuffer - * * @returns -1, 0, 1 */ static int @@ -4361,10 +4292,9 @@ xmlTextWriterWriteDocCallback(void *context, const char *str, int len) } /** - * @param context the xmlBufferPtr - * * Close callback for the xmlOutputBuffer with target xmlBuffer * + * @param context the xmlBufferPtr * @returns -1, 0, 1 */ static int @@ -4385,11 +4315,10 @@ xmlTextWriterCloseDocCallback(void *context) } /** - * @param format see printf - * @param argptr pointer to the first member of the variable argument list. - * * Utility function for formatted output * + * @param format see printf + * @param argptr pointer to the first member of the variable argument list. * @returns a new xmlChar buffer with the data or NULL on error. This buffer must be freed. */ static xmlChar * @@ -4428,9 +4357,9 @@ xmlTextWriterVSprintf(const char *format, va_list argptr) } /** - * @param ctx the user data (XML parser context) - * * called at the start of document processing. + * + * @param ctx the user data (XML parser context) */ static void xmlTextWriterStartDocumentCallback(void *ctx) @@ -4476,11 +4405,10 @@ xmlTextWriterStartDocumentCallback(void *ctx) } /** - * @param writer the xmlTextWriterPtr - * @param indent do indentation? - * * Set indentation output. indent = 0 do not indentation. indent > 0 do indentation. * + * @param writer the xmlTextWriterPtr + * @param indent do indentation? * @returns -1 on error or 0 otherwise. */ int @@ -4496,11 +4424,10 @@ xmlTextWriterSetIndent(xmlTextWriterPtr writer, int indent) } /** - * @param writer the xmlTextWriterPtr - * @param str the xmlChar string - * * Set string indentation. * + * @param writer the xmlTextWriterPtr + * @param str the xmlChar string * @returns -1 on error or 0 otherwise. */ int @@ -4520,11 +4447,10 @@ xmlTextWriterSetIndentString(xmlTextWriterPtr writer, const xmlChar * str) } /** - * @param writer the xmlTextWriterPtr - * @param quotechar the quote character - * * Set the character used for quoting attributes. * + * @param writer the xmlTextWriterPtr + * @param quotechar the quote character * @returns -1 on error or 0 otherwise. */ int @@ -4539,10 +4465,9 @@ xmlTextWriterSetQuoteChar(xmlTextWriterPtr writer, xmlChar quotechar) } /** - * @param writer the xmlTextWriterPtr - * * Write indent string. * + * @param writer the xmlTextWriterPtr * @returns -1 on error or the number of strings written. */ static int @@ -4566,11 +4491,10 @@ xmlTextWriterWriteIndent(xmlTextWriterPtr writer) } /** - * @param writer the xmlTextWriterPtr - * @param p the xmlTextWriterStackEntry - * * Write state dependent strings. * + * @param writer the xmlTextWriterPtr + * @param p the xmlTextWriterStackEntry * @returns -1 on error or the number of characters written. */ static int diff --git a/xpath.c b/xpath.c index 9f2a64da..c42f3f3e 100644 --- a/xpath.c +++ b/xpath.c @@ -240,10 +240,9 @@ xmlInitXPathInternal(void) { ************************************************************************/ /** - * @param val a double value - * * Checks whether a double is a NaN. * + * @param val a double value * @returns 1 if the value is a NaN, 0 otherwise */ int @@ -256,10 +255,9 @@ xmlXPathIsNaN(double val) { } /** - * @param val a double value - * * Checks whether a double is an infinity. * + * @param val a double value * @returns 1 if the value is +Infinite, -1 if -Infinite, 0 otherwise */ int @@ -298,12 +296,11 @@ xmlXPathNodeSetClear(xmlNodeSetPtr set, int hasNsNodes); #ifdef XP_OPTIMIZED_NON_ELEM_COMPARISON /** - * @param node1 the first node - * @param node2 the second node - * * Compare two nodes w.r.t document order. * This one is optimized for handling of non-element nodes. * + * @param node1 the first node + * @param node2 the second node * @returns -2 in case of error 1 if first point < second point, 0 if * it's the same node, -1 otherwise */ @@ -594,11 +591,10 @@ turtle_comparison: #define SORT_NAME libxml_domnode #define SORT_TYPE xmlNodePtr /** - * @param x a node - * @param y another node - * * Comparison function for the Timsort implementation * + * @param x a node + * @param y another node * @returns -2 in case of error -1 if first point < second point, 0 if * it's the same node, +1 otherwise */ @@ -628,9 +624,9 @@ int wrap_cmp( xmlNodePtr x, xmlNodePtr y ); ************************************************************************/ /** - * @param X the error code - * * Macro to raise an XPath error and return NULL. + * + * @param X the error code */ #define XP_ERRORNULL(X) \ { xmlXPathErr(ctxt, X); return(NULL); } @@ -671,9 +667,9 @@ static const char* const xmlXPathErrorMessages[] = { #define MAXERRNO ((int)(sizeof(xmlXPathErrorMessages) / \ sizeof(xmlXPathErrorMessages[0])) - 1) /** - * @param ctxt an XPath context - * * Handle a memory allocation failure. + * + * @param ctxt an XPath context */ void xmlXPathErrMemory(xmlXPathContextPtr ctxt) @@ -685,9 +681,9 @@ xmlXPathErrMemory(xmlXPathContextPtr ctxt) } /** - * @param ctxt an XPath parser context - * * Handle a memory allocation failure. + * + * @param ctxt an XPath parser context */ void xmlXPathPErrMemory(xmlXPathParserContextPtr ctxt) @@ -699,10 +695,10 @@ xmlXPathPErrMemory(xmlXPathParserContextPtr ctxt) } /** + * Handle an XPath error + * * @param ctxt a XPath parser context * @param code the error code - * - * Handle an XPath error */ void xmlXPathErr(xmlXPathParserContextPtr ctxt, int code) @@ -767,12 +763,12 @@ xmlXPathErr(xmlXPathParserContextPtr ctxt, int code) } /** + * Formats an error message. + * * @param ctxt the XPath Parser context * @param file the file name * @param line the line number * @param no the error number - * - * Formats an error message. */ void xmlXPatherror(xmlXPathParserContextPtr ctxt, const char *file ATTRIBUTE_UNUSED, @@ -781,11 +777,11 @@ xmlXPatherror(xmlXPathParserContextPtr ctxt, const char *file ATTRIBUTE_UNUSED, } /** - * @param ctxt the XPath Parser context - * @param opCount the number of operations to be added - * * Adds opCount to the running total of operations and returns -1 if the * operation limit is exceeded. Returns 0 otherwise. + * + * @param ctxt the XPath Parser context + * @param opCount the number of operations to be added */ static int xmlXPathCheckOpLimit(xmlXPathParserContextPtr ctxt, unsigned long opCount) { @@ -950,9 +946,9 @@ xmlXPathNewCompExpr(void) { } /** - * @param comp an XPATH comp - * * Free up the memory allocated by `comp` + * + * @param comp an XPATH comp */ void xmlXPathFreeCompExpr(xmlXPathCompExprPtr comp) @@ -1000,6 +996,8 @@ xmlXPathFreeCompExpr(xmlXPathCompExprPtr comp) } /** + * Add a step to an XPath Compiled Expression + * * @param ctxt XPath parser context * @param ch1 first child index * @param ch2 second child index @@ -1009,9 +1007,6 @@ xmlXPathFreeCompExpr(xmlXPathCompExprPtr comp) * @param value3 the third int value * @param value4 the first string value * @param value5 the second string value - * - * Add a step to an XPath Compiled Expression - * * @returns -1 in case of failure, the index otherwise */ static int @@ -1205,11 +1200,11 @@ xmlXPathDebugDumpValueTree(FILE *output, xmlNodeSetPtr cur, int depth) { } /** + * Dump the content of the object for debugging purposes + * * @param output the FILE * to dump the output * @param cur the object to inspect * @param depth indentation level - * - * Dump the content of the object for debugging purposes */ void xmlXPathDebugDumpObject(FILE *output, xmlXPathObjectPtr cur, int depth) { @@ -1453,11 +1448,11 @@ finish: } /** + * Dumps the tree of the compiled XPath expression. + * * @param output the FILE * for the output * @param comp the precompiled XPath expression * @param depth the indentation level. - * - * Dumps the tree of the compiled XPath expression. */ void xmlXPathDebugDumpCompExpr(FILE *output, xmlXPathCompExprPtr comp, @@ -1545,11 +1540,6 @@ xmlXPathFreeCache(xmlXPathContextCachePtr cache) } /** - * @param ctxt the XPath context - * @param active enables/disables (creates/frees) the cache - * @param value a value with semantics dependent on `options` - * @param options options (currently only the value 0 is used) - * * Creates/frees an object cache on the XPath context. * If activates XPath objects (xmlXPathObject) will be cached internally * to be reused. @@ -1561,6 +1551,10 @@ xmlXPathFreeCache(xmlXPathContextCachePtr cache) * There are two slots for node-set and misc objects. * Use <0 for the default number (100). * + * @param ctxt the XPath context + * @param active enables/disables (creates/frees) the cache + * @param value a value with semantics dependent on `options` + * @param options options (currently only the value 0 is used) * @returns 0 if the setting succeeded, and -1 on API or internal errors. */ int @@ -1596,15 +1590,13 @@ xmlXPathContextSetCache(xmlXPathContextPtr ctxt, } /** - * @param pctxt the XPath context - * @param val the NodePtr value - * * This is the cached version of xmlXPathWrapNodeSet(). * Wrap the Nodeset `val` in a new xmlXPathObjectPtr * - * @returns the created or reused object. - * * In case of error the node set is destroyed and NULL is returned. + * @param pctxt the XPath context + * @param val the NodePtr value + * @returns the created or reused object. */ static xmlXPathObjectPtr xmlXPathCacheWrapNodeSet(xmlXPathParserContextPtr pctxt, xmlNodeSetPtr val) @@ -1634,12 +1626,11 @@ xmlXPathCacheWrapNodeSet(xmlXPathParserContextPtr pctxt, xmlNodeSetPtr val) } /** - * @param pctxt the XPath context - * @param val the xmlChar * value - * * This is the cached version of xmlXPathWrapString(). * Wraps the `val` string into an XPath object. * + * @param pctxt the XPath context + * @param val the xmlChar * value * @returns the created or reused object. */ static xmlXPathObjectPtr @@ -1668,13 +1659,12 @@ xmlXPathCacheWrapString(xmlXPathParserContextPtr pctxt, xmlChar *val) } /** - * @param pctxt the XPath context - * @param val the NodePtr value - * * This is the cached version of xmlXPathNewNodeSet(). * Acquire an xmlXPathObjectPtr of type NodeSet and initialize * it with the single Node `val` * + * @param pctxt the XPath context + * @param val the NodePtr value * @returns the created or reused object. */ static xmlXPathObjectPtr @@ -1737,12 +1727,11 @@ xmlXPathCacheNewNodeSet(xmlXPathParserContextPtr pctxt, xmlNodePtr val) } /** - * @param pctxt the XPath context - * @param val the xmlChar * value - * * This is the cached version of xmlXPathNewString(). * Acquire an xmlXPathObjectPtr of type string and of value `val` * + * @param pctxt the XPath context + * @param val the xmlChar * value * @returns the created or reused object. */ static xmlXPathObjectPtr @@ -1781,12 +1770,11 @@ xmlXPathCacheNewString(xmlXPathParserContextPtr pctxt, const xmlChar *val) } /** - * @param pctxt the XPath context - * @param val the char * value - * * This is the cached version of xmlXPathNewCString(). * Acquire an xmlXPathObjectPtr of type string and of value `val` * + * @param pctxt the XPath context + * @param val the char * value * @returns the created or reused object. */ static xmlXPathObjectPtr @@ -1796,12 +1784,11 @@ xmlXPathCacheNewCString(xmlXPathParserContextPtr pctxt, const char *val) } /** - * @param pctxt the XPath context - * @param val the boolean value - * * This is the cached version of xmlXPathNewBoolean(). * Acquires an xmlXPathObjectPtr of type boolean and of value `val` * + * @param pctxt the XPath context + * @param val the boolean value * @returns the created or reused object. */ static xmlXPathObjectPtr @@ -1831,12 +1818,11 @@ xmlXPathCacheNewBoolean(xmlXPathParserContextPtr pctxt, int val) } /** - * @param pctxt the XPath context - * @param val the double value - * * This is the cached version of xmlXPathNewFloat(). * Acquires an xmlXPathObjectPtr of type double and of value `val` * + * @param pctxt the XPath context + * @param val the double value * @returns the created or reused object. */ static xmlXPathObjectPtr @@ -1866,12 +1852,11 @@ xmlXPathCacheNewFloat(xmlXPathParserContextPtr pctxt, double val) } /** - * @param pctxt the XPath context - * @param val the original object - * * This is the cached version of xmlXPathObjectCopy(). * Acquire a copy of a given object * + * @param pctxt the XPath context + * @param val the original object * @returns a created or reused created object. */ static xmlXPathObjectPtr @@ -1918,11 +1903,10 @@ xmlXPathCacheObjectCopy(xmlXPathParserContextPtr pctxt, xmlXPathObjectPtr val) ************************************************************************/ /** - * @param ctxt parser context - * @param val an XPath object - * * Converts an XPath object to its number value * + * @param ctxt parser context + * @param val an XPath object * @returns the number value */ static double @@ -1968,10 +1952,9 @@ xmlXPathCastToNumberInternal(xmlXPathParserContextPtr ctxt, } /** - * @param ctxt an XPath evaluation context - * * Pops the top XPath object from the value stack * + * @param ctxt an XPath evaluation context * @returns the XPath object just removed */ xmlXPathObjectPtr @@ -1993,15 +1976,13 @@ xmlXPathValuePop(xmlXPathParserContextPtr ctxt) } /** - * @param ctxt an XPath evaluation context - * @param value the XPath object - * * Pushes a new XPath object on top of the value stack. If value is NULL, * a memory error is recorded in the parser context. * - * @returns the number of items on the value stack, or -1 in case of error. - * * The object is destroyed in case of error. + * @param ctxt an XPath evaluation context + * @param value the XPath object + * @returns the number of items on the value stack, or -1 in case of error. */ int xmlXPathValuePush(xmlXPathParserContextPtr ctxt, xmlXPathObjectPtr value) @@ -2040,11 +2021,10 @@ xmlXPathValuePush(xmlXPathParserContextPtr ctxt, xmlXPathObjectPtr value) } /** - * @param ctxt an XPath parser context - * * Pops a boolean from the stack, handling conversion if needed. * Check error with xmlXPathCheckError. * + * @param ctxt an XPath parser context * @returns the boolean */ int @@ -2066,11 +2046,10 @@ xmlXPathPopBoolean (xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt an XPath parser context - * * Pops a number from the stack, handling conversion if needed. * Check error with xmlXPathCheckError. * + * @param ctxt an XPath parser context * @returns the number */ double @@ -2092,11 +2071,10 @@ xmlXPathPopNumber (xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt an XPath parser context - * * Pops a string from the stack, handling conversion if needed. * Check error with xmlXPathCheckError. * + * @param ctxt an XPath parser context * @returns the string */ xmlChar * @@ -2117,11 +2095,10 @@ xmlXPathPopString (xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt an XPath parser context - * * Pops a node-set from the stack, handling conversion if needed. * Check error with xmlXPathCheckError. * + * @param ctxt an XPath parser context * @returns the node-set */ xmlNodeSetPtr @@ -2146,11 +2123,10 @@ xmlXPathPopNodeSet (xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt an XPath parser context - * * Pops an external object from the stack, handling conversion if needed. * Check error with xmlXPathCheckError. * + * @param ctxt an XPath parser context * @returns the object */ void * @@ -2231,11 +2207,11 @@ xmlXPathPopExternal (xmlXPathParserContextPtr ctxt) { #define EXPONENT_DIGITS (3 + 2) /** + * Convert the number into a string representation. + * * @param number number to format * @param buffer output buffer * @param buffersize size of output buffer - * - * Convert the number into a string representation. */ static void xmlXPathFormatNumber(double number, char buffer[], int buffersize) @@ -2363,14 +2339,13 @@ xmlXPathFormatNumber(double number, char buffer[], int buffersize) ************************************************************************/ /** - * @param doc an input document - * * Call this routine to speed up XPath computation on static documents. * This stamps all the element nodes with the document order * Like for line information, the order is kept in the element->content * field, the value stored is actually - the node number (starting at -1) * to be able to differentiate from line numbers. * + * @param doc an input document * @returns the number of elements found in the document or -1 in case * of error. */ @@ -2413,11 +2388,10 @@ xmlXPathOrderDocElems(xmlDocPtr doc) { } /** - * @param node1 the first node - * @param node2 the second node - * * Compare two nodes w.r.t document order * + * @param node1 the first node + * @param node2 the second node * @returns -2 in case of error 1 if first point < second point, 0 if * it's the same node, -1 otherwise */ @@ -2559,9 +2533,9 @@ xmlXPathCmpNodes(xmlNodePtr node1, xmlNodePtr node2) { } /** - * @param set the node set - * * Sort the node set in document order + * + * @param set the node set */ void xmlXPathNodeSetSort(xmlNodeSetPtr set) { @@ -2607,13 +2581,12 @@ xmlXPathNodeSetSort(xmlNodeSetPtr set) { #define XML_NODESET_DEFAULT 10 /** - * @param node the parent node of the namespace XPath node - * @param ns the libxml namespace declaration node. - * * Namespace node in libxml don't match the XPath semantic. In a node set * the namespace nodes are duplicated and the next pointer is set to the * parent node in the XPath semantic. * + * @param node the parent node of the namespace XPath node + * @param ns the libxml namespace declaration node. * @returns the newly created object. */ static xmlNodePtr @@ -2653,11 +2626,11 @@ xmlXPathNodeSetDupNs(xmlNodePtr node, xmlNsPtr ns) { } /** - * @param ns the XPath namespace node found in a nodeset. - * * Namespace nodes in libxml don't match the XPath semantic. In a node set * the namespace nodes are duplicated and the next pointer is set to the * parent node in the XPath semantic. Check if such a node needs to be freed + * + * @param ns the XPath namespace node found in a nodeset. */ void xmlXPathNodeSetFreeNs(xmlNsPtr ns) { @@ -2674,10 +2647,9 @@ xmlXPathNodeSetFreeNs(xmlNsPtr ns) { } /** - * @param val an initial xmlNodePtr, or NULL - * * Create a new xmlNodeSetPtr of type double and of value `val` * + * @param val an initial xmlNodePtr, or NULL * @returns the newly created object. */ xmlNodeSetPtr @@ -2714,11 +2686,10 @@ xmlXPathNodeSetCreate(xmlNodePtr val) { } /** - * @param cur the node-set - * @param val the node - * * checks whether `cur` contains `val` * + * @param cur the node-set + * @param val the node * @returns true (1) if `cur` contains `val`, false (0) otherwise */ int @@ -2768,12 +2739,11 @@ xmlXPathNodeSetGrow(xmlNodeSetPtr cur) { } /** + * add a new namespace node to an existing NodeSet + * * @param cur the initial node set * @param node the hosting node * @param ns a the namespace node - * - * add a new namespace node to an existing NodeSet - * * @returns 0 in case of success and -1 in case of error */ int @@ -2813,11 +2783,10 @@ xmlXPathNodeSetAddNs(xmlNodeSetPtr cur, xmlNodePtr node, xmlNsPtr ns) { } /** - * @param cur the initial node set - * @param val a new xmlNodePtr - * * add a new xmlNodePtr to an existing NodeSet * + * @param cur the initial node set + * @param val a new xmlNodePtr * @returns 0 in case of success, and -1 in case of error */ int @@ -2854,12 +2823,11 @@ xmlXPathNodeSetAdd(xmlNodeSetPtr cur, xmlNodePtr val) { } /** - * @param cur the initial node set - * @param val a new xmlNodePtr - * * add a new xmlNodePtr to an existing NodeSet, optimized version * when we are sure the node is not already in the set. * + * @param cur the initial node set + * @param val a new xmlNodePtr * @returns 0 in case of success and -1 in case of failure */ int @@ -2888,15 +2856,13 @@ xmlXPathNodeSetAddUnique(xmlNodeSetPtr cur, xmlNodePtr val) { } /** - * @param val1 the first NodeSet or NULL - * @param val2 the second NodeSet - * * Merges two nodesets, all nodes from `val2` are added to `val1` * if `val1` is NULL, a new set is created and copied from `val2` * - * @returns `val1` once extended or NULL in case of error. - * * Frees `val1` in case of error. + * @param val1 the first NodeSet or NULL + * @param val2 the second NodeSet + * @returns `val1` once extended or NULL in case of error. */ xmlNodeSetPtr xmlXPathNodeSetMerge(xmlNodeSetPtr val1, xmlNodeSetPtr val2) { @@ -2966,15 +2932,13 @@ error: /** - * @param set1 the first NodeSet or NULL - * @param set2 the second NodeSet - * * Merges two nodesets, all nodes from `set2` are added to `set1`. * Checks for duplicate nodes. Clears set2. * - * @returns `set1` once extended or NULL in case of error. - * * Frees `set1` in case of error. + * @param set1 the first NodeSet or NULL + * @param set2 the second NodeSet + * @returns `set1` once extended or NULL in case of error. */ static xmlNodeSetPtr xmlXPathNodeSetMergeAndClear(xmlNodeSetPtr set1, xmlNodeSetPtr set2) @@ -3030,15 +2994,13 @@ error: } /** - * @param set1 the first NodeSet or NULL - * @param set2 the second NodeSet - * * Merges two nodesets, all nodes from `set2` are added to `set1`. * Doesn't check for duplicate nodes. Clears set2. * - * @returns `set1` once extended or NULL in case of error. - * * Frees `set1` in case of error. + * @param set1 the first NodeSet or NULL + * @param set2 the second NodeSet + * @returns `set1` once extended or NULL in case of error. */ static xmlNodeSetPtr xmlXPathNodeSetMergeAndClearNoDupls(xmlNodeSetPtr set1, xmlNodeSetPtr set2) @@ -3067,10 +3029,10 @@ error: } /** + * Removes an xmlNodePtr from an existing NodeSet + * * @param cur the initial node set * @param val an xmlNodePtr - * - * Removes an xmlNodePtr from an existing NodeSet */ void xmlXPathNodeSetDel(xmlNodeSetPtr cur, xmlNodePtr val) { @@ -3098,10 +3060,10 @@ xmlXPathNodeSetDel(xmlNodeSetPtr cur, xmlNodePtr val) { } /** + * Removes an entry from an existing NodeSet list. + * * @param cur the initial node set * @param val the index to remove - * - * Removes an entry from an existing NodeSet list. */ void xmlXPathNodeSetRemove(xmlNodeSetPtr cur, int val) { @@ -3117,9 +3079,9 @@ xmlXPathNodeSetRemove(xmlNodeSetPtr cur, int val) { } /** - * @param obj the xmlNodeSetPtr to free - * * Free the NodeSet compound (not the actual nodes !). + * + * @param obj the xmlNodeSetPtr to free */ void xmlXPathFreeNodeSet(xmlNodeSetPtr obj) { @@ -3138,13 +3100,13 @@ xmlXPathFreeNodeSet(xmlNodeSetPtr obj) { } /** - * @param set the node set to be cleared - * @param pos the start position to clear from - * @param hasNsNodes the node set might contain namespace nodes - * * Clears the list from temporary XPath objects (e.g. namespace nodes * are feed) starting with the entry at `pos`, but does *not* free the list * itself. Sets the length of the list to `pos`. + * + * @param set the node set to be cleared + * @param pos the start position to clear from + * @param hasNsNodes the node set might contain namespace nodes */ static void xmlXPathNodeSetClearFromPos(xmlNodeSetPtr set, int pos, int hasNsNodes) @@ -3166,12 +3128,12 @@ xmlXPathNodeSetClearFromPos(xmlNodeSetPtr set, int pos, int hasNsNodes) } /** - * @param set the node set to clear - * @param hasNsNodes the node set might contain namespace nodes - * * Clears the list from all temporary XPath objects (e.g. namespace nodes * are feed), but does *not* free the list itself. Sets the length of the * list to 0. + * + * @param set the node set to clear + * @param hasNsNodes the node set might contain namespace nodes */ static void xmlXPathNodeSetClear(xmlNodeSetPtr set, int hasNsNodes) @@ -3180,11 +3142,11 @@ xmlXPathNodeSetClear(xmlNodeSetPtr set, int hasNsNodes) } /** - * @param set the node set to be cleared - * * Move the last node to the first position and clear temporary XPath objects * (e.g. namespace nodes) from all other nodes. Sets the length of the list * to 1. + * + * @param set the node set to be cleared */ static void xmlXPathNodeSetKeepLast(xmlNodeSetPtr set) @@ -3205,11 +3167,10 @@ xmlXPathNodeSetKeepLast(xmlNodeSetPtr set) } /** - * @param val the NodePtr value - * * Create a new xmlXPathObjectPtr of type NodeSet and initialize * it with the single Node `val` * + * @param val the NodePtr value * @returns the newly created object. */ xmlXPathObjectPtr @@ -3232,11 +3193,10 @@ xmlXPathNewNodeSet(xmlNodePtr val) { } /** - * @param val the NodePtr value - * * Create a new xmlXPathObjectPtr of type Value Tree (XSLT) and initialize * it with the tree root `val` * + * @param val the NodePtr value * @returns the newly created object. */ xmlXPathObjectPtr @@ -3252,11 +3212,10 @@ xmlXPathNewValueTree(xmlNodePtr val) { } /** - * @param val an existing NodeSet - * * Create a new xmlXPathObjectPtr of type NodeSet and initialize * it with the Nodeset `val` * + * @param val an existing NodeSet * @returns the newly created object. */ xmlXPathObjectPtr @@ -3283,13 +3242,11 @@ xmlXPathNewNodeSetList(xmlNodeSetPtr val) } /** - * @param val the NodePtr value - * * Wrap the Nodeset `val` in a new xmlXPathObjectPtr * - * @returns the newly created object. - * * In case of error the node set is destroyed and NULL is returned. + * @param val the NodePtr value + * @returns the newly created object. */ xmlXPathObjectPtr xmlXPathWrapNodeSet(xmlNodeSetPtr val) { @@ -3307,10 +3264,10 @@ xmlXPathWrapNodeSet(xmlNodeSetPtr val) { } /** - * @param obj an existing NodeSetList object - * * Free up the xmlXPathObjectPtr `obj` but don't deallocate the objects in * the list contrary to xmlXPathFreeObject(). + * + * @param obj an existing NodeSetList object */ void xmlXPathFreeNodeSetList(xmlXPathObjectPtr obj) { @@ -3319,12 +3276,11 @@ xmlXPathFreeNodeSetList(xmlXPathObjectPtr obj) { } /** - * @param nodes1 a node-set - * @param nodes2 a node-set - * * Implements the EXSLT - Sets difference() function: * node-set set:difference (node-set, node-set) * + * @param nodes1 a node-set + * @param nodes2 a node-set * @returns the difference between the two node sets, or nodes1 if * nodes2 is empty */ @@ -3358,12 +3314,11 @@ xmlXPathDifference (xmlNodeSetPtr nodes1, xmlNodeSetPtr nodes2) { } /** - * @param nodes1 a node-set - * @param nodes2 a node-set - * * Implements the EXSLT - Sets intersection() function: * node-set set:intersection (node-set, node-set) * + * @param nodes1 a node-set + * @param nodes2 a node-set * @returns a node set comprising the nodes that are within both the * node sets passed as arguments */ @@ -3395,11 +3350,10 @@ xmlXPathIntersection (xmlNodeSetPtr nodes1, xmlNodeSetPtr nodes2) { } /** - * @param nodes a node-set, sorted by document order - * * Implements the EXSLT - Sets distinct() function: * node-set set:distinct (node-set) * + * @param nodes a node-set, sorted by document order * @returns a subset of the nodes contained in `nodes`, or `nodes` if * it is empty */ @@ -3443,13 +3397,12 @@ error: } /** - * @param nodes a node-set - * * Implements the EXSLT - Sets distinct() function: * node-set set:distinct (node-set) * `nodes` is sorted by document order, then exslSetsDistinctSorted * is called with the sorted node-set * + * @param nodes a node-set * @returns a subset of the nodes contained in `nodes`, or `nodes` if * it is empty */ @@ -3463,12 +3416,11 @@ xmlXPathDistinct (xmlNodeSetPtr nodes) { } /** - * @param nodes1 a node-set - * @param nodes2 a node-set - * * Implements the EXSLT - Sets has-same-nodes function: * boolean set:has-same-node(node-set, node-set) * + * @param nodes1 a node-set + * @param nodes2 a node-set * @returns true (1) if `nodes1` shares any node with `nodes2`, false (0) * otherwise */ @@ -3491,12 +3443,11 @@ xmlXPathHasSameNodes (xmlNodeSetPtr nodes1, xmlNodeSetPtr nodes2) { } /** - * @param nodes a node-set, sorted by document order - * @param node a node - * * Implements the EXSLT - Sets leading() function: * node-set set:leading (node-set, node-set) * + * @param nodes a node-set, sorted by document order + * @param node a node * @returns the nodes in `nodes` that precede `node` in document order, * `nodes` if `node` is NULL or an empty node-set if `nodes` * doesn't contain `node` @@ -3531,14 +3482,13 @@ xmlXPathNodeLeadingSorted (xmlNodeSetPtr nodes, xmlNodePtr node) { } /** - * @param nodes a node-set - * @param node a node - * * Implements the EXSLT - Sets leading() function: * node-set set:leading (node-set, node-set) * `nodes` is sorted by document order, then exslSetsNodeLeadingSorted * is called. * + * @param nodes a node-set + * @param node a node * @returns the nodes in `nodes` that precede `node` in document order, * `nodes` if `node` is NULL or an empty node-set if `nodes` * doesn't contain `node` @@ -3550,12 +3500,11 @@ xmlXPathNodeLeading (xmlNodeSetPtr nodes, xmlNodePtr node) { } /** - * @param nodes1 a node-set, sorted by document order - * @param nodes2 a node-set, sorted by document order - * * Implements the EXSLT - Sets leading() function: * node-set set:leading (node-set, node-set) * + * @param nodes1 a node-set, sorted by document order + * @param nodes2 a node-set, sorted by document order * @returns the nodes in `nodes1` that precede the first node in `nodes2` * in document order, `nodes1` if `nodes2` is NULL or empty or * an empty node-set if `nodes1` doesn't contain `nodes2` @@ -3569,14 +3518,13 @@ xmlXPathLeadingSorted (xmlNodeSetPtr nodes1, xmlNodeSetPtr nodes2) { } /** - * @param nodes1 a node-set - * @param nodes2 a node-set - * * Implements the EXSLT - Sets leading() function: * node-set set:leading (node-set, node-set) * `nodes1` and `nodes2` are sorted by document order, then * exslSetsLeadingSorted is called. * + * @param nodes1 a node-set + * @param nodes2 a node-set * @returns the nodes in `nodes1` that precede the first node in `nodes2` * in document order, `nodes1` if `nodes2` is NULL or empty or * an empty node-set if `nodes1` doesn't contain `nodes2` @@ -3594,12 +3542,11 @@ xmlXPathLeading (xmlNodeSetPtr nodes1, xmlNodeSetPtr nodes2) { } /** - * @param nodes a node-set, sorted by document order - * @param node a node - * * Implements the EXSLT - Sets trailing() function: * node-set set:trailing (node-set, node-set) * + * @param nodes a node-set, sorted by document order + * @param node a node * @returns the nodes in `nodes` that follow `node` in document order, * `nodes` if `node` is NULL or an empty node-set if `nodes` * doesn't contain `node` @@ -3635,14 +3582,13 @@ xmlXPathNodeTrailingSorted (xmlNodeSetPtr nodes, xmlNodePtr node) { } /** - * @param nodes a node-set - * @param node a node - * * Implements the EXSLT - Sets trailing() function: * node-set set:trailing (node-set, node-set) * `nodes` is sorted by document order, then xmlXPathNodeTrailingSorted() * is called. * + * @param nodes a node-set + * @param node a node * @returns the nodes in `nodes` that follow `node` in document order, * `nodes` if `node` is NULL or an empty node-set if `nodes` * doesn't contain `node` @@ -3654,12 +3600,11 @@ xmlXPathNodeTrailing (xmlNodeSetPtr nodes, xmlNodePtr node) { } /** - * @param nodes1 a node-set, sorted by document order - * @param nodes2 a node-set, sorted by document order - * * Implements the EXSLT - Sets trailing() function: * node-set set:trailing (node-set, node-set) * + * @param nodes1 a node-set, sorted by document order + * @param nodes2 a node-set, sorted by document order * @returns the nodes in `nodes1` that follow the first node in `nodes2` * in document order, `nodes1` if `nodes2` is NULL or empty or * an empty node-set if `nodes1` doesn't contain `nodes2` @@ -3673,14 +3618,13 @@ xmlXPathTrailingSorted (xmlNodeSetPtr nodes1, xmlNodeSetPtr nodes2) { } /** - * @param nodes1 a node-set - * @param nodes2 a node-set - * * Implements the EXSLT - Sets trailing() function: * node-set set:trailing (node-set, node-set) * `nodes1` and `nodes2` are sorted by document order, then * xmlXPathTrailingSorted() is called. * + * @param nodes1 a node-set + * @param nodes2 a node-set * @returns the nodes in `nodes1` that follow the first node in `nodes2` * in document order, `nodes1` if `nodes2` is NULL or empty or * an empty node-set if `nodes1` doesn't contain `nodes2` @@ -3704,12 +3648,11 @@ xmlXPathTrailing (xmlNodeSetPtr nodes1, xmlNodeSetPtr nodes2) { ************************************************************************/ /** + * Register a new function. If `f` is NULL it unregisters the function + * * @param ctxt the XPath context * @param name the function name * @param f the function implementation or NULL - * - * Register a new function. If `f` is NULL it unregisters the function - * * @returns 0 in case of success, -1 in case of error */ int @@ -3719,13 +3662,12 @@ xmlXPathRegisterFunc(xmlXPathContextPtr ctxt, const xmlChar *name, } /** + * Register a new function. If `f` is NULL it unregisters the function + * * @param ctxt the XPath context * @param name the function name * @param ns_uri the function namespace URI * @param f the function implementation or NULL - * - * Register a new function. If `f` is NULL it unregisters the function - * * @returns 0 in case of success, -1 in case of error */ int @@ -3758,11 +3700,11 @@ xmlXPathRegisterFuncNS(xmlXPathContextPtr ctxt, const xmlChar *name, } /** + * Registers an external mechanism to do function lookup. + * * @param ctxt the XPath context * @param f the lookup function * @param funcCtxt the lookup data - * - * Registers an external mechanism to do function lookup. */ void xmlXPathRegisterFuncLookup (xmlXPathContextPtr ctxt, @@ -3775,12 +3717,11 @@ xmlXPathRegisterFuncLookup (xmlXPathContextPtr ctxt, } /** - * @param ctxt the XPath context - * @param name the function name - * * Search in the Function array of the context for the given * function. * + * @param ctxt the XPath context + * @param name the function name * @returns the xmlXPathFunction or NULL if not found */ xmlXPathFunction @@ -3789,13 +3730,12 @@ xmlXPathFunctionLookup(xmlXPathContextPtr ctxt, const xmlChar *name) { } /** - * @param ctxt the XPath context - * @param name the function name - * @param ns_uri the function namespace URI - * * Search in the Function array of the context for the given * function. * + * @param ctxt the XPath context + * @param name the function name + * @param ns_uri the function namespace URI * @returns the xmlXPathFunction or NULL if not found */ xmlXPathFunction @@ -3844,9 +3784,9 @@ xmlXPathFunctionLookupNS(xmlXPathContextPtr ctxt, const xmlChar *name, } /** - * @param ctxt the XPath context - * * Cleanup the XPath context data associated to registered functions + * + * @param ctxt the XPath context */ void xmlXPathRegisteredFuncsCleanup(xmlXPathContextPtr ctxt) { @@ -3864,13 +3804,12 @@ xmlXPathRegisteredFuncsCleanup(xmlXPathContextPtr ctxt) { ************************************************************************/ /** - * @param ctxt the XPath context - * @param name the variable name - * @param value the variable value or NULL - * * Register a new variable value. If `value` is NULL it unregisters * the variable * + * @param ctxt the XPath context + * @param name the variable name + * @param value the variable value or NULL * @returns 0 in case of success, -1 in case of error */ int @@ -3880,14 +3819,13 @@ xmlXPathRegisterVariable(xmlXPathContextPtr ctxt, const xmlChar *name, } /** + * Register a new variable value. If `value` is NULL it unregisters + * the variable + * * @param ctxt the XPath context * @param name the variable name * @param ns_uri the variable namespace URI * @param value the variable value or NULL - * - * Register a new variable value. If `value` is NULL it unregisters - * the variable - * * @returns 0 in case of success, -1 in case of error */ int @@ -3911,11 +3849,11 @@ xmlXPathRegisterVariableNS(xmlXPathContextPtr ctxt, const xmlChar *name, } /** + * register an external mechanism to do variable lookup + * * @param ctxt the XPath context * @param f the lookup function * @param data the lookup data - * - * register an external mechanism to do variable lookup */ void xmlXPathRegisterVariableLookup(xmlXPathContextPtr ctxt, @@ -3927,12 +3865,11 @@ xmlXPathRegisterVariableLookup(xmlXPathContextPtr ctxt, } /** - * @param ctxt the XPath context - * @param name the variable name - * * Search in the Variable array of the context for the given * variable value. * + * @param ctxt the XPath context + * @param name the variable name * @returns a copy of the value or NULL if not found */ xmlXPathObjectPtr @@ -3951,13 +3888,12 @@ xmlXPathVariableLookup(xmlXPathContextPtr ctxt, const xmlChar *name) { } /** - * @param ctxt the XPath context - * @param name the variable name - * @param ns_uri the variable namespace URI - * * Search in the Variable array of the context for the given * variable value. * + * @param ctxt the XPath context + * @param name the variable name + * @param ns_uri the variable namespace URI * @returns the a copy of the value or NULL if not found */ xmlXPathObjectPtr @@ -3983,9 +3919,9 @@ xmlXPathVariableLookupNS(xmlXPathContextPtr ctxt, const xmlChar *name, } /** - * @param ctxt the XPath context - * * Cleanup the XPath context data associated to registered variables + * + * @param ctxt the XPath context */ void xmlXPathRegisteredVariablesCleanup(xmlXPathContextPtr ctxt) { @@ -3997,13 +3933,12 @@ xmlXPathRegisteredVariablesCleanup(xmlXPathContextPtr ctxt) { } /** - * @param ctxt the XPath context - * @param prefix the namespace prefix cannot be NULL or empty string - * @param ns_uri the namespace name - * * Register a new namespace. If `ns_uri` is NULL it unregisters * the namespace * + * @param ctxt the XPath context + * @param prefix the namespace prefix cannot be NULL or empty string + * @param ns_uri the namespace name * @returns 0 in case of success, -1 in case of error */ int @@ -4044,12 +3979,11 @@ xmlXPathRegisterNs(xmlXPathContextPtr ctxt, const xmlChar *prefix, } /** - * @param ctxt the XPath context - * @param prefix the namespace prefix value - * * Search in the namespace declaration array of the context for the given * namespace name associated to the given prefix * + * @param ctxt the XPath context + * @param prefix the namespace prefix value * @returns the value or NULL if not found */ const xmlChar * @@ -4076,9 +4010,9 @@ xmlXPathNsLookup(xmlXPathContextPtr ctxt, const xmlChar *prefix) { } /** - * @param ctxt the XPath context - * * Cleanup the XPath context data associated to registered variables + * + * @param ctxt the XPath context */ void xmlXPathRegisteredNsCleanup(xmlXPathContextPtr ctxt) { @@ -4098,10 +4032,9 @@ xmlXPathRegisteredNsCleanup(xmlXPathContextPtr ctxt) { /* Allocations are terrible, one needs to optimize all this !!! */ /** - * @param val the double value - * * Create a new xmlXPathObjectPtr of type double and of value `val` * + * @param val the double value * @returns the newly created object. */ xmlXPathObjectPtr @@ -4118,10 +4051,9 @@ xmlXPathNewFloat(double val) { } /** - * @param val the boolean value - * * Create a new xmlXPathObjectPtr of type boolean and of value `val` * + * @param val the boolean value * @returns the newly created object. */ xmlXPathObjectPtr @@ -4138,10 +4070,9 @@ xmlXPathNewBoolean(int val) { } /** - * @param val the xmlChar * value - * * Create a new xmlXPathObjectPtr of type string and of value `val` * + * @param val the xmlChar * value * @returns the newly created object. */ xmlXPathObjectPtr @@ -4164,13 +4095,11 @@ xmlXPathNewString(const xmlChar *val) { } /** - * @param val the xmlChar * value - * * Wraps the `val` string into an XPath object. * - * @returns the newly created object. - * * Frees `val` in case of error. + * @param val the xmlChar * value + * @returns the newly created object. */ xmlXPathObjectPtr xmlXPathWrapString (xmlChar *val) { @@ -4188,10 +4117,9 @@ xmlXPathWrapString (xmlChar *val) { } /** - * @param val the char * value - * * Create a new xmlXPathObjectPtr of type string and of value `val` * + * @param val the char * value * @returns the newly created object. */ xmlXPathObjectPtr @@ -4200,10 +4128,9 @@ xmlXPathNewCString(const char *val) { } /** - * @param val the char * value - * * Wraps a string into an XPath object. * + * @param val the char * value * @returns the newly created object. */ xmlXPathObjectPtr @@ -4212,10 +4139,9 @@ xmlXPathWrapCString (char * val) { } /** - * @param val the user data - * * Wraps the `val` data into an XPath object. * + * @param val the user data * @returns the newly created object. */ xmlXPathObjectPtr @@ -4232,10 +4158,9 @@ xmlXPathWrapExternal (void *val) { } /** - * @param val the original object - * * allocate a new copy of a given object * + * @param val the original object * @returns the newly created object. */ xmlXPathObjectPtr @@ -4282,9 +4207,9 @@ xmlXPathObjectCopy(xmlXPathObjectPtr val) { } /** - * @param obj the object to free - * * Free up an xmlXPathObjectPtr object. + * + * @param obj the object to free */ void xmlXPathFreeObject(xmlXPathObjectPtr obj) { @@ -4305,11 +4230,11 @@ xmlXPathFreeObjectEntry(void *obj, const xmlChar *name ATTRIBUTE_UNUSED) { } /** - * @param ctxt XPath context - * @param obj the xmlXPathObjectPtr to free or to cache - * * Depending on the state of the cache this frees the given * XPath object or stores it in the cache. + * + * @param ctxt XPath context + * @param obj the xmlXPathObjectPtr to free or to cache */ static void xmlXPathReleaseObject(xmlXPathContextPtr ctxt, xmlXPathObjectPtr obj) @@ -4404,10 +4329,9 @@ free_obj: ************************************************************************/ /** - * @param val a boolean - * * Converts a boolean to its string value. * + * @param val a boolean * @returns a newly allocated string. */ xmlChar * @@ -4421,10 +4345,9 @@ xmlXPathCastBooleanToString (int val) { } /** - * @param val a number - * * Converts a number to its string value. * + * @param val a number * @returns a newly allocated string. */ xmlChar * @@ -4455,10 +4378,9 @@ xmlXPathCastNumberToString (double val) { } /** - * @param node a node - * * Converts a node to its string value. * + * @param node a node * @returns a newly allocated string. */ xmlChar * @@ -4467,10 +4389,9 @@ xmlXPathCastNodeToString (xmlNodePtr node) { } /** - * @param ns a node-set - * * Converts a node-set to its string value. * + * @param ns a node-set * @returns a newly allocated string. */ xmlChar * @@ -4484,10 +4405,9 @@ xmlXPathCastNodeSetToString (xmlNodeSetPtr ns) { } /** - * @param val an XPath object - * * Converts an existing object to its string() equivalent * + * @param val an XPath object * @returns the allocated string value of the object, NULL in case of error. * It's up to the caller to free the string memory with xmlFree(). */ @@ -4523,10 +4443,9 @@ xmlXPathCastToString(xmlXPathObjectPtr val) { } /** - * @param val an XPath object - * * Converts an existing object to its string() equivalent * + * @param val an XPath object * @returns the new object, the old one is freed (or the operation * is done directly on `val`) */ @@ -4563,10 +4482,9 @@ xmlXPathConvertString(xmlXPathObjectPtr val) { } /** - * @param val a boolean - * * Converts a boolean to its number value * + * @param val a boolean * @returns the number value */ double @@ -4577,10 +4495,9 @@ xmlXPathCastBooleanToNumber(int val) { } /** - * @param val a string - * * Converts a string to its number value * + * @param val a string * @returns the number value */ double @@ -4589,11 +4506,10 @@ xmlXPathCastStringToNumber(const xmlChar * val) { } /** - * @param ctxt XPath parser context - * @param node a node - * * Converts a node to its number value * + * @param ctxt XPath parser context + * @param node a node * @returns the number value */ static double @@ -4615,10 +4531,9 @@ xmlXPathNodeToNumberInternal(xmlXPathParserContextPtr ctxt, xmlNodePtr node) { } /** - * @param node a node - * * Converts a node to its number value * + * @param node a node * @returns the number value */ double @@ -4627,10 +4542,9 @@ xmlXPathCastNodeToNumber (xmlNodePtr node) { } /** - * @param ns a node-set - * * Converts a node-set to its number value * + * @param ns a node-set * @returns the number value */ double @@ -4647,10 +4561,9 @@ xmlXPathCastNodeSetToNumber (xmlNodeSetPtr ns) { } /** - * @param val an XPath object - * * Converts an XPath object to its number value * + * @param val an XPath object * @returns the number value */ double @@ -4659,10 +4572,9 @@ xmlXPathCastToNumber(xmlXPathObjectPtr val) { } /** - * @param val an XPath object - * * Converts an existing object to its number() equivalent * + * @param val an XPath object * @returns the new object, the old one is freed (or the operation * is done directly on `val`) */ @@ -4680,10 +4592,9 @@ xmlXPathConvertNumber(xmlXPathObjectPtr val) { } /** - * @param val a number - * * Converts a number to its boolean value * + * @param val a number * @returns the boolean value */ int @@ -4694,10 +4605,9 @@ xmlXPathCastNumberToBoolean (double val) { } /** - * @param val a string - * * Converts a string to its boolean value * + * @param val a string * @returns the boolean value */ int @@ -4708,10 +4618,9 @@ xmlXPathCastStringToBoolean (const xmlChar *val) { } /** - * @param ns a node-set - * * Converts a node-set to its boolean value * + * @param ns a node-set * @returns the boolean value */ int @@ -4722,10 +4631,9 @@ xmlXPathCastNodeSetToBoolean (xmlNodeSetPtr ns) { } /** - * @param val an XPath object - * * Converts an XPath object to its boolean value * + * @param val an XPath object * @returns the boolean value */ int @@ -4761,10 +4669,9 @@ xmlXPathCastToBoolean (xmlXPathObjectPtr val) { /** - * @param val an XPath object - * * Converts an existing object to its boolean() equivalent * + * @param val an XPath object * @returns the new object, the old one is freed (or the operation * is done directly on `val`) */ @@ -4788,10 +4695,9 @@ xmlXPathConvertBoolean(xmlXPathObjectPtr val) { ************************************************************************/ /** - * @param doc the XML document - * * Create a new xmlXPathContext * + * @param doc the XML document * @returns the xmlXPathContext just allocated. The caller will need to free it. */ xmlXPathContextPtr @@ -4832,9 +4738,9 @@ xmlXPathNewContext(xmlDocPtr doc) { } /** - * @param ctxt the context to free - * * Free up an xmlXPathContext + * + * @param ctxt the context to free */ void xmlXPathFreeContext(xmlXPathContextPtr ctxt) { @@ -4850,14 +4756,13 @@ xmlXPathFreeContext(xmlXPathContextPtr ctxt) { } /** - * @param ctxt the XPath context - * @param handler error handler - * @param data user data which will be passed to the handler - * * Register a callback function that will be called on errors and * warnings. If handler is NULL, the error handler will be deactivated. * * @since 2.13.0 + * @param ctxt the XPath context + * @param handler error handler + * @param data user data which will be passed to the handler */ void xmlXPathSetErrorHandler(xmlXPathContextPtr ctxt, @@ -4876,11 +4781,10 @@ xmlXPathSetErrorHandler(xmlXPathContextPtr ctxt, ************************************************************************/ /** - * @param str the XPath expression - * @param ctxt the XPath context - * * Create a new xmlXPathParserContext * + * @param str the XPath expression + * @param ctxt the XPath context * @returns the xmlXPathParserContext just allocated. */ xmlXPathParserContextPtr @@ -4912,11 +4816,10 @@ xmlXPathNewParserContext(const xmlChar *str, xmlXPathContextPtr ctxt) { } /** - * @param comp the XPath compiled expression - * @param ctxt the XPath context - * * Create a new xmlXPathParserContext when processing a compiled expression * + * @param comp the XPath compiled expression + * @param ctxt the XPath context * @returns the xmlXPathParserContext just allocated. */ static xmlXPathParserContextPtr @@ -4952,9 +4855,9 @@ xmlXPathCompParserContext(xmlXPathCompExprPtr comp, xmlXPathContextPtr ctxt) { } /** - * @param ctxt the context to free - * * Free up an xmlXPathParserContext + * + * @param ctxt the context to free */ void xmlXPathFreeParserContext(xmlXPathParserContextPtr ctxt) { @@ -4991,11 +4894,10 @@ xmlXPathFreeParserContext(xmlXPathParserContextPtr ctxt) { ************************************************************************/ /** - * @param node a node pointer - * * Function computing the beginning of the string value of the node, * used to speed up comparisons * + * @param node a node pointer * @returns an int usable as a hash */ static unsigned int @@ -5103,11 +5005,10 @@ xmlXPathNodeValHash(xmlNodePtr node) { } /** - * @param string a string - * * Function computing the beginning of the string value of the node, * used to speed up comparisons * + * @param string a string * @returns an int usable as a hash */ static unsigned int @@ -5120,12 +5021,6 @@ xmlXPathStringHash(const xmlChar * string) { } /** - * @param ctxt the XPath Parser context - * @param inf less than (1) or greater than (0) - * @param strict is the comparison strict - * @param arg the node set - * @param f the value - * * Implement the compare operation between a nodeset and a number * `ns` < `val` (1, 1, ... * `ns` <= `val` (1, 0, ... @@ -5138,6 +5033,11 @@ xmlXPathStringHash(const xmlChar * string) { * to be compared and on the result of converting the string-value of that * node to a number using the number function is true. * + * @param ctxt the XPath Parser context + * @param inf less than (1) or greater than (0) + * @param strict is the comparison strict + * @param arg the node set + * @param f the value * @returns 0 or 1 depending on the results of the test. */ static int @@ -5176,12 +5076,6 @@ xmlXPathCompareNodeSetFloat(xmlXPathParserContextPtr ctxt, int inf, int strict, } /** - * @param ctxt the XPath Parser context - * @param inf less than (1) or greater than (0) - * @param strict is the comparison strict - * @param arg the node set - * @param s the value - * * Implement the compare operation between a nodeset and a string * `ns` < `val` (1, 1, ... * `ns` <= `val` (1, 0, ... @@ -5193,6 +5087,11 @@ xmlXPathCompareNodeSetFloat(xmlXPathParserContextPtr ctxt, int inf, int strict, * the node-set such that the result of performing the comparison on the * string-value of the node and the other string is true. * + * @param ctxt the XPath Parser context + * @param inf less than (1) or greater than (0) + * @param strict is the comparison strict + * @param arg the node set + * @param s the value * @returns 0 or 1 depending on the results of the test. */ static int @@ -5231,12 +5130,6 @@ xmlXPathCompareNodeSetString(xmlXPathParserContextPtr ctxt, int inf, int strict, } /** - * @param ctxt XPath parser context - * @param inf less than (1) or greater than (0) - * @param strict is the comparison strict - * @param arg1 the first node set object - * @param arg2 the second node set object - * * Implement the compare operation on nodesets: * * If both objects to be compared are node-sets, then the comparison @@ -5257,6 +5150,11 @@ xmlXPathCompareNodeSetString(xmlXPathParserContextPtr ctxt, int inf, int strict, * * Conclusion all nodes need to be converted first to their string value * and then the comparison must be done when possible + * @param ctxt XPath parser context + * @param inf less than (1) or greater than (0) + * @param strict is the comparison strict + * @param arg1 the first node set object + * @param arg2 the second node set object */ static int xmlXPathCompareNodeSets(xmlXPathParserContextPtr ctxt, int inf, int strict, @@ -5334,12 +5232,6 @@ xmlXPathCompareNodeSets(xmlXPathParserContextPtr ctxt, int inf, int strict, } /** - * @param ctxt the XPath Parser context - * @param inf less than (1) or greater than (0) - * @param strict is the comparison strict - * @param arg the node set - * @param val the value - * * Implement the compare operation between a nodeset and a value * `ns` < `val` (1, 1, ... * `ns` <= `val` (1, 0, ... @@ -5351,6 +5243,11 @@ xmlXPathCompareNodeSets(xmlXPathParserContextPtr ctxt, int inf, int strict, * the comparison on the boolean and on the result of converting * the node-set to a boolean using the boolean function is true. * + * @param ctxt the XPath Parser context + * @param inf less than (1) or greater than (0) + * @param strict is the comparison strict + * @param arg the node set + * @param val the value * @returns 0 or 1 depending on the results of the test. */ static int @@ -5382,17 +5279,16 @@ xmlXPathCompareNodeSetValue(xmlXPathParserContextPtr ctxt, int inf, int strict, } /** - * @param ctxt XPath parser context - * @param arg the nodeset object argument - * @param str the string to compare to. - * @param neq flag to show whether for '=' (0) or '!=' (1) - * * Implement the equal operation on XPath objects content: `arg1` == `arg2` * If one object to be compared is a node-set and the other is a string, * then the comparison will be true if and only if there is a node in * the node-set such that the result of performing the comparison on the * string-value of the node and the other string is true. * + * @param ctxt XPath parser context + * @param arg the nodeset object argument + * @param str the string to compare to. + * @param neq flag to show whether for '=' (0) or '!=' (1) * @returns 0 or 1 depending on the results of the test. */ static int @@ -5439,11 +5335,6 @@ xmlXPathEqualNodeSetString(xmlXPathParserContextPtr ctxt, } /** - * @param ctxt XPath parser context - * @param arg the nodeset object argument - * @param f the float to compare to - * @param neq flag to show whether to compare '=' (0) or '!=' (1) - * * Implement the equal operation on XPath objects content: `arg1` == `arg2` * If one object to be compared is a node-set and the other is a number, * then the comparison will be true if and only if there is a node in @@ -5451,6 +5342,10 @@ xmlXPathEqualNodeSetString(xmlXPathParserContextPtr ctxt, * number to be compared and on the result of converting the string-value * of that node to a number using the number function is true. * + * @param ctxt XPath parser context + * @param arg the nodeset object argument + * @param f the float to compare to + * @param neq flag to show whether to compare '=' (0) or '!=' (1) * @returns 0 or 1 depending on the results of the test. */ static int @@ -5501,11 +5396,6 @@ xmlXPathEqualNodeSetFloat(xmlXPathParserContextPtr ctxt, /** - * @param ctxt XPath parser context - * @param arg1 first nodeset object argument - * @param arg2 second nodeset object argument - * @param neq flag to show whether to test '=' (0) or '!=' (1) - * * Implement the equal / not equal operation on XPath nodesets: * `arg1` == `arg2` or `arg1` != `arg2` * If both objects to be compared are node-sets, then the comparison @@ -5515,6 +5405,10 @@ xmlXPathEqualNodeSetFloat(xmlXPathParserContextPtr ctxt, * * (needless to say, this is a costly operation) * + * @param ctxt XPath parser context + * @param arg1 first nodeset object argument + * @param arg2 second nodeset object argument + * @param neq flag to show whether to test '=' (0) or '!=' (1) * @returns 0 or 1 depending on the results of the test. */ static int @@ -5782,10 +5676,9 @@ xmlXPathEqualValuesCommon(xmlXPathParserContextPtr ctxt, } /** - * @param ctxt the XPath Parser context - * * Implement the equal operation on XPath objects content: `arg1` == `arg2` * + * @param ctxt the XPath Parser context * @returns 0 or 1 depending on the results of the test. */ int @@ -5856,10 +5749,9 @@ xmlXPathEqualValues(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Implement the equal operation on XPath objects content: `arg1` == `arg2` * + * @param ctxt the XPath Parser context * @returns 0 or 1 depending on the results of the test. */ int @@ -5930,10 +5822,6 @@ xmlXPathNotEqualValues(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * @param inf less than (1) or greater than (0) - * @param strict is the comparison strict - * * Implement the compare operation on XPath objects: * `arg1` < `arg2` (1, 1, ... * `arg1` <= `arg2` (1, 0, ... @@ -5950,6 +5838,9 @@ xmlXPathNotEqualValues(xmlXPathParserContextPtr ctxt) { * number. The >= comparison will be true if and only if the first number * is greater than or equal to the second number. * + * @param ctxt the XPath Parser context + * @param inf less than (1) or greater than (0) + * @param strict is the comparison strict * @returns 1 if the comparison succeeded, 0 if it failed */ int @@ -6058,11 +5949,11 @@ error: } /** - * @param ctxt the XPath Parser context - * * Implement the unary - operation on an XPath object * The numeric operators convert their operands to numbers as if * by calling the number function. + * + * @param ctxt the XPath Parser context */ void xmlXPathValueFlipSign(xmlXPathParserContextPtr ctxt) { @@ -6073,11 +5964,11 @@ xmlXPathValueFlipSign(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Implement the add operation on XPath objects: * The numeric operators convert their operands to numbers as if * by calling the number function. + * + * @param ctxt the XPath Parser context */ void xmlXPathAddValues(xmlXPathParserContextPtr ctxt) { @@ -6095,11 +5986,11 @@ xmlXPathAddValues(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Implement the subtraction operation on XPath objects: * The numeric operators convert their operands to numbers as if * by calling the number function. + * + * @param ctxt the XPath Parser context */ void xmlXPathSubValues(xmlXPathParserContextPtr ctxt) { @@ -6117,11 +6008,11 @@ xmlXPathSubValues(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Implement the multiply operation on XPath objects: * The numeric operators convert their operands to numbers as if * by calling the number function. + * + * @param ctxt the XPath Parser context */ void xmlXPathMultValues(xmlXPathParserContextPtr ctxt) { @@ -6139,11 +6030,11 @@ xmlXPathMultValues(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Implement the div operation on XPath objects `arg1` / `arg2`. * The numeric operators convert their operands to numbers as if * by calling the number function. + * + * @param ctxt the XPath Parser context */ ATTRIBUTE_NO_SANITIZE("float-divide-by-zero") void @@ -6162,11 +6053,11 @@ xmlXPathDivValues(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Implement the mod operation on XPath objects: `arg1` / `arg2` * The numeric operators convert their operands to numbers as if * by calling the number function. + * + * @param ctxt the XPath Parser context */ void xmlXPathModValues(xmlXPathParserContextPtr ctxt) { @@ -6219,12 +6110,11 @@ typedef xmlNodeSetPtr (*xmlXPathNodeSetMergeFunction) /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "self" direction * The self axis contains just the context node itself * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6236,12 +6126,11 @@ xmlXPathNextSelf(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "child" direction * The child axis contains the children of the context node in document order. * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6283,12 +6172,11 @@ xmlXPathNextChild(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "child" direction and nodes of type element. * The child axis contains the children of the context node in document order. * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ static xmlNodePtr @@ -6354,13 +6242,12 @@ xmlXPathNextChildElement(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "descendant" direction * the descendant axis contains the descendants of the context node in document * order; a descendant is a child or a child of a child and so on. * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6416,15 +6303,14 @@ xmlXPathNextDescendant(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "descendant-or-self" direction * the descendant-or-self axis contains the context node and the descendants * of the context node in document order; thus the context node is the first * node on the axis, and the first child of the context node is the second node * on the axis * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6443,12 +6329,11 @@ xmlXPathNextDescendantOrSelf(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "parent" direction * The parent axis contains the parent of the context node, if there is one. * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6508,9 +6393,6 @@ xmlXPathNextParent(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "ancestor" direction * the ancestor axis contains the ancestors of the context node; the ancestors * of the context node consist of the parent of context node and the parent's @@ -6518,6 +6400,8 @@ xmlXPathNextParent(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { * parent is the first node on the axis, and the parent's parent is the second * node on the axis * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6626,15 +6510,14 @@ xmlXPathNextAncestor(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "ancestor-or-self" direction * he ancestor-or-self axis contains the context node and ancestors of * the context node in reverse document order; thus the context node is * the first node on the axis, and the context node's parent the second; * parent here is defined the same as with the parent axis. * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6646,13 +6529,12 @@ xmlXPathNextAncestorOrSelf(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "following-sibling" direction * The following-sibling axis contains the following siblings of the context * node in document order. * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6669,14 +6551,13 @@ xmlXPathNextFollowingSibling(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "preceding-sibling" direction * The preceding-sibling axis contains the preceding siblings of the context * node in reverse document order; the first preceding sibling is first on the * axis; the sibling preceding that node is the second on the axis and so on. * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6698,15 +6579,14 @@ xmlXPathNextPrecedingSibling(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "following" direction * The following axis contains all nodes in the same document as the context * node that are after the context node in document order, excluding any * descendants and excluding attribute nodes and namespace nodes; the nodes * are ordered in document order * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6769,15 +6649,14 @@ xmlXPathIsAncestor(xmlNodePtr ancestor, xmlNodePtr node) { } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "preceding" direction * the preceding axis contains all nodes in the same document as the context * node that are before the context node in document order, excluding any * ancestors and excluding attribute nodes and namespace nodes; the nodes are * ordered in reverse document order * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6817,9 +6696,6 @@ xmlXPathNextPreceding(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) } /** - * @param ctxt the XPath Parser context - * @param cur the current node in the traversal - * * Traversal function for the "preceding" direction * the preceding axis contains all nodes in the same document as the context * node that are before the context node in document order, excluding any @@ -6828,6 +6704,8 @@ xmlXPathNextPreceding(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) * This is a faster implementation but internal only since it requires a * state kept in the parser context: ctxt->ancestor. * + * @param ctxt the XPath Parser context + * @param cur the current node in the traversal * @returns the next element following that axis */ static xmlNodePtr @@ -6872,9 +6750,6 @@ xmlXPathNextPrecedingInternal(xmlXPathParserContextPtr ctxt, } /** - * @param ctxt the XPath Parser context - * @param cur the current attribute in the traversal - * * Traversal function for the "namespace" direction * the namespace axis contains the namespace nodes of the context node; * the order of nodes on this axis is implementation-defined; the axis will @@ -6882,6 +6757,8 @@ xmlXPathNextPrecedingInternal(xmlXPathParserContextPtr ctxt, * * We keep the XML namespace node at the end of the list. * + * @param ctxt the XPath Parser context + * @param cur the current attribute in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6915,12 +6792,11 @@ xmlXPathNextNamespace(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { } /** - * @param ctxt the XPath Parser context - * @param cur the current attribute in the traversal - * * Traversal function for the "attribute" direction * TODO: support DTD inherited default attributes * + * @param ctxt the XPath Parser context + * @param cur the current attribute in the traversal * @returns the next element following that axis */ xmlNodePtr @@ -6954,9 +6830,9 @@ xmlXPathNextAttribute(xmlXPathParserContextPtr ctxt, xmlNodePtr cur) { ************************************************************************/ /** - * @param ctxt the XPath Parser context - * * Initialize the context to the root of the document + * + * @param ctxt the XPath Parser context */ void xmlXPathRoot(xmlXPathParserContextPtr ctxt) { @@ -6975,12 +6851,12 @@ xmlXPathRoot(xmlXPathParserContextPtr ctxt) { /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the last() XPath function * number last() * The last function returns the number of nodes in the context node list. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathLastFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -6994,14 +6870,14 @@ xmlXPathLastFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the position() XPath function * number position() * The position function returns the position of the context node in the * context node list. The first position is 1, and so the last position * will be equal to last(). + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathPositionFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7015,11 +6891,11 @@ xmlXPathPositionFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the count() XPath function * number count(node-set) + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathCountFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7041,11 +6917,10 @@ xmlXPathCountFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param doc the document - * @param ids a whitespace separated list of IDs - * * Selects elements by their unique ID. * + * @param doc the document + * @param ids a whitespace separated list of IDs * @returns a node-set of selected elements. */ static xmlNodeSetPtr @@ -7103,9 +6978,6 @@ xmlXPathGetElementsByIds (xmlDocPtr doc, const xmlChar *ids) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the id() XPath function * node-set id(object) * The id function selects elements by their unique ID @@ -7118,6 +6990,9 @@ xmlXPathGetElementsByIds (xmlDocPtr doc, const xmlChar *ids) { * of characters matching the production S); the result is a node-set * containing the elements in the same document as the context node that * have a unique ID equal to any of the tokens in the list. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathIdFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7169,9 +7044,6 @@ xmlXPathIdFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the local-name() XPath function * string local-name(node-set?) * The local-name function returns a string containing the local part @@ -7179,6 +7051,9 @@ xmlXPathIdFunction(xmlXPathParserContextPtr ctxt, int nargs) { * document order. If the node-set is empty or the first node has no * name, an empty string is returned. If the argument is omitted it * defaults to the context node. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathLocalNameFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7224,9 +7099,6 @@ xmlXPathLocalNameFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the namespace-uri() XPath function * string namespace-uri(node-set?) * The namespace-uri function returns a string containing the @@ -7235,6 +7107,9 @@ xmlXPathLocalNameFunction(xmlXPathParserContextPtr ctxt, int nargs) { * the first node has no name, or the expanded name has no namespace * URI, an empty string is returned. If the argument is omitted it * defaults to the context node. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathNamespaceURIFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7274,9 +7149,6 @@ xmlXPathNamespaceURIFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the name() XPath function * string name(node-set?) * The name function returns a string containing a QName representing @@ -7293,6 +7165,9 @@ xmlXPathNamespaceURIFunction(xmlXPathParserContextPtr ctxt, int nargs) { * defaults to the context node. * Libxml keep the original prefix so the "real qualified name" used is * returned. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ static void xmlXPathNameFunction(xmlXPathParserContextPtr ctxt, int nargs) @@ -7350,9 +7225,6 @@ xmlXPathNameFunction(xmlXPathParserContextPtr ctxt, int nargs) /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the string() XPath function * string string(object?) * The string function converts an object to a string as follows: @@ -7383,6 +7255,8 @@ xmlXPathNameFunction(xmlXPathParserContextPtr ctxt, int nargs) * * If the argument is omitted, it defaults to a node-set with the * context node as its only member. + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathStringFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7412,15 +7286,15 @@ xmlXPathStringFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the string-length() XPath function * number string-length(string?) * The string-length returns the number of characters in the string * (see [3.6 Strings]). If the argument is omitted, it defaults to * the context node converted to a string, in other words the value * of the context node. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathStringLengthFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7453,12 +7327,12 @@ xmlXPathStringLengthFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the concat() XPath function * string concat(string, string, string*) * The concat function returns the concatenation of its arguments. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathConcatFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7498,13 +7372,13 @@ xmlXPathConcatFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the contains() XPath function * boolean contains(string, string) * The contains function returns true if the first argument string * contains the second argument string, and otherwise returns false. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathContainsFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7531,13 +7405,13 @@ xmlXPathContainsFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the starts-with() XPath function * boolean starts-with(string, string) * The starts-with function returns true if the first argument string * starts with the second argument string, and otherwise returns false. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathStartsWithFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7566,9 +7440,6 @@ xmlXPathStartsWithFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the substring() XPath function * string substring(string, number, number?) * The substring function returns the substring of the first argument @@ -7591,6 +7462,9 @@ xmlXPathStartsWithFunction(xmlXPathParserContextPtr ctxt, int nargs) { * - substring("12345", 1, 0 div 0) returns "" * - substring("12345", -42, 1 div 0) returns "12345" * - substring("12345", -1 div 0, 1 div 0) returns "" + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathSubstringFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7668,9 +7542,6 @@ xmlXPathSubstringFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the substring-before() XPath function * string substring-before(string, string) * The substring-before function returns the substring of the first @@ -7678,6 +7549,9 @@ xmlXPathSubstringFunction(xmlXPathParserContextPtr ctxt, int nargs) { * argument string in the first argument string, or the empty string * if the first argument string does not contain the second argument * string. For example, substring-before("1999/04/01","/") returns 1999. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathSubstringBeforeFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7712,9 +7586,6 @@ error: } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the substring-after() XPath function * string substring-after(string, string) * The substring-after function returns the substring of the first @@ -7723,6 +7594,9 @@ error: * if the first argument string does not contain the second argument * string. For example, substring-after("1999/04/01","/") returns 04/01, * and substring-after("1999/04/01","19") returns 99/04/01. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathSubstringAfterFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7757,9 +7631,6 @@ error: } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the normalize-space() XPath function * string normalize-space(string?) * The normalize-space function returns the argument string with white @@ -7768,6 +7639,9 @@ error: * space. Whitespace characters are the same allowed by the S production * in XML. If the argument is omitted, it defaults to the context * node converted to a string, in other words the value of the context node. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathNormalizeFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7814,9 +7688,6 @@ xmlXPathNormalizeFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the translate() XPath function * string translate(string, string, string) * The translate function returns the first argument string with @@ -7833,6 +7704,9 @@ xmlXPathNormalizeFunction(xmlXPathParserContextPtr ctxt, int nargs) { * argument string, then the first occurrence determines the replacement * character. If the third argument string is longer than the second * argument string, then excess characters are ignored. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathTranslateFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7924,9 +7798,6 @@ error: } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the boolean() XPath function * boolean boolean(object) * The boolean function converts its argument to a boolean as follows: @@ -7934,6 +7805,9 @@ error: * negative zero nor NaN * - a node-set is true if and only if it is non-empty * - a string is true if and only if its length is non-zero + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathBooleanFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7952,13 +7826,13 @@ xmlXPathBooleanFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the not() XPath function * boolean not(boolean) * The not function returns true if its argument is false, * and false otherwise. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathNotFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7969,11 +7843,11 @@ xmlXPathNotFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the true() XPath function * boolean true() + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathTrueFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7982,11 +7856,11 @@ xmlXPathTrueFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the false() XPath function * boolean false() + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathFalseFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -7995,9 +7869,6 @@ xmlXPathFalseFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the lang() XPath function * boolean lang(string) * The lang function returns true or false depending on whether the @@ -8013,6 +7884,9 @@ xmlXPathFalseFunction(xmlXPathParserContextPtr ctxt, int nargs) { * or if there is some suffix starting with - such that the attribute * value is equal to the argument ignoring that suffix of the attribute * value and ignoring case. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathLangFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -8053,11 +7927,11 @@ not_equal: } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the number() XPath function * number number(object?) + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathNumberFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -8093,13 +7967,13 @@ xmlXPathNumberFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the sum() XPath function * number sum(node-set) * The sum function returns the sum of the values of the nodes in * the argument node-set. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathSumFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -8125,13 +7999,13 @@ xmlXPathSumFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the floor() XPath function * number floor(number) * The floor function returns the largest (closest to positive infinity) * number that is not greater than the argument and that is an integer. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathFloorFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -8143,13 +8017,13 @@ xmlXPathFloorFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the ceiling() XPath function * number ceiling(number) * The ceiling function returns the smallest (closest to negative infinity) * number that is not less than the argument and that is an integer. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathCeilingFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -8166,14 +8040,14 @@ xmlXPathCeilingFunction(xmlXPathParserContextPtr ctxt, int nargs) { } /** - * @param ctxt the XPath Parser context - * @param nargs the number of arguments - * * Implement the round() XPath function * number round(number) * The round function returns the number that is closest to the * argument and that is an integer. If there are two such numbers, * then the one that is closest to positive infinity is returned. + * + * @param ctxt the XPath Parser context + * @param nargs the number of arguments */ void xmlXPathRoundFunction(xmlXPathParserContextPtr ctxt, int nargs) { @@ -8215,12 +8089,11 @@ static xmlChar * xmlXPathParseNameComplex(xmlXPathParserContextPtr ctxt, int qualified); /** - * @param ctxt the XPath parser context - * @param len pointer to the length of the char read - * * The current char value, if using UTF-8 this may actually span multiple * bytes in the input buffer. * + * @param ctxt the XPath parser context + * @param len pointer to the length of the char read * @returns the current char value and its length */ @@ -8298,8 +8171,6 @@ encoding_error: } /** - * @param ctxt the XPath Parser context - * * parse an XML namespace non qualified name. * * [NS 3] NCName ::= (Letter | '_') (NCNameChar)* @@ -8307,6 +8178,7 @@ encoding_error: * [NS 4] NCNameChar ::= Letter | Digit | '.' | '-' | '_' | * CombiningChar | Extender * + * @param ctxt the XPath Parser context * @returns the namespace name or NULL */ @@ -8349,9 +8221,6 @@ xmlXPathParseNCName(xmlXPathParserContextPtr ctxt) { /** - * @param ctxt the XPath Parser context - * @param prefix a xmlChar ** - * * parse an XML qualified name * * [NS 5] QName ::= (Prefix ':')? LocalPart @@ -8360,6 +8229,8 @@ xmlXPathParseNCName(xmlXPathParserContextPtr ctxt) { * * [NS 7] LocalPart ::= NCName * + * @param ctxt the XPath Parser context + * @param prefix a xmlChar ** * @returns the function returns the local part, and prefix is updated * to get the Prefix if any. */ @@ -8379,8 +8250,6 @@ xmlXPathParseQName(xmlXPathParserContextPtr ctxt, xmlChar **prefix) { } /** - * @param ctxt the XPath Parser context - * * parse an XML name * * [4] NameChar ::= Letter | Digit | '.' | '-' | '_' | ':' | @@ -8388,6 +8257,7 @@ xmlXPathParseQName(xmlXPathParserContextPtr ctxt, xmlChar **prefix) { * * [5] Name ::= (Letter | '_' | ':') (NameChar)* * + * @param ctxt the XPath Parser context * @returns the namespace name or NULL */ @@ -8516,8 +8386,6 @@ xmlXPathParseNameComplex(xmlXPathParserContextPtr ctxt, int qualified) { #define MAX_FRAC 20 /** - * @param str A string to scan - * * [30a] Float ::= Number ('e' Digits?)? * * [30] Number ::= Digits ('.' Digits?)? @@ -8528,6 +8396,7 @@ xmlXPathParseNameComplex(xmlXPathParserContextPtr ctxt, int qualified) { * In complement of the Number expression, this function also handles * negative values : '-' Number. * + * @param str A string to scan * @returns the double value. */ double @@ -8622,14 +8491,13 @@ xmlXPathStringEvalNumber(const xmlChar *str) { } /** - * @param ctxt the XPath Parser context - * * [30] Number ::= Digits ('.' Digits?)? * | '.' Digits * [31] Digits ::= [0-9]+ * * Compile a Number, then push it on the stack * + * @param ctxt the XPath Parser context */ static void xmlXPathCompNumber(xmlXPathParserContextPtr ctxt) @@ -8721,13 +8589,12 @@ xmlXPathCompNumber(xmlXPathParserContextPtr ctxt) } /** - * @param ctxt the XPath Parser context - * * Parse a Literal * * [29] Literal ::= '"' [^"]* '"' * | "'" [^']* "'" * + * @param ctxt the XPath Parser context * @returns the value found or NULL in case of error */ static xmlChar * @@ -8765,14 +8632,13 @@ xmlXPathParseLiteral(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Parse a Literal and push it on the stack. * * [29] Literal ::= '"' [^"]* '"' * | "'" [^']* "'" * * TODO: xmlXPathCompLiteral() memory allocation could be improved. + * @param ctxt the XPath Parser context */ static void xmlXPathCompLiteral(xmlXPathParserContextPtr ctxt) { @@ -8793,8 +8659,6 @@ xmlXPathCompLiteral(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Parse a VariableReference, evaluate it and push it on the stack. * * The variable bindings consist of a mapping from variable names @@ -8807,6 +8671,7 @@ xmlXPathCompLiteral(xmlXPathParserContextPtr ctxt) { * always the same as those used to evaluate the containing expression. * * [36] VariableReference ::= '$' QName + * @param ctxt the XPath Parser context */ static void xmlXPathCompVariableReference(xmlXPathParserContextPtr ctxt) { @@ -8835,8 +8700,6 @@ xmlXPathCompVariableReference(xmlXPathParserContextPtr ctxt) { } /** - * @param name a name string - * * Is the name given a NodeType one. * * [38] NodeType ::= 'comment' @@ -8844,6 +8707,7 @@ xmlXPathCompVariableReference(xmlXPathParserContextPtr ctxt) { * | 'processing-instruction' * | 'node' * + * @param name a name string * @returns 1 if true 0 otherwise */ int @@ -8863,13 +8727,12 @@ xmlXPathIsNodeType(const xmlChar *name) { } /** - * @param ctxt the XPath Parser context - * * [16] FunctionCall ::= FunctionName '(' ( Argument ( ',' Argument)*)? ')' * [17] Argument ::= Expr * * Compile a function call, the evaluation of all arguments are * pushed on the stack + * @param ctxt the XPath Parser context */ static void xmlXPathCompFunctionCall(xmlXPathParserContextPtr ctxt) { @@ -8933,8 +8796,6 @@ xmlXPathCompFunctionCall(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [15] PrimaryExpr ::= VariableReference * | '(' Expr ')' * | Literal @@ -8942,6 +8803,7 @@ xmlXPathCompFunctionCall(xmlXPathParserContextPtr ctxt) { * | FunctionCall * * Compile a primary expression. + * @param ctxt the XPath Parser context */ static void xmlXPathCompPrimaryExpr(xmlXPathParserContextPtr ctxt) { @@ -8968,8 +8830,6 @@ xmlXPathCompPrimaryExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [20] FilterExpr ::= PrimaryExpr * | FilterExpr Predicate * @@ -8979,6 +8839,7 @@ xmlXPathCompPrimaryExpr(xmlXPathParserContextPtr ctxt) { * be filtered does not evaluate to a node-set. The context node list * used for evaluating the expression in square brackets is the node-set * to be filtered listed in document order. + * @param ctxt the XPath Parser context */ static void @@ -8996,8 +8857,6 @@ xmlXPathCompFilterExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * Trickery: parse an XML name but without consuming the input flow * Needed to avoid insanity in the parser state. * @@ -9008,6 +8867,7 @@ xmlXPathCompFilterExpr(xmlXPathParserContextPtr ctxt) { * * [6] Names ::= Name (S Name)* * + * @param ctxt the XPath Parser context * @returns the Name parsed or NULL */ @@ -9044,14 +8904,13 @@ xmlXPathScanName(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [19] PathExpr ::= LocationPath * | FilterExpr * | FilterExpr '/' RelativeLocationPath * | FilterExpr '//' RelativeLocationPath * * Compile a path expression. + * @param ctxt the XPath Parser context */ static void @@ -9168,12 +9027,11 @@ xmlXPathCompPathExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [18] UnionExpr ::= PathExpr * | UnionExpr '|' PathExpr * * Compile an union expression. + * @param ctxt the XPath Parser context */ static void @@ -9196,12 +9054,11 @@ xmlXPathCompUnionExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [27] UnaryExpr ::= UnionExpr * | '-' UnaryExpr * * Compile an unary expression. + * @param ctxt the XPath Parser context */ static void @@ -9228,8 +9085,6 @@ xmlXPathCompUnaryExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [26] MultiplicativeExpr ::= UnaryExpr * | MultiplicativeExpr MultiplyOperator UnaryExpr * | MultiplicativeExpr 'div' UnaryExpr @@ -9237,6 +9092,7 @@ xmlXPathCompUnaryExpr(xmlXPathParserContextPtr ctxt) { * [34] MultiplyOperator ::= '*' * * Compile an Additive expression. + * @param ctxt the XPath Parser context */ static void @@ -9269,13 +9125,12 @@ xmlXPathCompMultiplicativeExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [25] AdditiveExpr ::= MultiplicativeExpr * | AdditiveExpr '+' MultiplicativeExpr * | AdditiveExpr '-' MultiplicativeExpr * * Compile an Additive expression. + * @param ctxt the XPath Parser context */ static void @@ -9300,8 +9155,6 @@ xmlXPathCompAdditiveExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [24] RelationalExpr ::= AdditiveExpr * | RelationalExpr '<' AdditiveExpr * | RelationalExpr '>' AdditiveExpr @@ -9314,6 +9167,7 @@ xmlXPathCompAdditiveExpr(xmlXPathParserContextPtr ctxt) { * * Compile a Relational expression, then push the result * on the stack + * @param ctxt the XPath Parser context */ static void @@ -9340,8 +9194,6 @@ xmlXPathCompRelationalExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [23] EqualityExpr ::= RelationalExpr * | EqualityExpr '=' RelationalExpr * | EqualityExpr '!=' RelationalExpr @@ -9353,6 +9205,7 @@ xmlXPathCompRelationalExpr(xmlXPathParserContextPtr ctxt) { * * Compile an Equality expression. * + * @param ctxt the XPath Parser context */ static void xmlXPathCompEqualityExpr(xmlXPathParserContextPtr ctxt) { @@ -9376,13 +9229,12 @@ xmlXPathCompEqualityExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [22] AndExpr ::= EqualityExpr * | AndExpr 'and' EqualityExpr * * Compile an AND expression. * + * @param ctxt the XPath Parser context */ static void xmlXPathCompAndExpr(xmlXPathParserContextPtr ctxt) { @@ -9401,14 +9253,13 @@ xmlXPathCompAndExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * @param sort whether to sort the resulting node set - * * [14] Expr ::= OrExpr * [21] OrExpr ::= AndExpr * | OrExpr 'or' AndExpr * * Parse and compile an expression + * @param ctxt the XPath Parser context + * @param sort whether to sort the resulting node set */ static void xmlXPathCompileExpr(xmlXPathParserContextPtr ctxt, int sort) { @@ -9451,13 +9302,12 @@ xmlXPathCompileExpr(xmlXPathParserContextPtr ctxt, int sort) { } /** - * @param ctxt the XPath Parser context - * @param filter act as a filter - * * [8] Predicate ::= '[' PredicateExpr ']' * [9] PredicateExpr ::= Expr * * Compile a predicate expression + * @param ctxt the XPath Parser context + * @param filter act as a filter */ static void xmlXPathCompPredicate(xmlXPathParserContextPtr ctxt, int filter) { @@ -9500,12 +9350,6 @@ xmlXPathCompPredicate(xmlXPathParserContextPtr ctxt, int filter) { } /** - * @param ctxt the XPath Parser context - * @param test pointer to a xmlXPathTestVal - * @param type pointer to a xmlXPathTypeVal - * @param prefix placeholder for a possible name prefix - * @param name current name token (optional) - * * ``` * [7] NodeTest ::= NameTest * | NodeType '(' ')' @@ -9520,6 +9364,11 @@ xmlXPathCompPredicate(xmlXPathParserContextPtr ctxt, int filter) { * | 'node' * ``` * + * @param ctxt the XPath Parser context + * @param test pointer to a xmlXPathTestVal + * @param type pointer to a xmlXPathTypeVal + * @param prefix placeholder for a possible name prefix + * @param name current name token (optional) * @returns the name found and updates `test`, `type` and `prefix` appropriately */ static xmlChar * @@ -9627,8 +9476,6 @@ xmlXPathCompNodeTest(xmlXPathParserContextPtr ctxt, xmlXPathTestVal *test, } /** - * @param name a preparsed name token - * * [6] AxisName ::= 'ancestor' * | 'ancestor-or-self' * | 'attribute' @@ -9643,6 +9490,7 @@ xmlXPathCompNodeTest(xmlXPathParserContextPtr ctxt, xmlXPathTestVal *test, * | 'preceding-sibling' * | 'self' * + * @param name a preparsed name token * @returns the axis or 0 */ static xmlXPathAxisVal @@ -9694,8 +9542,6 @@ xmlXPathIsAxisName(const xmlChar *name) { } /** - * @param ctxt the XPath Parser context - * * [4] Step ::= AxisSpecifier NodeTest Predicate* * | AbbreviatedStep * @@ -9713,6 +9559,7 @@ xmlXPathIsAxisName(const xmlChar *name) { * | 'range-to' '(' Expr ')' Predicate* * * Compile one step in a Location Path + * @param ctxt the XPath Parser context */ static void xmlXPathCompStep(xmlXPathParserContextPtr ctxt) { @@ -9794,14 +9641,13 @@ xmlXPathCompStep(xmlXPathParserContextPtr ctxt) { } /** - * @param ctxt the XPath Parser context - * * [3] RelativeLocationPath ::= Step * | RelativeLocationPath '/' Step * | AbbreviatedRelativeLocationPath * [11] AbbreviatedRelativeLocationPath ::= RelativeLocationPath '//' Step * * Compile a relative location path. + * @param ctxt the XPath Parser context */ static void xmlXPathCompRelativeLocationPath @@ -9836,8 +9682,6 @@ xmlXPathCompRelativeLocationPath } /** - * @param ctxt the XPath Parser context - * * [1] LocationPath ::= RelativeLocationPath * | AbsoluteLocationPath * [2] AbsoluteLocationPath ::= '/' RelativeLocationPath? @@ -9846,6 +9690,7 @@ xmlXPathCompRelativeLocationPath * '//' RelativeLocationPath * * Compile a location path + * @param ctxt the XPath Parser context */ static void xmlXPathCompLocationPath(xmlXPathParserContextPtr ctxt) { @@ -9884,16 +9729,16 @@ static int xmlXPathCompOpEval(xmlXPathParserContextPtr ctxt, xmlXPathStepOpPtr op); /** + * Filter a node set, keeping only nodes for which the predicate expression + * matches. Afterwards, keep only nodes between minPos and maxPos in the + * filtered result. + * * @param ctxt the XPath Parser context * @param set the node set to filter * @param filterOpIndex the index of the predicate/filter op * @param minPos minimum position in the filtered set (1-based) * @param maxPos maximum position in the filtered set (1-based) * @param hasNsNodes true if the node set may contain namespace nodes - * - * Filter a node set, keeping only nodes for which the predicate expression - * matches. Afterwards, keep only nodes between minPos and maxPos in the - * filtered result. */ static void xmlXPathNodeSetFilter(xmlXPathParserContextPtr ctxt, @@ -10017,16 +9862,16 @@ xmlXPathNodeSetFilter(xmlXPathParserContextPtr ctxt, } /** + * Filter a node set, keeping only nodes for which the sequence of predicate + * expressions matches. Afterwards, keep only nodes between minPos and maxPos + * in the filtered result. + * * @param ctxt the XPath Parser context * @param op the predicate op * @param set the node set to filter * @param minPos minimum position in the filtered set (1-based) * @param maxPos maximum position in the filtered set (1-based) * @param hasNsNodes true if the node set may contain namespace nodes - * - * Filter a node set, keeping only nodes for which the sequence of predicate - * expressions matches. Afterwards, keep only nodes between minPos and maxPos - * in the filtered result. */ static void xmlXPathCompOpEvalPredicate(xmlXPathParserContextPtr ctxt, @@ -10717,13 +10562,12 @@ xmlXPathCompOpEvalFilterFirst(xmlXPathParserContextPtr ctxt, xmlXPathStepOpPtr op, xmlNodePtr * first); /** - * @param ctxt the XPath parser context with the compiled expression - * @param op an XPath compiled operation - * @param first the first elem found so far - * * Evaluate the Precompiled XPath operation searching only the first * element in document order * + * @param ctxt the XPath parser context with the compiled expression + * @param op an XPath compiled operation + * @param first the first elem found so far * @returns the number of examined objects. */ static int @@ -10856,13 +10700,12 @@ xmlXPathCompOpEvalFirst(xmlXPathParserContextPtr ctxt, } /** - * @param ctxt the XPath parser context with the compiled expression - * @param op an XPath compiled operation - * @param last the last elem found so far - * * Evaluate the Precompiled XPath operation searching only the last * element in document order * + * @param ctxt the XPath parser context with the compiled expression + * @param op an XPath compiled operation + * @param last the last elem found so far * @returns the number of nodes traversed */ static int @@ -11066,10 +10909,10 @@ xmlXPathCompOpEvalFilterFirst(xmlXPathParserContextPtr ctxt, #endif /* XP_OPTIMIZED_FILTER_FIRST */ /** + * Evaluate the Precompiled XPath operation + * * @param ctxt the XPath parser context with the compiled expression * @param op an XPath compiled operation - * - * Evaluate the Precompiled XPath operation * @returns the number of nodes traversed */ static int @@ -11468,12 +11311,11 @@ xmlXPathCompOpEval(xmlXPathParserContextPtr ctxt, xmlXPathStepOpPtr op) } /** + * Evaluates if the expression evaluates to true. + * * @param ctxt the XPath parser context * @param op the step operation * @param isPredicate whether a predicate is evaluated - * - * Evaluates if the expression evaluates to true. - * * @returns 1 if true, 0 if false and -1 on API or internal errors. */ static int @@ -11561,9 +11403,9 @@ start: #ifdef XPATH_STREAMING /** - * @param pctxt the XPath parser context with the compiled expression - * * Evaluate the Precompiled Streamable XPath expression in the given context. + * + * @param pctxt the XPath parser context with the compiled expression */ static int xmlXPathRunStreamEval(xmlXPathParserContextPtr pctxt, xmlPatternPtr comp, @@ -11792,10 +11634,10 @@ return_1: #endif /* XPATH_STREAMING */ /** + * Evaluate the Precompiled XPath expression in the given context. + * * @param ctxt the XPath parser context with the compiled expression * @param toBool evaluate to a boolean result - * - * Evaluate the Precompiled XPath expression in the given context. */ static int xmlXPathRunEval(xmlXPathParserContextPtr ctxt, int toBool) @@ -11878,9 +11720,6 @@ xmlXPathRunEval(xmlXPathParserContextPtr ctxt, int toBool) ************************************************************************/ /** - * @param ctxt the XPath context - * @param res the Predicate Expression evaluation result - * * Evaluate a predicate result for the current node. * A PredicateExpr is evaluated by evaluating the Expr and converting * the result to a boolean. If the result is a number, the result will @@ -11890,6 +11729,8 @@ xmlXPathRunEval(xmlXPathParserContextPtr ctxt, int toBool) * is not a number, then the result will be converted as if by a call * to the boolean function. * + * @param ctxt the XPath context + * @param res the Predicate Expression evaluation result * @returns 1 if predicate is true, 0 otherwise */ int @@ -11915,9 +11756,6 @@ xmlXPathEvalPredicate(xmlXPathContextPtr ctxt, xmlXPathObjectPtr res) { } /** - * @param ctxt the XPath Parser context - * @param res the Predicate Expression evaluation result - * * Evaluate a predicate result for the current node. * A PredicateExpr is evaluated by evaluating the Expr and converting * the result to a boolean. If the result is a number, the result will @@ -11927,6 +11765,8 @@ xmlXPathEvalPredicate(xmlXPathContextPtr ctxt, xmlXPathObjectPtr res) { * is not a number, then the result will be converted as if by a call * to the boolean function. * + * @param ctxt the XPath Parser context + * @param res the Predicate Expression evaluation result * @returns 1 if predicate is true, 0 otherwise */ int @@ -11958,11 +11798,10 @@ xmlXPathEvaluatePredicateResult(xmlXPathParserContextPtr ctxt, #ifdef XPATH_STREAMING /** - * @param ctxt an XPath context - * @param str the XPath expression - * * Try to compile the XPath expression as a streamable subset. * + * @param ctxt an XPath context + * @param str the XPath expression * @returns the compiled expression or NULL if failed to compile. */ static xmlXPathCompExprPtr @@ -12120,11 +11959,10 @@ xmlXPathOptimizeExpression(xmlXPathParserContextPtr pctxt, } /** - * @param ctxt an XPath context - * @param str the XPath expression - * * Compile an XPath expression * + * @param ctxt an XPath context + * @param str the XPath expression * @returns the xmlXPathCompExprPtr resulting from the compilation or NULL. * the caller has to free the object. */ @@ -12206,10 +12044,9 @@ xmlXPathCtxtCompile(xmlXPathContextPtr ctxt, const xmlChar *str) { } /** - * @param str the XPath expression - * * Compile an XPath expression * + * @param str the XPath expression * @returns the xmlXPathCompExprPtr resulting from the compilation or NULL. * the caller has to free the object. */ @@ -12219,14 +12056,13 @@ xmlXPathCompile(const xmlChar *str) { } /** + * Evaluate the Precompiled XPath expression in the given context. + * The caller has to free `resObj`. + * * @param comp the compiled XPath expression * @param ctxt the XPath context * @param resObjPtr the resulting XPath object or NULL * @param toBool 1 if only a boolean result is requested - * - * Evaluate the Precompiled XPath expression in the given context. - * The caller has to free `resObj`. - * * @returns the xmlXPathObjectPtr resulting from the evaluation or NULL. * the caller has to free the object. */ @@ -12270,11 +12106,10 @@ xmlXPathCompiledEvalInternal(xmlXPathCompExprPtr comp, } /** - * @param comp the compiled XPath expression - * @param ctx the XPath context - * * Evaluate the Precompiled XPath expression in the given context. * + * @param comp the compiled XPath expression + * @param ctx the XPath context * @returns the xmlXPathObjectPtr resulting from the evaluation or NULL. * the caller has to free the object. */ @@ -12288,12 +12123,11 @@ xmlXPathCompiledEval(xmlXPathCompExprPtr comp, xmlXPathContextPtr ctx) } /** - * @param comp the compiled XPath expression - * @param ctxt the XPath context - * * Applies the XPath boolean() function on the result of the given * compiled expression. * + * @param comp the compiled XPath expression + * @param ctxt the XPath context * @returns 1 if the expression evaluated to true, 0 if to false and * -1 in API and internal errors. */ @@ -12305,12 +12139,12 @@ xmlXPathCompiledEvalToBoolean(xmlXPathCompExprPtr comp, } /** - * @param ctxt the XPath Parser context + * Parse and evaluate an XPath expression in the given context, + * then push the result on the context stack * * @deprecated Internal function, don't use. * - * Parse and evaluate an XPath expression in the given context, - * then push the result on the context stack + * @param ctxt the XPath Parser context */ void xmlXPathEvalExpr(xmlXPathParserContextPtr ctxt) { @@ -12363,11 +12197,10 @@ xmlXPathEvalExpr(xmlXPathParserContextPtr ctxt) { } /** - * @param str the XPath expression - * @param ctx the XPath context - * * Evaluate the XPath Location Path in the given context. * + * @param str the XPath expression + * @param ctx the XPath context * @returns the xmlXPathObjectPtr resulting from the evaluation or NULL. * the caller has to free the object. */ @@ -12402,12 +12235,11 @@ xmlXPathEval(const xmlChar *str, xmlXPathContextPtr ctx) { } /** - * @param node the node to to use as the context node - * @param ctx the XPath context - * * Sets 'node' as the context node. The node must be in the same * document as that associated with the context. * + * @param node the node to to use as the context node + * @param ctx the XPath context * @returns -1 in case of error or 0 if successful */ int @@ -12423,13 +12255,12 @@ xmlXPathSetContextNode(xmlNodePtr node, xmlXPathContextPtr ctx) { } /** - * @param node the node to to use as the context node - * @param str the XPath expression - * @param ctx the XPath context - * * Evaluate the XPath Location Path in the given context. The node 'node' * is set as the context node. The context node is not restored. * + * @param node the node to to use as the context node + * @param str the XPath expression + * @param ctx the XPath context * @returns the xmlXPathObjectPtr resulting from the evaluation or NULL. * the caller has to free the object. */ @@ -12443,11 +12274,10 @@ xmlXPathNodeEval(xmlNodePtr node, const xmlChar *str, xmlXPathContextPtr ctx) { } /** - * @param str the XPath expression - * @param ctxt the XPath context - * * Alias for xmlXPathEval(). * + * @param str the XPath expression + * @param ctxt the XPath context * @returns the xmlXPathObjectPtr resulting from the evaluation or NULL. * the caller has to free the object. */ @@ -12457,11 +12287,11 @@ xmlXPathEvalExpression(const xmlChar *str, xmlXPathContextPtr ctxt) { } /** - * @param ctxt the XPath context + * Registers all default XPath functions in this context * * @deprecated No-op since 2.14.0. * - * Registers all default XPath functions in this context + * @param ctxt the XPath context */ void xmlXPathRegisterAllFunctions(xmlXPathContextPtr ctxt ATTRIBUTE_UNUSED) diff --git a/xpointer.c b/xpointer.c index 73f38200..a95000e8 100644 --- a/xpointer.c +++ b/xpointer.c @@ -54,12 +54,12 @@ ************************************************************************/ /** + * Handle an XPointer error + * * @param ctxt an XPTR evaluation context * @param code error code * @param msg error message * @param extra extra information - * - * Handle an XPointer error */ static void LIBXML_ATTR_FORMAT(3,0) xmlXPtrErr(xmlXPathParserContextPtr ctxt, int code, @@ -118,7 +118,6 @@ xmlXPtrErr(xmlXPathParserContextPtr ctxt, int code, /** * @param cur the node * @param no the child number - * * @returns the `no`'th element child of `cur` or NULL */ static xmlNodePtr @@ -213,9 +212,6 @@ xmlXPtrGetChildNo(xmlXPathParserContextPtr ctxt, int indx) { } /** - * @param ctxt the XPointer Parser context - * @param name the preparsed Scheme for the XPtrPart - * * XPtrPart ::= 'xpointer' '(' XPtrExpr ')' * | Scheme '(' SchemeSpecificExpr ')' * @@ -243,6 +239,8 @@ xmlXPtrGetChildNo(xmlXPathParserContextPtr ctxt, int indx) { * string and if the scheme is 'xpointer' it will call the XPath interpreter. * * TODO: there is no new scheme registration mechanism + * @param ctxt the XPointer Parser context + * @param name the preparsed Scheme for the XPtrPart */ static void @@ -380,9 +378,6 @@ xmlXPtrEvalXPtrPart(xmlXPathParserContextPtr ctxt, xmlChar *name) { } /** - * @param ctxt the XPointer Parser context - * @param name the preparsed Scheme for the first XPtrPart - * * FullXPtr ::= XPtrPart (S? XPtrPart)* * * As the specs says: @@ -404,6 +399,8 @@ xmlXPtrEvalXPtrPart(xmlXPathParserContextPtr ctxt, xmlChar *name) { * * Parse and evaluate a Full XPtr i.e. possibly a cascade of XPath based * expressions or other schemes. + * @param ctxt the XPointer Parser context + * @param name the preparsed Scheme for the first XPtrPart */ static void xmlXPtrEvalFullXPtr(xmlXPathParserContextPtr ctxt, xmlChar *name) { @@ -459,14 +456,13 @@ xmlXPtrEvalFullXPtr(xmlXPathParserContextPtr ctxt, xmlChar *name) { } /** - * @param ctxt the XPointer Parser context - * @param name a possible ID name of the child sequence - * * ChildSeq ::= '/1' ('/' [0-9]*)* * | Name ('/' [0-9]*)+ * * Parse and evaluate a Child Sequence. This routine also handle the * case of a Bare Name used to get a document ID. + * @param ctxt the XPointer Parser context + * @param name a possible ID name of the child sequence */ static void xmlXPtrEvalChildSeq(xmlXPathParserContextPtr ctxt, xmlChar *name) { @@ -510,13 +506,12 @@ xmlXPtrEvalChildSeq(xmlXPathParserContextPtr ctxt, xmlChar *name) { /** - * @param ctxt the XPointer Parser context - * * XPointer ::= Name * | ChildSeq * | FullXPtr * * Parse and evaluate an XPointer + * @param ctxt the XPointer Parser context */ static void xmlXPtrEvalXPointer(xmlXPathParserContextPtr ctxt) { @@ -564,13 +559,12 @@ xmlXPtrEvalXPointer(xmlXPathParserContextPtr ctxt) { ************************************************************************/ /** + * Create a new XPointer context + * * @param doc the XML document * @param here the node that directly contains the XPointer being evaluated or NULL * @param origin the element from which a user or program initiated traversal of * the link, or NULL. - * - * Create a new XPointer context - * * @returns the xmlXPathContext just allocated. */ xmlXPathContextPtr @@ -587,11 +581,10 @@ xmlXPtrNewContext(xmlDocPtr doc, xmlNodePtr here, xmlNodePtr origin) { } /** - * @param str the XPointer expression - * @param ctx the XPointer context - * * Evaluate the XPath Location Path in the given context. * + * @param str the XPointer expression + * @param ctx the XPointer context * @returns the xmlXPathObjectPtr resulting from the evaluation or NULL. * the caller has to free the object. */