scripts/apibuild.py did not consider exporting external variable's
comments into the XML API. This commits fixes that.
Noe that the way that CParser is designed, it is currently possible to
lose a parsed comment when parsing other fields as self.comment in
several places. I've added a comment to highlight this.
Signed-off-by: Victor Toso <victortoso@xxxxxxxxxx>
---
scripts/apibuild.py | 22 ++++++++++++++++------
1 file changed, 16 insertions(+), 6 deletions(-)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py
index 97f448f6bf..d1edfce3a6 100755
--- a/scripts/apibuild.py
+++ b/scripts/apibuild.py
@@ -1930,10 +1930,14 @@ class CParser:
if token is None or token[0] != 'name':
return token
+ variable_comment = None
if token[1] == 'typedef':
token = self.token()
return self.parseTypedef(token)
else:
+ # Store block of comment that might be from variable as
+ # the code uses self.comment a lot and it would lose it.
+ variable_comment = self.cleanup_code_comment(self.comment)
token = self.parseType(token)
type_orig = self.type
if token is None or token[0] != "name":
@@ -1979,8 +1983,10 @@ class CParser:
not self.is_header, "struct",
self.struct_fields)
else:
+ # Just to use the cleanupComment function.
+ info = (type, variable_comment)
self.index_add(self.name, self.filename,
- not self.is_header, "variable", type)
+ not self.is_header, "variable", info)
break
elif token[1] == "(":
token = self.token()
@@ -2354,12 +2360,16 @@ class docBuilder:
def serialize_variable(self, output, name):
id = self.idx.variables[name]
- if id.info is not None:
- output.write(" <variable name='%s' file='%s' type='%s'/>\n" % (
- name, self.modulename_file(id.header), id.info))
+ (type, comment) = id.info
+ (since, comment, _) = self.retrieve_comment_tags(name, comment)
+ version_tag = len(since) > 0 and f" version='{since}'" or ""
+ output.write(" <variable name='%s' file='%s' type='%s'%s" % (
+ name, self.modulename_file(id.header), type, version_tag))
+ if len(comment) == 0:
+ output.write("/>\n")
else:
- output.write(" <variable name='%s' file='%s'/>\n" % (
- name, self.modulename_file(id.header)))
+ output.write(">\n <info><![CDATA[%s]]></info>\n" % (comment))
+ output.write(" </variable>\n")
def serialize_function(self, output, name):
id = self.idx.functions[name]
--
2.35.1
