new API building Python script, does the C parsing directly, generates a

* doc/apibuild.py doc/libxml2-api.xml doc/Makefile.am: new API
  building Python script, does the C parsing directly, generates
  a better API description including structure fieds defs and
  enums. Still a couple of bugs, but good enough for the python
  wrappers now.
* DOCBparser.c SAX.c nanohttp.c parser.c parserInternals.c tree.c
  valid.c xmlIO.c xmlmemory.c xmlreader.c xmlregexp.c xmlschemas.c
  include/libxml/schemasInternals.h include/libxml/tree.h: more
  cleanup based on the python analysis script reports.
* libxml.spec.in: make sure the API XML description is part of the
  devel package.
Daniel

ChangeLog

@@ -1,3 +1,17 @@
+Wed Dec 11 14:54:47 CET 2002 Daniel Veillard <daniel@veillard.com>
+
+	* doc/apibuild.py doc/libxml2-api.xml doc/Makefile.am: new API
+	  building Python script, does the C parsing directly, generates
+	  a better API description including structure fieds defs and
+	  enums. Still a couple of bugs, but good enough for the python
+	  wrappers now.
+	* DOCBparser.c SAX.c nanohttp.c parser.c parserInternals.c tree.c
+	  valid.c xmlIO.c xmlmemory.c xmlreader.c xmlregexp.c xmlschemas.c
+	  include/libxml/schemasInternals.h include/libxml/tree.h: more
+	  cleanup based on the python analysis script reports.
+	* libxml.spec.in: make sure the API XML description is part of the
+	  devel package.
+
 Tue Dec 10 16:16:34 CET 2002 Daniel Veillard <daniel@veillard.com>
 
 	* DOCBparser.c HTMLparser.c c14n.c debugXML.c encoding.c hash.c

DOCBparser.c

@@ -68,18 +68,6 @@ struct _docbEntityDesc {
     const char *desc;   /* the description */
 };
 
-#if 0
-docbElemDescPtr        docbTagLookup   (const xmlChar *tag); 
-docbEntityDescPtr      docbEntityLookup(const xmlChar *name);
-docbEntityDescPtr      docbEntityValueLookup(int value);
-
-int                    docbIsAutoClosed(docbDocPtr doc,
-                                        docbNodePtr elem);
-int                    docbAutoCloseTag(docbDocPtr doc,
-                                        const xmlChar *name,
-                                        docbNodePtr elem);
-
-#endif
 static int             docbParseCharRef(docbParserCtxtPtr ctxt);
 static xmlEntityPtr    docbParseEntityRef(docbParserCtxtPtr ctxt,
                                         xmlChar **str);

SAX.c

@@ -33,7 +33,7 @@
  * getPublicId:
  * @ctx: the user data (XML parser context)
  *
- * Return the public ID e.g. "-//SGMLSOURCE//DTD DEMO//EN"
+ * Provides the public ID e.g. "-//SGMLSOURCE//DTD DEMO//EN"
  *
  * Returns a xmlChar *
  */
@@ -48,7 +48,7 @@ getPublicId(void *ctx ATTRIBUTE_UNUSED)
  * getSystemId:
  * @ctx: the user data (XML parser context)
  *
- * Return the system ID, basically URL or filename e.g.
+ * Provides the system ID, basically URL or filename e.g.
  * http://www.sgmlsource.com/dtds/memo.dtd
  *
  * Returns a xmlChar *
@@ -64,7 +64,7 @@ getSystemId(void *ctx)
  * getLineNumber:
  * @ctx: the user data (XML parser context)
  *
- * Return the line number of the current parsing point.
+ * Provide the line number of the current parsing point.
  *
  * Returns an int
  */
@@ -79,7 +79,7 @@ getLineNumber(void *ctx)
  * getColumnNumber:
  * @ctx: the user data (XML parser context)
  *
- * Return the column number of the current parsing point.
+ * Provide the column number of the current parsing point.
  *
  * Returns an int
  */

doc/Makefile.am

@@ -21,7 +21,8 @@ APIPAGES=APIconstructors.html APIfiles.html APIfunctions.html \
 EXTRA_DIST=xmlcatalog_man.xml tutorial/*.html tutorial/*.c tutorial/*.pdf \
            tutorial/images/*.png tutorial/images/callouts/*.png \
 	   API*.html *.1 *.xsl *.html *.gif w3c.png html/*.html \
-	   html/*.sgml libxml2-api.xml parsedecl.py index.py search.php
+	   html/*.sgml libxml2-api.xml parsedecl.py index.py search.php \
+	   apibuild.py
 
 
 man_MANS = xmllint.1 xmlcatalog.1
@@ -52,8 +53,8 @@ xml: sgml
 	-@(for s in sgml/*.sgml ; do name=`basename $$s .sgml` ; \
 	   xmllint --sgml $$s > xml/"$$name".xml ; done)
 
-libxml2-api.xml libxml2-refs.xml: xml parsedecl.py libxml-decl.txt libxml-decl-list.txt
+libxml2-api.xml: apibuild.py ../include/libxml/*.h
-	-(./parsedecl.py)
+	-(./apibuild.py)
 
 api: libxml2-api.xml libxml2-refs.xml
 

include/libxml/schemasInternals.h

@@ -139,10 +139,17 @@ struct _xmlSchemaAttributeGroup {
 
 
 /**
- * Schemas type definition.
+ * XML_SCHEMAS_TYPE_MIXED:
+ *
+ * the element content type is mixed
  */
 #define XML_SCHEMAS_TYPE_MIXED		1 << 0
 
+/**
+ * _xmlSchemaType:
+ *
+ * Schemas type definition.
+ */
 struct _xmlSchemaType {
     xmlSchemaTypeType type;	/* The kind of type */
     struct _xmlSchemaType *next;/* the next type if in a sequence ... */
@@ -166,17 +173,53 @@ struct _xmlSchemaType {
 };
 
 /**
+ * xmlSchemaElement:
  * An element definition.
  *
  * xmlSchemaType, xmlSchemaFacet and xmlSchemaElement start of
  * structures must be kept similar
  */
+/**
+ * XML_SCHEMAS_ELEM_NILLABLE:
+ *
+ * the element is nillable
+ */
 #define XML_SCHEMAS_ELEM_NILLABLE	1 << 0
+/**
+ * XML_SCHEMAS_ELEM_GLOBAL:
+ *
+ * the element is global
+ */
 #define XML_SCHEMAS_ELEM_GLOBAL		1 << 1
+/**
+ * XML_SCHEMAS_ELEM_DEFAULT:
+ *
+ * the element has a default value
+ */
 #define XML_SCHEMAS_ELEM_DEFAULT	1 << 2
+/**
+ * XML_SCHEMAS_ELEM_FIXED:
+ *
+ * the element has a fixed value
+ */
 #define XML_SCHEMAS_ELEM_FIXED		1 << 3
+/**
+ * XML_SCHEMAS_ELEM_ABSTRACT:
+ *
+ * the element is abstract
+ */
 #define XML_SCHEMAS_ELEM_ABSTRACT	1 << 4
+/**
+ * XML_SCHEMAS_ELEM_TOPLEVEL:
+ *
+ * the element is top level
+ */
 #define XML_SCHEMAS_ELEM_TOPLEVEL	1 << 5
+/**
+ * XML_SCHEMAS_ELEM_REF:
+ *
+ * the element is a reference to a type
+ */
 #define XML_SCHEMAS_ELEM_REF		1 << 6
 
 typedef struct _xmlSchemaElement xmlSchemaElement;
@@ -208,15 +251,34 @@ struct _xmlSchemaElement {
     xmlSchemaContentType contentType;
 };
 
-/**
+/*
- * An facet definition.
+ * XML_SCHEMAS_FACET_UNKNOWN:
  *
+ * unknown facet handling
  */
 #define XML_SCHEMAS_FACET_UNKNOWN	0
+/*
+ * XML_SCHEMAS_FACET_PRESERVE:
+ *
+ * preserve the type of the facet
+ */
 #define XML_SCHEMAS_FACET_PRESERVE	1
+/*
+ * XML_SCHEMAS_FACET_REPLACE:
+ *
+ * replace the type of the facet
+ */
 #define XML_SCHEMAS_FACET_REPLACE	2
+/*
+ * XML_SCHEMAS_FACET_COLLAPSE:
+ *
+ * collapse the types of the facet
+ */
 #define XML_SCHEMAS_FACET_COLLAPSE	3
 
+/**
+ * A facet definition.
+ */
 struct _xmlSchemaFacet {
     xmlSchemaTypeType type;	/* The kind of type */
     struct _xmlSchemaFacet *next;/* the next type if in a sequence ... */
@@ -243,10 +305,22 @@ struct _xmlSchemaNotation {
 };
 
 /**
- * A Schemas definition
+ * XML_SCHEMAS_QUALIF_ELEM:
+ *
+ * the shemas requires qualified elements
  */
 #define XML_SCHEMAS_QUALIF_ELEM		1 << 0
+/**
+ * XML_SCHEMAS_QUALIF_ATTR:
+ *
+ * the shemas requires qualified attributes
+ */
 #define XML_SCHEMAS_QUALIF_ATTR		1 << 1
+/**
+ * _xmlSchema:
+ *
+ * A Schemas definition
+ */
 struct _xmlSchema {
     xmlChar *name;        /* schema name */
     xmlChar *targetNamespace;     /* the target namespace */

include/libxml/tree.h

@@ -240,7 +240,7 @@ struct _xmlElementContent {
     struct _xmlElementContent *c1;	/* first child */
     struct _xmlElementContent *c2;	/* second child */
     struct _xmlElementContent *parent;	/* parent */
-    const xmlChar             *prefix;	/* Element name */
+    const xmlChar             *prefix;	/* Namespace prefix */
 };
 
 /**

libxml.spec.in

@@ -115,7 +115,7 @@ rm -fr %{buildroot}
 %doc %{_mandir}/man1/xml2-config.1*
 %doc AUTHORS ChangeLog NEWS README Copyright TODO
 %doc doc/*.html doc/html doc/*.gif doc/*.png
-%doc doc/tutorial
+%doc doc/tutorial doc/libxml2-api.xml
 
 %{_libdir}/lib*.so
 %{_libdir}/*a

nanohttp.c

@@ -1422,6 +1422,8 @@ xmlNanoHTTPAuthHeader(void *ctx) {
  * xmlNanoHTTPContentLength:
  * @ctx:  the HTTP context
  *
+ * Provides the specified content length from the HTTP header.
+ *
  * Return the specified content length from the HTTP header.  Note that
  * a value of -1 indicates that the content length element was not included in
  * the response header.
@@ -1439,6 +1441,8 @@ xmlNanoHTTPContentLength( void * ctx ) {
  * @ptr:  pointer to set to the content buffer.
  * @len:  integer pointer to hold the length of the content
  *
+ * Check if all the content was read
+ *
  * Returns 0 if all the content was read and available, returns
  * -1 if received content length was less than specified or an error 
  * occurred.

parser.c

@@ -4364,6 +4364,7 @@ xmlParseAttributeListDecl(xmlParserCtxtPtr ctxt) {
 /**
  * xmlParseElementMixedContentDecl:
  * @ctxt:  an XML parser context
+ * @inputchk:  the input used for the current entity, needed for boundary checks
  *
  * parse the declaration for a Mixed Element content
  * The leading '(' and spaces have been skipped in xmlParseElementContentDecl
@@ -4491,6 +4492,7 @@ xmlParseElementMixedContentDecl(xmlParserCtxtPtr ctxt, xmlParserInputPtr inputch
 /**
  * xmlParseElementChildrenContentDecl:
  * @ctxt:  an XML parser context
+ * @inputchk:  the input used for the current entity, needed for boundary checks
  *
  * parse the declaration for a Mixed Element content
  * The leading '(' and spaces have been skipped in xmlParseElementContentDecl

parserInternals.c

@@ -2712,8 +2712,8 @@ xmlCheckLanguageID(const xmlChar *lang) {
 /**
  * xmlDecodeEntities:
  * @ctxt:  the parser context
- * @what:  combination of XML_SUBSTITUTE_REF and XML_SUBSTITUTE_PEREF
  * @len:  the len to decode (in bytes !), -1 for no size limit
+ * @what:  combination of XML_SUBSTITUTE_REF and XML_SUBSTITUTE_PEREF
  * @end:  an end marker xmlChar, 0 if none
  * @end2:  an end marker xmlChar, 0 if none
  * @end3:  an end marker xmlChar, 0 if none

python/libxml2class.txt

@@ -38,6 +38,7 @@ newCatalog()
 parseCatalogFile()
 
 # functions from module debugXML
+boolToText()
 debugDumpString()
 shellPrintXPathError()
 
@@ -151,13 +152,6 @@ validateNamesValue()
 validateNmtokenValue()
 validateNmtokensValue()
 
-# functions from module wincecompat
-close()
-getenv()
-read()
-strerror()
-write()
-
 # functions from module xmlIO
 checkFilename()
 cleanupInputCallbacks()
@@ -171,9 +165,16 @@ registerDefaultInputCallbacks()
 registerDefaultOutputCallbacks()
 registerHTTPPostCallbacks()
 
+# functions from module xmlmemory.c
+mallocBreakpoint()
+
 # functions from module xmlregexp
 regexpCompile()
 
+# functions from module xmlschemastypes
+schemaCleanupTypes()
+schemaInitTypes()
+
 # functions from module xmlunicode
 uCSIsAlphabeticPresentationForms()
 uCSIsArabic()
@@ -394,6 +395,9 @@ Class xmlNode(xmlCore)
     unsetNsProp()
     unsetProp()
 
+    # functions from module tree.c
+    newReconciliedNs()
+
     # functions from module valid
     isID()
     isRef()
@@ -421,6 +425,9 @@ Class xmlNode(xmlCore)
     xpathNextPrecedingSibling()
     xpathNextSelf()
 
+    # functions from module xpointer.c
+    xpointerAdvanceNode()
+
 
 Class xmlDoc(xmlNode)
 
@@ -441,6 +448,9 @@ Class xmlDoc(xmlNode)
     htmlSaveFileFormat()
     htmlSetMetaEncoding()
 
+    # functions from module HTMLtree.c
+    htmlNodeDumpOutput()
+
     # functions from module debugXML
     debugDumpDocument()
     debugDumpDocumentHead()
@@ -456,6 +466,9 @@ Class xmlDoc(xmlNode)
     encodeSpecialChars()
     parameterEntity()
 
+    # functions from module parserInternals.c
+    upgradeOldNs()
+
     # functions from module tree
     copyDoc()
     createIntSubset()
@@ -623,6 +636,15 @@ Class xpathParserContext()
     xpathTrueFunction()
     xpathValueFlipSign()
     xpatherror()
+
+    # functions from module xpointer.c
+    xpointerEndPointFunction()
+    xpointerHereFunction()
+    xpointerOriginFunction()
+    xpointerRangeFunction()
+    xpointerRangeInsideFunction()
+    xpointerStartPointFunction()
+    xpointerStringRangeFunction()
 Class parserCtxt()
     # accessors
     doc()
@@ -641,6 +663,9 @@ Class parserCtxt()
     htmlParseDocument()
     htmlParseElement()
 
+    # functions from module HTMLparser.c
+    htmlDecodeEntities()
+
     # functions from module parser
     clearParserCtxt()
     freeParserCtxt()
@@ -648,8 +673,13 @@ Class parserCtxt()
     parseChunk()
     parseDocument()
     parseExtParsedEnt()
+    setupParserForBuffer()
     stopParser()
 
+    # functions from module parser.c
+    parseAttValueComplex()
+    parseCharDataComplex()
+
     # functions from module parserInternals
     decodeEntities()
     namespaceParseNCName()
@@ -713,6 +743,9 @@ Class xmlDtd(xmlNode)
     dtdQAttrDesc()
     dtdQElementDesc()
 
+    # functions from module valid.c
+    scanAttributeDecl()
+
 
 Class xmlNs(xmlNode)
 

tree.c

@@ -899,8 +899,9 @@ xmlStringGetNodeList(xmlDocPtr doc, const xmlChar *value) {
  * @list:  a Node list
  * @inLine:  should we replace entity contents or show their external form
  *
- * Returns the string equivalent to the text contained in the Node list
+ * Build the string equivalent to the text contained in the Node list
  * made of TEXTs and ENTITY_REFs
+ *
  * Returns a pointer to the string copy, the caller must free it with xmlFree().
  */
 xmlChar *
@@ -977,7 +978,7 @@ xmlNodeListGetString(xmlDocPtr doc, xmlNodePtr list, int inLine)
  * @list:  a Node list
  * @inLine:  should we replace entity contents or show their external form
  *
- * Returns the string equivalent to the text contained in the Node list
+ * Builds the string equivalent to the text contained in the Node list
  * made of TEXTs and ENTITY_REFs, contrary to xmlNodeListGetString()
  * this function doesn't do any character encoding handling.
  *
@@ -7470,6 +7471,8 @@ xmlSaveFormatFileTo(xmlOutputBufferPtr buf, xmlDocPtr cur, const char *encoding,
  * @encoding:  the name of the encoding to use or NULL.
  * @format:  should formatting spaces be added.
  *
+ * Dump an XML document to a file or an URL.
+ *
  * Returns the number of bytes written or -1 in case of error.
  */
 int

valid.c

@@ -3825,6 +3825,7 @@ xmlValidateOneAttribute(xmlValidCtxtPtr ctxt, xmlDocPtr doc,
  * @ctxt:  the validation context
  * @doc:  a document instance
  * @elem:  an element instance
+ * @prefix:  the namespace prefix
  * @ns:  an namespace declaration instance
  * @value:  the attribute value (without entities processing)
  *

xmlIO.c

@@ -246,7 +246,7 @@ xmlCleanupOutputCallbacks(void)
  ************************************************************************/
 
 /**
- * xmlCheckFilename
+ * xmlCheckFilename:
  * @path:  the path to check
  *
  * function checks to see if @path is a valid source
@@ -461,6 +461,8 @@ xmlFileWrite (void * context, const char * buffer, int len) {
  * @context:  the I/O context
  *
  * Close an I/O channel
+ *
+ * Returns 0 or -1 in case of error
  */
 int
 xmlFileClose (void * context) {
@@ -1033,7 +1035,7 @@ xmlIOHTTPOpen (const char *filename) {
 }
 
 /**
- * xmlIOHTTPOpenW
+ * xmlIOHTTPOpenW:
  * @post_uri:  The destination URI for the document
  * @compression:  The compression desired for the document.
  *
@@ -1176,6 +1178,8 @@ xmlIOHTTPWrite( void * context, const char * buffer, int len ) {
  * @context:  the I/O context
  *
  * Close an HTTP I/O channel
+ *
+ * Returns 0
  */
 int
 xmlIOHTTPClose (void * context) {
@@ -1396,6 +1400,8 @@ xmlIOFTPRead(void * context, char * buffer, int len) {
  * @context:  the I/O context
  *
  * Close an FTP I/O channel
+ *
+ * Returns 0
  */
 int
 xmlIOFTPClose (void * context) {
@@ -1524,7 +1530,7 @@ xmlRegisterDefaultOutputCallbacks
 
 #ifdef LIBXML_HTTP_ENABLED
 /**
- * xmlRegisterHTTPPostCallbacks
+ * xmlRegisterHTTPPostCallbacks:
  *
  * By default, libxml submits HTTP output requests using the "PUT" method.
  * Calling this method changes the HTTP output method to use the "POST"

xmlmemory.c

@@ -427,7 +427,7 @@ xmlMemoryStrdup(const char *str) {
 /**
  * xmlMemUsed:
  *
- * returns the amount of memory currently allocated
+ * Provides the amount of memory currently allocated
  *
  * Returns an int representing the amount of memory allocated.
  */
@@ -754,12 +754,12 @@ xmlMemSetup(xmlFreeFunc freeFunc, xmlMallocFunc mallocFunc,
 
 /**
  * xmlMemGet:
- * @freeFunc: the free() function in use
+ * @freeFunc: place to save the free() function in use
- * @mallocFunc: the malloc() function in use
+ * @mallocFunc: place to save the malloc() function in use
- * @reallocFunc: the realloc() function in use
+ * @reallocFunc: place to save the realloc() function in use
- * @strdupFunc: the strdup() function in use
+ * @strdupFunc: place to save the strdup() function in use
  *
- * Return the memory access functions set currently in use
+ * Provides the memory access functions set currently in use
  *
  * Returns 0 on success
  */

xmlreader.c

@@ -482,7 +482,7 @@ xmlFreeTextReader(xmlTextReaderPtr reader) {
  * xmlTextReaderAttributeCount:
  * @reader:  the xmlTextReaderPtr used
  *
- * Returns the number of attributes of the current node
+ * Provides the number of attributes of the current node
  *
  * Returns 0 i no attributes, -1 in case of error or the attribute count
  */

xmlregexp.c

@@ -3961,6 +3961,8 @@ xmlFreeAutomata(xmlAutomataPtr am) {
  * xmlAutomataGetInitState:
  * @am: an automata
  *
+ * Initial state lookup
+ *
  * Returns the initial state of the automata
  */
 xmlAutomataStatePtr
@@ -4028,7 +4030,8 @@ xmlAutomataNewTransition(xmlAutomataPtr am, xmlAutomataStatePtr from,
  * @to: the target point of the transition or NULL
  * @token: the input string associated to that transition
  * @min:  the minimum successive occurences of token
- * @min:  the maximum successive occurences of token
+ * @max:  the maximum successive occurences of token
+ * @data:  data associated to the transition
  *
  * If @to is NULL, this create first a new target state in the automata
  * and then adds a transition from the @from state to the target state
@@ -4077,7 +4080,8 @@ xmlAutomataNewCountTrans(xmlAutomataPtr am, xmlAutomataStatePtr from,
  * @to: the target point of the transition or NULL
  * @token: the input string associated to that transition
  * @min:  the minimum successive occurences of token
- * @min:  the maximum successive occurences of token
+ * @max:  the maximum successive occurences of token
+ * @data:  data associated to the transition
  *
  * If @to is NULL, this create first a new target state in the automata
  * and then adds a transition from the @from state to the target state
@@ -4153,7 +4157,7 @@ xmlAutomataNewState(xmlAutomataPtr am) {
 }
 
 /**
- * xmlAutomataNewTransition:
+ * xmlAutomataNewEpsilon:
  * @am: an automata
  * @from: the starting point of the transition
  * @to: the target point of the transition or NULL
@@ -4180,6 +4184,7 @@ xmlAutomataNewEpsilon(xmlAutomataPtr am, xmlAutomataStatePtr from,
  * @am: an automata
  * @from: the starting point of the transition
  * @to: the target point of the transition or NULL
+ * @lax: allow to transition if not all all transitions have been activated
  *
  * If @to is NULL, this create first a new target state in the automata
  * and then adds a an ALL transition from the @from state to the

xmlschemas.c

@@ -5401,7 +5401,7 @@ xmlSchemaFreeValidCtxt(xmlSchemaValidCtxtPtr ctxt) {
  * @ctxt:  a schema validation context
  * @err:  the error function
  * @warn: the warning function
- * @ctxt: the functions context
+ * @ctx: the functions context
  *
  * Set the error and warning callback informations
  */