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

[Daniel Veillard]

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 :-)

Daniel

-- 
Daniel Veillard      | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
daniel at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/