Re: [libvirt] [PATCH] Fix API doc extractor to stop munging comment formatting

The python method help docs are copied across from the C funtion comments, but in the process all line breaks and indentation was being lost. This made the resulting text and code examples completely unreadable. Both the API doc extractor and the python generator were destroying whitespace & this fixes them to preserve it exactly. * docs/apibuild.py: Preserve all whitespace when extracting function comments. Print function comment inside a <![CDATA[ section to fully preserve all whitespace. Look for the word 'returns' to describe return values, instead of 'return' to avoid getting confused with code examples including the C 'return' statement. * python/generator.py: Preserve all whitespace when printing function help docs * src/libvirt.c: Change any return parameter indicated by 'return' to be 'returns', to avoid confusing the API extractor

if desc != None and desc != "": - output.write(" <info>%s</info>\n" % (escape(desc))) + output.write(" <info><![CDATA[%s]]></info>\n" % (desc))

self.indexString(name, desc) for arg in args: (name, desc) = arg @@ -1760,7 +1771,7 @@ class docBuilder: try: desc = id.extra if desc != None and desc != "": - output.write(">\n <info>%s</info>\n" % (escape(desc))) + output.write(">\n <info><![CDATA[%s]]></info>\n" % (desc)) output.write(" </typedef>\n") else: output.write("/>\n") @@ -1796,7 +1807,7 @@ class docBuilder: output.write(" <cond>%s</cond>\n"% (apstr)); try: (ret, params, desc) = id.info - output.write(" <info>%s</info>\n" % (escape(desc))) + output.write(" <info><![CDATA[%s]]></info>\n" % (desc)) self.indexString(name, desc) if ret[0] != None: if ret[0] == "void": diff --git a/python/generator.py b/python/generator.py index c34cb34..178a415 100755 --- a/python/generator.py +++ b/python/generator.py @@ -44,6 +44,7 @@ if sgmlop: self.finish_starttag = target.start self.finish_endtag = target.end self.handle_data = target.data + self.handle_cdata = target.cdata # activate parser self.parser = sgmlop.XMLParser() @@ -78,6 +79,7 @@ class SlowParser(xmllib.XMLParser): def __init__(self, target): self.unknown_starttag = target.start self.handle_data = target.data + self.handle_cdata = target.cdata self.unknown_endtag = target.end xmllib.XMLParser.__init__(self) @@ -108,6 +110,11 @@ class docParser: print "data %s" % text self._data.append(text) + def cdata(self, text): + if debug: + print "data %s" % text + self._data.append(text) + def start(self, tag, attrs):