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

On Fri, Sep 25, 2009 at 01:28:51PM +0100, Daniel P. Berrange wrote: > 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)) Ah, okay you're using CDATA ! > 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): Okay makes sense, plus the large amount of return -> Returns changes ACK ! I'm still waiting to see what this gives in the HTML docs :-)