[libxml2] Support comments for global variables in documentation
- From: Nick Wellnhofer <nwellnhof src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libxml2] Support comments for global variables in documentation
- Date: Tue, 23 Aug 2022 23:07:00 +0000 (UTC)
commit 4f3eb8a3b42c38e0f5a47681848e9094bd841e6d
Author: Nick Wellnhofer <wellnhofer aevum de>
Date: Wed Aug 24 00:15:10 2022 +0200
Support comments for global variables in documentation
This was never implemented.
doc/apibuild.py | 55 +++++++++++++++++++----------
doc/libxml2-api.xml | 100 +++++++++++++++++++++++++++++++++++++++-------------
2 files changed, 111 insertions(+), 44 deletions(-)
---
diff --git a/doc/apibuild.py b/doc/apibuild.py
index 8bf8bbd3..2090c31b 100755
--- a/doc/apibuild.py
+++ b/doc/apibuild.py
@@ -330,7 +330,19 @@ class index:
# else:
# print "Function %s from %s is not declared in headers" % (
# id, idx.functions[id].module)
- # TODO: do the same for variables.
+
+ for id in list(idx.variables.keys()):
+ if id in self.variables:
+ # check that variable condition agrees with header
+ # TODO: produces many false positives
+ #if idx.variables[id].conditionals != \
+ # self.variables[id].conditionals:
+ # print("Header condition differs from Variable for %s:" \
+ # % id)
+ # print(" H: %s" % self.variables[id].conditionals)
+ # print(" C: %s" % idx.variables[id].conditionals)
+ up = idx.variables[id]
+ self.variables[id].update(None, up.module, up.type, up.info, up.extra)
def analyze_dict(self, type, dict):
count = 0
@@ -679,9 +691,9 @@ class CParser:
return token
#
- # Parse a comment block associate to a typedef
+ # Parse a simple comment block for typedefs or global variables
#
- def parseTypeComment(self, name, quiet = 0):
+ def parseSimpleComment(self, name, quiet = False):
if name[0:2] == '__':
quiet = 1
@@ -690,20 +702,20 @@ class CParser:
if self.comment == None:
if not quiet:
- self.warning("Missing comment for type %s" % (name))
- return((args, desc))
+ self.warning("Missing comment for %s" % (name))
+ return(None)
if self.comment[0] != '*':
if not quiet:
- self.warning("Missing * in type comment for %s" % (name))
- return((args, desc))
+ self.warning("Missing * in comment for %s" % (name))
+ return(None)
lines = self.comment.split('\n')
if lines[0] == '*':
del lines[0]
if lines[0] != "* %s:" % (name):
if not quiet:
- self.warning("Misformatted type comment for %s" % (name))
+ self.warning("Misformatted comment for %s" % (name))
self.warning(" Expecting '* %s:' got '%s'" % (name, lines[0]))
- return((args, desc))
+ return(None)
del lines[0]
while len(lines) > 0 and lines[0] == '*':
del lines[0]
@@ -720,7 +732,7 @@ class CParser:
if quiet == 0:
if desc == "":
- self.warning("Type comment for %s lack description of the macro" % (name))
+ self.warning("Comment for %s lacks description" % (name))
return(desc)
#
@@ -1070,7 +1082,7 @@ class CParser:
base_type = "struct " + name
else:
# TODO report missing or misformatted comments
- info = self.parseTypeComment(name, 1)
+ info = self.parseSimpleComment(name, True)
self.index_add(name, self.filename, not self.is_header,
"typedef", type, info)
token = self.token()
@@ -1520,25 +1532,24 @@ class CParser:
token = self.token()
token = self.parseBlock(token)
else:
- self.comment = None
while token != None and (token[0] != "sep" or \
(token[1] != ';' and token[1] != ',')):
token = self.token()
- self.comment = None
if token == None or token[0] != "sep" or (token[1] != ';' and
token[1] != ','):
self.error("missing ';' or ',' after value")
if token != None and token[0] == "sep":
if token[1] == ";":
- self.comment = None
- token = self.token()
if type == "struct":
self.index_add(self.name, self.filename,
not self.is_header, "struct", self.struct_fields)
else:
+ info = self.parseSimpleComment(self.name, True)
self.index_add(self.name, self.filename,
- not self.is_header, "variable", type)
+ not self.is_header, "variable", type, info)
+ self.comment = None
+ token = self.token()
break
elif token[1] == "(":
token = self.token()
@@ -1559,7 +1570,6 @@ class CParser:
token = self.token()
token = self.parseBlock(token);
elif token[1] == ',':
- self.comment = None
self.index_add(self.name, self.filename, static,
"variable", type)
type = type_orig
@@ -1570,6 +1580,7 @@ class CParser:
if token != None and token[0] == "name":
self.name = token[1]
token = self.token()
+ self.comment = None
else:
break
@@ -1734,11 +1745,17 @@ class docBuilder:
def serialize_variable(self, output, name):
id = self.idx.variables[name]
if id.info != None:
- output.write(" <variable name='%s' file='%s' type='%s'/>\n" % (
+ output.write(" <variable name='%s' file='%s' type='%s'" % (
name, self.modulename_file(id.header), id.info))
else:
- output.write(" <variable name='%s' file='%s'/>\n" % (
+ output.write(" <variable name='%s' file='%s'" % (
name, self.modulename_file(id.header)))
+ desc = id.extra
+ if desc != None and desc != "":
+ output.write(">\n <info>%s</info>\n" % (escape(desc)))
+ output.write(" </variable>\n")
+ else:
+ output.write("/>\n")
def serialize_function(self, output, name):
id = self.idx.functions[name]
diff --git a/doc/libxml2-api.xml b/doc/libxml2-api.xml
index 285837c7..8623afbc 100644
--- a/doc/libxml2-api.xml
+++ b/doc/libxml2-api.xml
@@ -6952,18 +6952,36 @@ Could we use @subtypes for this?'/>
<variable name='emptyExp' file='xmlregexp' type='xmlExpNodePtr'/>
<variable name='forbiddenExp' file='xmlregexp' type='xmlExpNodePtr'/>
<variable name='htmlDefaultSAXHandler' file='globals' type='xmlSAXHandlerV1'/>
- <variable name='oldXMLWDcompatibility' file='globals' type='int'/>
- <variable name='xmlBufferAllocScheme' file='globals' type='xmlBufferAllocationScheme'/>
- <variable name='xmlDefaultBufferSize' file='globals' type='int'/>
+ <variable name='oldXMLWDcompatibility' file='globals' type='int'>
+ <info>Global setting, DEPRECATED.</info>
+ </variable>
+ <variable name='xmlBufferAllocScheme' file='globals' type='xmlBufferAllocationScheme'>
+ <info>DEPRECATED: Don't use. Global setting, default allocation policy for buffers, default is
XML_BUFFER_ALLOC_EXACT</info>
+ </variable>
+ <variable name='xmlDefaultBufferSize' file='globals' type='int'>
+ <info>DEPRECATED: Don't use. Global setting, default buffer size. Default value is
BASE_BUFFER_SIZE</info>
+ </variable>
<variable name='xmlDefaultSAXHandler' file='globals' type='xmlSAXHandlerV1'/>
<variable name='xmlDefaultSAXLocator' file='globals' type='xmlSAXLocator'/>
<variable name='xmlDeregisterNodeDefaultValue' file='globals' type='xmlDeregisterNodeFunc'/>
- <variable name='xmlDoValidityCheckingDefaultValue' file='globals' type='int'/>
- <variable name='xmlFree' file='globals' type='xmlFreeFunc'/>
- <variable name='xmlGenericError' file='globals' type='xmlGenericErrorFunc'/>
- <variable name='xmlGenericErrorContext' file='globals' type='void *'/>
- <variable name='xmlGetWarningsDefaultValue' file='globals' type='int'/>
- <variable name='xmlIndentTreeOutput' file='globals' type='int'/>
+ <variable name='xmlDoValidityCheckingDefaultValue' file='globals' type='int'>
+ <info>Global setting, indicate that the parser should work in validating mode. Disabled by
default.</info>
+ </variable>
+ <variable name='xmlFree' file='globals' type='xmlFreeFunc'>
+ <info>@mem: an already allocated block of memory The variable holding the libxml free()
implementation</info>
+ </variable>
+ <variable name='xmlGenericError' file='globals' type='xmlGenericErrorFunc'>
+ <info>Global setting: function used for generic error callbacks</info>
+ </variable>
+ <variable name='xmlGenericErrorContext' file='globals' type='void *'>
+ <info>Global setting passed to generic error callbacks</info>
+ </variable>
+ <variable name='xmlGetWarningsDefaultValue' file='globals' type='int'>
+ <info>Global setting, indicate that the parser should provide warnings. Activated by default.</info>
+ </variable>
+ <variable name='xmlIndentTreeOutput' file='globals' type='int'>
+ <info>Global setting, asking the serializer to indent the output tree by default Enabled by
default</info>
+ </variable>
<variable name='xmlIsBaseCharGroup' file='chvalid' type='const xmlChRangeGroup'/>
<variable name='xmlIsCharGroup' file='chvalid' type='const xmlChRangeGroup'/>
<variable name='xmlIsCombiningGroup' file='chvalid' type='const xmlChRangeGroup'/>
@@ -6971,29 +6989,61 @@ Could we use @subtypes for this?'/>
<variable name='xmlIsExtenderGroup' file='chvalid' type='const xmlChRangeGroup'/>
<variable name='xmlIsIdeographicGroup' file='chvalid' type='const xmlChRangeGroup'/>
<variable name='xmlIsPubidChar_tab' file='chvalid' type='const unsigned charxmlIsPubidChar_tab[256]'/>
- <variable name='xmlKeepBlanksDefaultValue' file='globals' type='int'/>
+ <variable name='xmlKeepBlanksDefaultValue' file='globals' type='int'>
+ <info>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.</info>
+ </variable>
<variable name='xmlLastError' file='globals' type='xmlError'/>
- <variable name='xmlLineNumbersDefaultValue' file='globals' type='int'/>
- <variable name='xmlLoadExtDtdDefaultValue' file='globals' type='int'/>
- <variable name='xmlMalloc' file='globals' type='xmlMallocFunc'/>
- <variable name='xmlMallocAtomic' file='globals' type='xmlMallocFunc'/>
- <variable name='xmlMemStrdup' file='globals' type='xmlStrdupFunc'/>
+ <variable name='xmlLineNumbersDefaultValue' file='globals' type='int'>
+ <info>DEPRECATED: The modern options API always enables line numbers. 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 application.</info>
+ </variable>
+ <variable name='xmlLoadExtDtdDefaultValue' file='globals' type='int'>
+ <info>Global setting, indicate that the parser should load DTD while not validating. Disabled by
default.</info>
+ </variable>
+ <variable name='xmlMalloc' file='globals' type='xmlMallocFunc'>
+ <info>@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</info>
+ </variable>
+ <variable name='xmlMallocAtomic' file='globals' type='xmlMallocFunc'>
+ <info>@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. Returns
a pointer to the newly allocated block or NULL in case of error</info>
+ </variable>
+ <variable name='xmlMemStrdup' file='globals' type='xmlStrdupFunc'>
+ <info>@str: a zero terminated string The variable holding the libxml strdup() implementation Returns
the copy of the string or NULL in case of error</info>
+ </variable>
<variable name='xmlOutputBufferCreateFilenameValue' file='globals'
type='xmlOutputBufferCreateFilenameFunc'/>
- <variable name='xmlParserDebugEntities' file='globals' type='int'/>
+ <variable name='xmlParserDebugEntities' file='globals' type='int'>
+ <info>Global setting, asking the parser to print out debugging information. while handling entities.
Disabled by default</info>
+ </variable>
<variable name='xmlParserInputBufferCreateFilenameValue' file='globals'
type='xmlParserInputBufferCreateFilenameFunc'/>
- <variable name='xmlParserMaxDepth' file='parserInternals' type='unsigned int'/>
- <variable name='xmlParserVersion' file='globals' type='const char *'/>
- <variable name='xmlPedanticParserDefaultValue' file='globals' type='int'/>
- <variable name='xmlRealloc' file='globals' type='xmlReallocFunc'/>
+ <variable name='xmlParserMaxDepth' file='parserInternals' type='unsigned int'>
+ <info>arbitrary depth limit for the XML documents that we allow to process. This is not a limitation
of the parser but a safety boundary feature. It can be disabled with the XML_PARSE_HUGE parser option.</info>
+ </variable>
+ <variable name='xmlParserVersion' file='globals' type='const char *'>
+ <info>Constant string describing the internal version of the library</info>
+ </variable>
+ <variable name='xmlPedanticParserDefaultValue' file='globals' type='int'>
+ <info>DEPRECATED: Use the modern options API with XML_PARSE_PEDANTIC. Global setting, indicate that
the parser be pedantic Disabled by default.</info>
+ </variable>
+ <variable name='xmlRealloc' file='globals' type='xmlReallocFunc'>
+ <info>@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</info>
+ </variable>
<variable name='xmlRegisterNodeDefaultValue' file='globals' type='xmlRegisterNodeFunc'/>
- <variable name='xmlSaveNoEmptyTags' file='globals' type='int'/>
+ <variable name='xmlSaveNoEmptyTags' file='globals' type='int'>
+ <info>Global setting, asking the serializer to not output empty tags as <empty/> but
<empty></empty>. those two forms are indistinguishable once parsed. Disabled by default</info>
+ </variable>
<variable name='xmlStringComment' file='parserInternals' type='const xmlCharxmlStringComment[]'/>
<variable name='xmlStringText' file='parserInternals' type='const xmlCharxmlStringText[]'/>
<variable name='xmlStringTextNoenc' file='parserInternals' type='const xmlCharxmlStringTextNoenc[]'/>
- <variable name='xmlStructuredError' file='globals' type='xmlStructuredErrorFunc'/>
- <variable name='xmlStructuredErrorContext' file='globals' type='void *'/>
- <variable name='xmlSubstituteEntitiesDefaultValue' file='globals' type='int'/>
- <variable name='xmlTreeIndentString' file='globals' type='const char *'/>
+ <variable name='xmlStructuredError' file='globals' type='xmlStructuredErrorFunc'>
+ <info>Global setting: function used for structured error callbacks</info>
+ </variable>
+ <variable name='xmlStructuredErrorContext' file='globals' type='void *'>
+ <info>Global setting passed to structured error callbacks</info>
+ </variable>
+ <variable name='xmlSubstituteEntitiesDefaultValue' file='globals' type='int'>
+ <info>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.</info>
+ </variable>
+ <variable name='xmlTreeIndentString' file='globals' type='const char *'>
+ <info>The string used to do one-level indent. By default is equal to " " (two spaces)</info>
+ </variable>
<variable name='xmlXPathNAN' file='xpath' type='double'/>
<variable name='xmlXPathNINF' file='xpath' type='double'/>
<variable name='xmlXPathPINF' file='xpath' type='double'/>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
