Commit 9d06d300 authored by Daniel Veillard's avatar Daniel Veillard

Build a new version hopefully near complete and fully documented of the

* doc/libxml2-api.xml doc/parsedecl.py: Build a new version
  hopefully near complete and fully documented of the API in XML
* HTMLtree.c SAX.c debugXML.c error.c globals.c parser.c tree.c
 xmlIO.c xmlmemory.c include/libxml/catalog.h include/libxml/hash.h
 include/libxml/list.h include/libxml/parser.h include/libxml/tree.h
 include/libxml/parserInternals.h include/libxml/valid.hi
 include/libxml/xmlIO.h include/libxml/xmlerror.hi
 include/libxml/xmlmemory.h include/libxml/xmlversion.h.ini
 include/libxml/xpath.h include/libxml/xpathInternals.h:
  Cleaned up the doc comments a lot in the process, the interface
  coverage is now 100%
Daniel
parent 2d1464fb
Tue Jan 22 19:12:06 CET 2002 Daniel Veillard <daniel@veillard.com>
* doc/libxml2-api.xml doc/parsedecl.py: Build a new version
hopefully near complete and fully documented of the API in XML
* HTMLtree.c SAX.c debugXML.c error.c globals.c parser.c tree.c
xmlIO.c xmlmemory.c include/libxml/catalog.h include/libxml/hash.h
include/libxml/list.h include/libxml/parser.h include/libxml/tree.h
include/libxml/parserInternals.h include/libxml/valid.hi
include/libxml/xmlIO.h include/libxml/xmlerror.hi
include/libxml/xmlmemory.h include/libxml/xmlversion.h.ini
include/libxml/xpath.h include/libxml/xpathInternals.h:
Cleaned up the doc comments a lot in the process, the interface
coverage is now 100%
Tue Jan 22 00:12:58 CET 2002 Daniel Veillard <daniel@veillard.com>
* doc/libxml2-api.xml doc/parsedecl.py: improved the script to
......
......@@ -1123,6 +1123,7 @@ htmlNodeDumpOutput(xmlOutputBufferPtr buf, xmlDocPtr doc,
* @buf: the HTML buffer output
* @cur: the document
* @encoding: the encoding string
* @format: should formatting spaces been added
*
* Dump an HTML document.
*/
......
......@@ -1662,7 +1662,7 @@ cdataBlock(void *ctx, const xmlChar *value, int len)
}
/**
* xmlDefaultSAXHandlerInit:
* initxmlDefaultSAXHandler:
* @hdlr: the SAX handler
* @warning: flag if non-zero sets the handler warning procedure
*
......@@ -1723,9 +1723,8 @@ xmlDefaultSAXHandlerInit(void)
#ifdef LIBXML_HTML_ENABLED
/**
* inithtmlDefaultSAXHandlerInit:
* inithtmlDefaultSAXHandler:
* @hdlr: the SAX handler
* @warning: flag if non-zero sets the handler warning procedure
*
* Initialize the default HTML SAX handler
*/
......@@ -1782,9 +1781,8 @@ htmlDefaultSAXHandlerInit(void)
#ifdef LIBXML_DOCB_ENABLED
/**
* initdocbDefaultSAXHandlerInit:
* initdocbDefaultSAXHandler:
* @hdlr: the SAX handler
* @warning: flag if non-zero sets the handler warning procedure
*
* Initialize the default DocBook SAX handler
*/
......
......@@ -1307,7 +1307,7 @@ xmlShellPrintNode(xmlNodePtr node)
/**
* xmlShellPrintXPathResult:
* list: a valid result generated by an xpath evaluation
* @list: a valid result generated by an xpath evaluation
*
* Prints result to stdout
*/
......@@ -1813,7 +1813,7 @@ xmlShellDu(xmlShellCtxtPtr ctxt ATTRIBUTE_UNUSED,
* xmlShellPwd:
* @ctxt: the shell context
* @buffer: the output buffer
* @tree: a node
* @node: a node
* @node2: unused
*
* Implements the XML shell function "pwd"
......
This diff is collapsed.
......@@ -58,6 +58,8 @@ def removeComments(raw):
def extractArgs(raw, function):
raw = removeComments(raw)
raw = string.replace(raw, '\n', ' ')
raw = string.replace(raw, '\r', ' ')
list = string.split(raw, ",")
ret = []
for arg in list:
......@@ -67,7 +69,7 @@ def extractArgs(raw, function):
i = i - 1
c = arg[i]
while string.find(string.letters, c) >= 0 or \
string.find(string.digits, c) >= 0:
string.find(string.digits, c) >= 0 or c == '_':
i = i - 1
if i < 0:
break
......@@ -79,8 +81,11 @@ def extractArgs(raw, function):
break
c = arg[i]
type = mormalizeTypeSpaces(arg[0:i+1], function)
# print "list: %s -> %s, %s" % (list, type, name)
ret.append((type, name))
if name == 'void' and type == '':
pass
else:
ret.append([type, name, ''])
return ret
def extractTypes(raw, function):
......@@ -97,6 +102,7 @@ def extractTypes(raw, function):
ret_types[type].append(function)
else:
ret_types[type] = [function]
return type
def parseMacro():
......@@ -114,10 +120,10 @@ def parseMacro():
line = input.readline()[:-1]
if var == 1:
variables[name] = ''
variables[name] = ['', ''] # type, info
identifiers_type[name] = "variable"
else:
macros[name] = ''
macros[name] = [[], ''] # args, info
identifiers_type[name] = "macro"
def parseStruct():
......@@ -187,18 +193,18 @@ def parseStaticFunction():
line = input.readline()[:-1]
type = None
signature = None
signature = ""
while line != "</USER_FUNCTION>":
if line[0:6] == "<NAME>" and line[-7:] == "</NAME>":
name = line[6:-7]
elif line[0:9] == "<RETURNS>" and line[-10:] == "</RETURNS>":
type = extractTypes(line[9:-10], name)
else:
signature = line
signature = signature + line
line = input.readline()[:-1]
args = extractArgs(signature, name)
user_functions[name] = [type , args, '']
user_functions[name] = [[type, ''] , args, '']
identifiers_type[name] = "functype"
def parseFunction():
......@@ -207,18 +213,18 @@ def parseFunction():
line = input.readline()[:-1]
type = None
signature = None
signature = ""
while line != "</FUNCTION>":
if line[0:6] == "<NAME>" and line[-7:] == "</NAME>":
name = line[6:-7]
elif line[0:9] == "<RETURNS>" and line[-10:] == "</RETURNS>":
type = extractTypes(line[9:-10], name)
else:
signature = line
signature = signature + line
line = input.readline()[:-1]
args = extractArgs(signature, name)
functions[name] = [type , args, '']
functions[name] = [[type, ''] , args, '']
identifiers_type[name] = "function"
print "Parsing: libxml-decl.txt"
......@@ -309,26 +315,87 @@ print "Parsed: %d files %d identifiers" % (len(files), len(identifiers_file.keys
nbcomments = 0
def insertParameterComment(id, name, value, is_param):
global nbcomments
if functions.has_key(id):
if is_param == 1:
args = functions[id][1]
found = 0
for arg in args:
if arg[1] == name:
arg[2] = value
found = 1
break
if found == 0 and name != '...':
print "Arg %s not found on function %s description" % (name, id)
return
else:
ret = functions[id][0]
ret[1] = value
elif user_functions.has_key(id):
if is_param == 1:
args = user_functions[id][1]
found = 0
for arg in args:
if arg[1] == name:
arg[2] = value
found = 1
break
if found == 0 and name != '...':
print "Arg %s not found on functype %s description" % (name, id)
print args
return
else:
ret = user_functions[id][0]
ret[1] = value
elif macros.has_key(id):
if is_param == 1:
args = macros[id][0]
found = 0
for arg in args:
if arg[0] == name:
arg[1] = value
found = 1
break
if found == 0:
args.append([name, value])
else:
print "Return info for macro %s: %s" % (id, value)
# ret = macros[id][0]
# ret[1] = value
else:
print "lost specific comment %s: %s: %s" % (id, name, value)
return
nbcomments = nbcomments + 1
def insertComment(name, title, value):
global nbcomments
if functions.has_key(name):
functions[name][2] = value
return "function"
elif typedefs.has_key(name):
typedefs[name] = value
return "typedef"
elif macros.has_key(name):
macros[name] = value
macros[name][1] = value
return "macro"
elif variables.has_key(name):
variables[name] = value
variables[name][1] = value
return "variable"
elif structs.has_key(name):
structs[name] = value
return "struct"
elif enums.has_key(name):
enums[name][1] = value
return "enum"
elif user_functions.has_key(name):
user_functions[name] = value
user_functions[name][2] = value
return "user_function"
else:
print "lost comment %s: %s" % (name, value)
return
return "unknown"
nbcomments = nbcomments + 1
import os
......@@ -426,10 +493,25 @@ class docParser:
self.title = None
self.descr = None
self.string = None
self.type = None
self.in_parameter = 0
self.is_parameter = 0
self.parameter = None
self.parameter_info = None
self.entry = 0
elif tag == 'para':
self._data = []
elif tag == 'title':
self._data = []
elif tag == 'tgroup':
self.in_parameter = 1
elif tag == 'row':
self._data = []
self.entry = 0
elif tag == 'entry':
self.entry = self.entry + 1
elif tag == 'parameter' and self.in_parameter == 1:
self._data = []
elif tag == 'anchor' and self.id == None:
if attrs.has_key('id'):
self.id = attrs['id']
......@@ -440,20 +522,44 @@ class docParser:
if debug:
print "end %s" % tag
if tag == 'refsect2':
insertComment(self.id, self.title, self.string)
elif tag == 'para':
self.type = insertComment(self.id, self.title, self.string)
self.string = None
elif tag == 'row':
if self.parameter_info != None and self.parameter_info != '':
insertParameterComment(self.id, self.parameter,
self.parameter_info, self.is_parameter)
self.parameter_info = None
self.parameter = 0
self.is_parameter = 0
elif tag == 'parameter' and self.in_parameter == 1 and self.entry == 1:
str = ''
for c in self._data:
str = str + c
str = string.replace(str, '\n', ' ')
str = string.replace(str, '\r', ' ')
str = string.replace(str, ' ', ' ')
str = string.replace(str, ' ', ' ')
str = string.replace(str, ' ', ' ')
while len(str) >= 1 and str[0] == ' ':
str=str[1:]
self.parameter = str
self.is_parameter = 1
self._data = []
elif tag == 'para' or tag == 'entry':
str = ''
for c in self._data:
str = str + c
str = string.replace(str, '\n', ' ')
str = string.replace(str, '\r', ' ')
str = string.replace(str, ' ', ' ')
str = string.replace(str, ' ', ' ')
str = string.replace(str, ' ', ' ')
while len(str) >= 1 and str[0] == ' ':
str=str[1:]
if self.string == None:
str = ''
for c in self._data:
str = str + c
str = string.replace(str, '\n', ' ')
str = string.replace(str, '\r', ' ')
str = string.replace(str, ' ', ' ')
str = string.replace(str, ' ', ' ')
str = string.replace(str, ' ', ' ')
while len(str) >= 1 and str[0] == ' ':
str=str[1:]
self.string = str
elif self.in_parameter == 1:
self.parameter_info = str
self._data = []
elif tag == 'title':
str = ''
......@@ -491,8 +597,11 @@ print "Parsed: %d XML files collexting %d comments" % (xmlfiles, nbcomments)
##################################################################
def escape(raw):
raw = string.replace(raw, '&', '&amp;')
raw = string.replace(raw, '<', '&lt;')
raw = string.replace(raw, '>', '&gt;')
raw = string.replace(raw, "'", '&apos;')
raw = string.replace(raw, '"', '&quot;')
return raw
print "Saving XML description libxml2-api.xml"
......@@ -541,28 +650,69 @@ for i in symbols:
(ret, args, doc) = functions[i]
if doc != None and doc != '':
output.write(" <info>%s</info>\n" % (escape(doc)))
output.write(" <return type='%s'/>\n" % (ret))
if ret[1] != None and ret[1] != '':
output.write(" <return type='%s' info='%s'/>\n" % (
ret[0], escape(ret[1])))
else:
if ret[0] != 'void' and\
ret[0][0:4] != 'void': # This one is actually a bug in GTK Doc
print "Description for return on %s is missing" % (i)
output.write(" <return type='%s'/>\n" % (ret[0]))
for arg in args:
if arg[2] != None and arg[2] != '':
output.write(" <arg name='%s' type='%s' info='%s'/>\n" %
(arg[1], arg[0], escape(arg[2])))
else:
if arg[0] != '...':
print "Description for %s on %s is missing" % (arg[1], i)
output.write(" <arg name='%s' type='%s'/>\n" % (
arg[1], arg[0]))
output.write(" </%s>\n" % (type));
elif type == 'functype':
output.write(">\n");
(ret, args, doc) = user_functions[i]
if doc != None and doc != '':
output.write(" <info>%s</info>\n" % (escape(doc)))
if ret[1] != None and ret[1] != '':
output.write(" <return type='%s' info='%s'/>\n" % (
ret[0], escape(ret[1])))
else:
if ret[0] != 'void' and\
ret[0][0:4] != 'void': # This one is actually a bug in GTK Doc
print "Description for return on %s is missing" % (i)
output.write(" <return type='%s'/>\n" % (ret[0]))
for arg in args:
output.write(" <arg name='%s' type='%s'/>\n" % (
arg[1], arg[0]))
if arg[2] != None and arg[2] != '':
output.write(" <arg name='%s' type='%s' info='%s'/>\n" %
(arg[1], arg[0], escape(arg[2])))
else:
if arg[0] != '...':
print "Description for %s on %s is missing" % (arg[1], i)
output.write(" <arg name='%s' type='%s'/>\n" % (
arg[1], arg[0]))
output.write(" </%s>\n" % (type));
elif type == 'macro':
if macros[i] != None and macros[i] != '':
output.write(" info='%s'/>\n" % (escape(macros[i])))
output.write(">\n");
if macros[i][1] != None and macros[i][1] != '':
output.write(" <info>%s</info>\n" % (escape(macros[i][1])))
else:
output.write("/>\n");
print "Description for %s is missing" % (i)
args = macros[i][0]
for arg in args:
if arg[1] != None and arg[1] != '':
output.write(" <arg name='%s' info='%s'/>\n" %
(arg[0], escape(arg[1])))
else:
print "Description for %s on %s is missing" % (arg[1], i)
output.write(" <arg name='%s'/>\n" % (arg[0]))
output.write(" </%s>\n" % (type));
elif type == 'struct':
if structs[i] != None and structs[i] != '':
output.write(" info='%s'/>\n" % (escape(structs[i])))
else:
output.write("/>\n");
elif type == 'functype':
if user_functions[i] != None and user_functions[i] != '':
output.write(" info='%s'/>\n" % (escape(user_functions[i])))
else:
output.write("/>\n");
elif type == 'variable':
if variables[i] != None and variables[i] != '':
if variables[i][1] != None and variables[i][1] != '':
output.write(" info='%s'/>\n" % (escape(variables[i])))
else:
output.write("/>\n");
......
......@@ -74,6 +74,12 @@ xmlGenericErrorDefaultFunc(void *ctx ATTRIBUTE_UNUSED, const char *msg, ...) {
va_end(args);
}
/**
* initGenericErrorDefaultFunc:
* @handler: the handler
*
* Set or reset (if NULL) the default handler for generic errors
*/
void
initGenericErrorDefaultFunc(xmlGenericErrorFunc * handler)
{
......
......@@ -52,9 +52,40 @@ xmlMallocFunc xmlMalloc = (xmlMallocFunc) xmlMemMalloc;
xmlReallocFunc xmlRealloc = (xmlReallocFunc) xmlMemRealloc;
xmlStrdupFunc xmlMemStrdup = (xmlStrdupFunc) xmlMemoryStrdup;
#else
/**
* xmlFree:
* @mem: an already allocated block of memory
*
* The variable holding the libxml free() implementation
*/
xmlFreeFunc xmlFree = (xmlFreeFunc) free;
/**
* xmlMalloc:
* @size: the size requested in bytes
*
* The variable holding the libxml malloc() implementation
*
* Returns a pointer to the newly allocated block or NULL in case of error
*/
xmlMallocFunc xmlMalloc = (xmlMallocFunc) malloc;
/**
* xmlRealloc:
* @mem: an already allocated block of memory
* @size: the new size requested in bytes
*
* The variable holding the libxml realloc() implementation
*
* Returns a pointer to the newly reallocated block or NULL in case of error
*/
xmlReallocFunc xmlRealloc = (xmlReallocFunc) realloc;
/**
* xmlMemStrdup:
* @str: a zero terminated string
*
* The variable holding the libxml strdup() implementation
*
* Returns the copy of the string or NULL in case of error
*/
xmlStrdupFunc xmlMemStrdup = (xmlStrdupFunc) xmlStrdup;
#endif
......@@ -88,26 +119,102 @@ xmlStrdupFunc xmlMemStrdup = (xmlStrdupFunc) xmlStrdup;
#undef xmlMemStrdup
#undef xmlRealloc
/**
* xmlParserVersion:
*
* Constant string describing the internal version of the library
*/
const char *xmlParserVersion = LIBXML_VERSION_STRING;
/*
* Buffers stuff
/**
* xmlBufferAllocScheme:
*
* Global setting, default allocation policy for buffers, default is
* XML_BUFFER_ALLOC_EXACT
*/
xmlBufferAllocationScheme xmlBufferAllocScheme = XML_BUFFER_ALLOC_EXACT;
/**
* xmlDefaultBufferSize:
*
* Global setting, default buffer size. Default value is BASE_BUFFER_SIZE
*/
int xmlDefaultBufferSize = BASE_BUFFER_SIZE;
/*
* Parser defaults
*/
/**
* oldXMLWDcompatibility:
*
* Global setting, DEPRECATED.
*/
int oldXMLWDcompatibility = 0; /* DEPRECATED */
/**
* xmlParserDebugEntities:
*
* Global setting, asking the parser to print out debugging informations.
* while handling entities.
* Disabled by default
*/
int xmlParserDebugEntities = 0;
/**
* xmlDoValidityCheckingDefaultValue:
*
* Global setting, indicate that the parser should work in validating mode.
* Disabled by default.
*/
int xmlDoValidityCheckingDefaultValue = 0;
/**
* xmlGetWarningsDefaultValue:
*
* Global setting, indicate that the parser should provide warnings.
* Activated by default.
*/
int xmlGetWarningsDefaultValue = 1;
/**
* xmlLoadExtDtdDefaultValue:
*
* Global setting, indicate that the parser should load DTD while not
* validating.
* Disabled by default.
*/
int xmlLoadExtDtdDefaultValue = 0;
/**
* xmlPedanticParserDefaultValue:
*
* Global setting, indicate that the parser be pedantic
* Disabled by default.
*/
int xmlPedanticParserDefaultValue = 0;
/**
* xmlLineNumbersDefaultValue:
*
* Global setting, indicate that the parser should store the line number
* in the content field of elements in the DOM tree.
* Disabled by default since this may not be safe for old classes of
* applicaton.
*/
int xmlLineNumbersDefaultValue = 0;
/**
* xmlKeepBlanksDefaultValue:
*
* Global setting, indicate that the parser should keep all blanks
* nodes found in the content
* Activated by default, this is actually needed to have the parser
* conformant to the XML Recommendation, however the option is kept
* for some applications since this was libxml1 default behaviour.
*/
int xmlKeepBlanksDefaultValue = 1;
/**
* xmlSubstituteEntitiesDefaultValue:
*
* Global setting, indicate that the parser should not generate entity
* references but replace them with the actual content of the entity
* Disabled by default, this should be activated when using XPath since
* the XPath data model requires entities replacement and the XPath
* engine does not handle entities references transparently.
*/
int xmlSubstituteEntitiesDefaultValue = 0;
/*
......@@ -119,16 +226,42 @@ int xmlSubstituteEntitiesDefaultValue = 0;
void xmlGenericErrorDefaultFunc (void *ctx ATTRIBUTE_UNUSED,
const char *msg,
...);
/**
* xmlGenericError:
*
* Global setting: function used for generic error callbacks
*/
xmlGenericErrorFunc xmlGenericError = xmlGenericErrorDefaultFunc;
/**
* xmlGenericErrorContext:
*
* Global setting passed to generic error callbacks
*/
void *xmlGenericErrorContext = NULL;
/*
* output defaults
*/
/**
* xmlIndentTreeOutput: