Re: [PATCH v3 29/30] scripts: apibuild: add parsing variable's comments

On Wed, Apr 20, 2022 at 09:08:18PM +0200, Victor Toso wrote: > 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)) Note that, for variables, the comment will not have gone through the same sanifications as for other symbols, and so the output will look like <variable name='virConnectAuthPtrDefault' file='libvirt-host' type='virConnectAuthPtr' version='0.4.1'> <info><![CDATA[virConnectAuthPtrDefault: A default implementation of the authentication callbacks. This implementation is suitable for command line based tools. It will prompt for username, passwords, realm and one time keys as needed. It will print on STDOUT, and read from STDIN. If this is not suitable for the application's needs an alternative implementation should be provided.]]></info> </variable> The first two lines of the CDATA section should obviously not be there.

Various functions have code like lines = self.comment.split('\n') if lines[0] == '*': del lines[0] if lines[0] != "* %s:" % name: if not quiet: self.warning("Misformatted function comment for %s" % name) self.warning(" Expecting '* %s:' got '%s'" % (name, lines[0])) return (ret[0], retdesc), args, desc del lines[0] while lines[0] == '*': del lines[0] to deal with this scenario, but I'm unclear on where exactly you'd put the equivalent for variables. The whole script is a giant underdocumented[1] mess and I'm utterly impressed by your ability to understand it well enough to add features to it.

[1] I can absolutely appreciate the irony in that ;)