Skip to content

Commit 4f3eb8a

Browse files
nwellnhofnwellnhof
committed
Support comments for global variables in documentation
This was never implemented.
1 parent 288c951 commit 4f3eb8a

File tree

2 files changed

+111
-44
lines changed

2 files changed

+111
-44
lines changed

‎doc/apibuild.py

+36-19
Original file line numberDiff line numberDiff line change
@@ -330,7 +330,19 @@ def merge_public(self, idx):
330330
# else:
331331
# print "Function %s from %s is not declared in headers" % (
332332
# id, idx.functions[id].module)
333-
# TODO: do the same for variables.
333+
334+
for id in list(idx.variables.keys()):
335+
if id in self.variables:
336+
# check that variable condition agrees with header
337+
# TODO: produces many false positives
338+
#if idx.variables[id].conditionals != \
339+
# self.variables[id].conditionals:
340+
# print("Header condition differs from Variable for %s:" \
341+
# % id)
342+
# print(" H: %s" % self.variables[id].conditionals)
343+
# print(" C: %s" % idx.variables[id].conditionals)
344+
up = idx.variables[id]
345+
self.variables[id].update(None, up.module, up.type, up.info, up.extra)
334346

335347
def analyze_dict(self, type, dict):
336348
count = 0
@@ -679,9 +691,9 @@ def parseComment(self, token):
679691
return token
680692

681693
#
682-
# Parse a comment block associate to a typedef
694+
# Parse a simple comment block for typedefs or global variables
683695
#
684-
def parseTypeComment(self, name, quiet = 0):
696+
def parseSimpleComment(self, name, quiet = False):
685697
if name[0:2] == '__':
686698
quiet = 1
687699

@@ -690,20 +702,20 @@ def parseTypeComment(self, name, quiet = 0):
690702

691703
if self.comment == None:
692704
if not quiet:
693-
self.warning("Missing comment for type %s" % (name))
694-
return((args, desc))
705+
self.warning("Missing comment for %s" % (name))
706+
return(None)
695707
if self.comment[0] != '*':
696708
if not quiet:
697-
self.warning("Missing * in type comment for %s" % (name))
698-
return((args, desc))
709+
self.warning("Missing * in comment for %s" % (name))
710+
return(None)
699711
lines = self.comment.split('\n')
700712
if lines[0] == '*':
701713
del lines[0]
702714
if lines[0] != "* %s:" % (name):
703715
if not quiet:
704-
self.warning("Misformatted type comment for %s" % (name))
716+
self.warning("Misformatted comment for %s" % (name))
705717
self.warning(" Expecting '* %s:' got '%s'" % (name, lines[0]))
706-
return((args, desc))
718+
return(None)
707719
del lines[0]
708720
while len(lines) > 0 and lines[0] == '*':
709721
del lines[0]
@@ -720,7 +732,7 @@ def parseTypeComment(self, name, quiet = 0):
720732

721733
if quiet == 0:
722734
if desc == "":
723-
self.warning("Type comment for %s lack description of the macro" % (name))
735+
self.warning("Comment for %s lacks description" % (name))
724736

725737
return(desc)
726738
#
@@ -1070,7 +1082,7 @@ def parseTypedef(self, token):
10701082
base_type = "struct " + name
10711083
else:
10721084
# TODO report missing or misformatted comments
1073-
info = self.parseTypeComment(name, 1)
1085+
info = self.parseSimpleComment(name, True)
10741086
self.index_add(name, self.filename, not self.is_header,
10751087
"typedef", type, info)
10761088
token = self.token()
@@ -1520,25 +1532,24 @@ def parseGlobal(self, token):
15201532
token = self.token()
15211533
token = self.parseBlock(token)
15221534
else:
1523-
self.comment = None
15241535
while token != None and (token[0] != "sep" or \
15251536
(token[1] != ';' and token[1] != ',')):
15261537
token = self.token()
1527-
self.comment = None
15281538
if token == None or token[0] != "sep" or (token[1] != ';' and
15291539
token[1] != ','):
15301540
self.error("missing ';' or ',' after value")
15311541

15321542
if token != None and token[0] == "sep":
15331543
if token[1] == ";":
1534-
self.comment = None
1535-
token = self.token()
15361544
if type == "struct":
15371545
self.index_add(self.name, self.filename,
15381546
not self.is_header, "struct", self.struct_fields)
15391547
else:
1548+
info = self.parseSimpleComment(self.name, True)
15401549
self.index_add(self.name, self.filename,
1541-
not self.is_header, "variable", type)
1550+
not self.is_header, "variable", type, info)
1551+
self.comment = None
1552+
token = self.token()
15421553
break
15431554
elif token[1] == "(":
15441555
token = self.token()
@@ -1559,7 +1570,6 @@ def parseGlobal(self, token):
15591570
token = self.token()
15601571
token = self.parseBlock(token);
15611572
elif token[1] == ',':
1562-
self.comment = None
15631573
self.index_add(self.name, self.filename, static,
15641574
"variable", type)
15651575
type = type_orig
@@ -1570,6 +1580,7 @@ def parseGlobal(self, token):
15701580
if token != None and token[0] == "name":
15711581
self.name = token[1]
15721582
token = self.token()
1583+
self.comment = None
15731584
else:
15741585
break
15751586

@@ -1734,11 +1745,17 @@ def serialize_typedef(self, output, name):
17341745
def serialize_variable(self, output, name):
17351746
id = self.idx.variables[name]
17361747
if id.info != None:
1737-
output.write(" <variable name='%s' file='%s' type='%s'/>\n" % (
1748+
output.write(" <variable name='%s' file='%s' type='%s'" % (
17381749
name, self.modulename_file(id.header), id.info))
17391750
else:
1740-
output.write(" <variable name='%s' file='%s'/>\n" % (
1751+
output.write(" <variable name='%s' file='%s'" % (
17411752
name, self.modulename_file(id.header)))
1753+
desc = id.extra
1754+
if desc != None and desc != "":
1755+
output.write(">\n <info>%s</info>\n" % (escape(desc)))
1756+
output.write(" </variable>\n")
1757+
else:
1758+
output.write("/>\n")
17421759

17431760
def serialize_function(self, output, name):
17441761
id = self.idx.functions[name]

‎doc/libxml2-api.xml

+75-25
Original file line numberDiff line numberDiff line change
@@ -6952,48 +6952,98 @@ Could we use @subtypes for this?'/>
69526952
<variable name='emptyExp' file='xmlregexp' type='xmlExpNodePtr'/>
69536953
<variable name='forbiddenExp' file='xmlregexp' type='xmlExpNodePtr'/>
69546954
<variable name='htmlDefaultSAXHandler' file='globals' type='xmlSAXHandlerV1'/>
6955-
<variable name='oldXMLWDcompatibility' file='globals' type='int'/>
6956-
<variable name='xmlBufferAllocScheme' file='globals' type='xmlBufferAllocationScheme'/>
6957-
<variable name='xmlDefaultBufferSize' file='globals' type='int'/>
6955+
<variable name='oldXMLWDcompatibility' file='globals' type='int'>
6956+
<info>Global setting, DEPRECATED.</info>
6957+
</variable>
6958+
<variable name='xmlBufferAllocScheme' file='globals' type='xmlBufferAllocationScheme'>
6959+
<info>DEPRECATED: Don&apos;t use. Global setting, default allocation policy for buffers, default is XML_BUFFER_ALLOC_EXACT</info>
6960+
</variable>
6961+
<variable name='xmlDefaultBufferSize' file='globals' type='int'>
6962+
<info>DEPRECATED: Don&apos;t use. Global setting, default buffer size. Default value is BASE_BUFFER_SIZE</info>
6963+
</variable>
69586964
<variable name='xmlDefaultSAXHandler' file='globals' type='xmlSAXHandlerV1'/>
69596965
<variable name='xmlDefaultSAXLocator' file='globals' type='xmlSAXLocator'/>
69606966
<variable name='xmlDeregisterNodeDefaultValue' file='globals' type='xmlDeregisterNodeFunc'/>
6961-
<variable name='xmlDoValidityCheckingDefaultValue' file='globals' type='int'/>
6962-
<variable name='xmlFree' file='globals' type='xmlFreeFunc'/>
6963-
<variable name='xmlGenericError' file='globals' type='xmlGenericErrorFunc'/>
6964-
<variable name='xmlGenericErrorContext' file='globals' type='void *'/>
6965-
<variable name='xmlGetWarningsDefaultValue' file='globals' type='int'/>
6966-
<variable name='xmlIndentTreeOutput' file='globals' type='int'/>
6967+
<variable name='xmlDoValidityCheckingDefaultValue' file='globals' type='int'>
6968+
<info>Global setting, indicate that the parser should work in validating mode. Disabled by default.</info>
6969+
</variable>
6970+
<variable name='xmlFree' file='globals' type='xmlFreeFunc'>
6971+
<info>@mem: an already allocated block of memory The variable holding the libxml free() implementation</info>
6972+
</variable>
6973+
<variable name='xmlGenericError' file='globals' type='xmlGenericErrorFunc'>
6974+
<info>Global setting: function used for generic error callbacks</info>
6975+
</variable>
6976+
<variable name='xmlGenericErrorContext' file='globals' type='void *'>
6977+
<info>Global setting passed to generic error callbacks</info>
6978+
</variable>
6979+
<variable name='xmlGetWarningsDefaultValue' file='globals' type='int'>
6980+
<info>Global setting, indicate that the parser should provide warnings. Activated by default.</info>
6981+
</variable>
6982+
<variable name='xmlIndentTreeOutput' file='globals' type='int'>
6983+
<info>Global setting, asking the serializer to indent the output tree by default Enabled by default</info>
6984+
</variable>
69676985
<variable name='xmlIsBaseCharGroup' file='chvalid' type='const xmlChRangeGroup'/>
69686986
<variable name='xmlIsCharGroup' file='chvalid' type='const xmlChRangeGroup'/>
69696987
<variable name='xmlIsCombiningGroup' file='chvalid' type='const xmlChRangeGroup'/>
69706988
<variable name='xmlIsDigitGroup' file='chvalid' type='const xmlChRangeGroup'/>
69716989
<variable name='xmlIsExtenderGroup' file='chvalid' type='const xmlChRangeGroup'/>
69726990
<variable name='xmlIsIdeographicGroup' file='chvalid' type='const xmlChRangeGroup'/>
69736991
<variable name='xmlIsPubidChar_tab' file='chvalid' type='const unsigned charxmlIsPubidChar_tab[256]'/>
6974-
<variable name='xmlKeepBlanksDefaultValue' file='globals' type='int'/>
6992+
<variable name='xmlKeepBlanksDefaultValue' file='globals' type='int'>
6993+
<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>
6994+
</variable>
69756995
<variable name='xmlLastError' file='globals' type='xmlError'/>
6976-
<variable name='xmlLineNumbersDefaultValue' file='globals' type='int'/>
6977-
<variable name='xmlLoadExtDtdDefaultValue' file='globals' type='int'/>
6978-
<variable name='xmlMalloc' file='globals' type='xmlMallocFunc'/>
6979-
<variable name='xmlMallocAtomic' file='globals' type='xmlMallocFunc'/>
6980-
<variable name='xmlMemStrdup' file='globals' type='xmlStrdupFunc'/>
6996+
<variable name='xmlLineNumbersDefaultValue' file='globals' type='int'>
6997+
<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>
6998+
</variable>
6999+
<variable name='xmlLoadExtDtdDefaultValue' file='globals' type='int'>
7000+
<info>Global setting, indicate that the parser should load DTD while not validating. Disabled by default.</info>
7001+
</variable>
7002+
<variable name='xmlMalloc' file='globals' type='xmlMallocFunc'>
7003+
<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>
7004+
</variable>
7005+
<variable name='xmlMallocAtomic' file='globals' type='xmlMallocFunc'>
7006+
<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>
7007+
</variable>
7008+
<variable name='xmlMemStrdup' file='globals' type='xmlStrdupFunc'>
7009+
<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>
7010+
</variable>
69817011
<variable name='xmlOutputBufferCreateFilenameValue' file='globals' type='xmlOutputBufferCreateFilenameFunc'/>
6982-
<variable name='xmlParserDebugEntities' file='globals' type='int'/>
7012+
<variable name='xmlParserDebugEntities' file='globals' type='int'>
7013+
<info>Global setting, asking the parser to print out debugging information. while handling entities. Disabled by default</info>
7014+
</variable>
69837015
<variable name='xmlParserInputBufferCreateFilenameValue' file='globals' type='xmlParserInputBufferCreateFilenameFunc'/>
6984-
<variable name='xmlParserMaxDepth' file='parserInternals' type='unsigned int'/>
6985-
<variable name='xmlParserVersion' file='globals' type='const char *'/>
6986-
<variable name='xmlPedanticParserDefaultValue' file='globals' type='int'/>
6987-
<variable name='xmlRealloc' file='globals' type='xmlReallocFunc'/>
7016+
<variable name='xmlParserMaxDepth' file='parserInternals' type='unsigned int'>
7017+
<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>
7018+
</variable>
7019+
<variable name='xmlParserVersion' file='globals' type='const char *'>
7020+
<info>Constant string describing the internal version of the library</info>
7021+
</variable>
7022+
<variable name='xmlPedanticParserDefaultValue' file='globals' type='int'>
7023+
<info>DEPRECATED: Use the modern options API with XML_PARSE_PEDANTIC. Global setting, indicate that the parser be pedantic Disabled by default.</info>
7024+
</variable>
7025+
<variable name='xmlRealloc' file='globals' type='xmlReallocFunc'>
7026+
<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>
7027+
</variable>
69887028
<variable name='xmlRegisterNodeDefaultValue' file='globals' type='xmlRegisterNodeFunc'/>
6989-
<variable name='xmlSaveNoEmptyTags' file='globals' type='int'/>
7029+
<variable name='xmlSaveNoEmptyTags' file='globals' type='int'>
7030+
<info>Global setting, asking the serializer to not output empty tags as &lt;empty/&gt; but &lt;empty&gt;&lt;/empty&gt;. those two forms are indistinguishable once parsed. Disabled by default</info>
7031+
</variable>
69907032
<variable name='xmlStringComment' file='parserInternals' type='const xmlCharxmlStringComment[]'/>
69917033
<variable name='xmlStringText' file='parserInternals' type='const xmlCharxmlStringText[]'/>
69927034
<variable name='xmlStringTextNoenc' file='parserInternals' type='const xmlCharxmlStringTextNoenc[]'/>
6993-
<variable name='xmlStructuredError' file='globals' type='xmlStructuredErrorFunc'/>
6994-
<variable name='xmlStructuredErrorContext' file='globals' type='void *'/>
6995-
<variable name='xmlSubstituteEntitiesDefaultValue' file='globals' type='int'/>
6996-
<variable name='xmlTreeIndentString' file='globals' type='const char *'/>
7035+
<variable name='xmlStructuredError' file='globals' type='xmlStructuredErrorFunc'>
7036+
<info>Global setting: function used for structured error callbacks</info>
7037+
</variable>
7038+
<variable name='xmlStructuredErrorContext' file='globals' type='void *'>
7039+
<info>Global setting passed to structured error callbacks</info>
7040+
</variable>
7041+
<variable name='xmlSubstituteEntitiesDefaultValue' file='globals' type='int'>
7042+
<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>
7043+
</variable>
7044+
<variable name='xmlTreeIndentString' file='globals' type='const char *'>
7045+
<info>The string used to do one-level indent. By default is equal to &quot; &quot; (two spaces)</info>
7046+
</variable>
69977047
<variable name='xmlXPathNAN' file='xpath' type='double'/>
69987048
<variable name='xmlXPathNINF' file='xpath' type='double'/>
69997049
<variable name='xmlXPathPINF' file='xpath' type='double'/>

0 commit comments

Comments
 (0)