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

[Daniel P. Berrange]

On Fri, Sep 25, 2009 at 03:33:41PM +0200, Daniel Veillard wrote:
> 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 :-)

Hmm, I didn't check that yet, but I guess it shouldn't make any
difference, since the HTML will still collapse the whitespace
as before - we'd need to insert real <p> breaks & use <pre>
during generation of the HTML if we wanted to maintain any kind
of sane formatting

Daniel
-- 
|: Red Hat, Engineering, London   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|