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
* docs/libvirt-api.xml: Re-build for fixed descriptions

1 files changed, 13 insertions, 12 deletions

diff --git a/generator.py b/generator.py
index c34cb34..178a415 100755
--- a/generator.py
+++ b/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):
         if debug:
             print "start %s, %s" % (tag, attrs)
@@ -843,20 +850,14 @@ def writeDoc(name, args, indent, output):
      val = string.replace(val, "NULL", "None");
      output.write(indent)
      output.write('"""')
-     while len(val) > 60:
-         if val[0] == " ":
-	     val = val[1:]
-	     continue
-         str = val[0:60]
-         i = string.rfind(str, " ");
-         if i < 0:
-             i = 60
-         str = val[0:i]
-         val = val[i:]
+     i = string.find(val, "\n")
+     while i >= 0:
+         str = val[0:i+1]
+         val = val[i+1:]
          output.write(str)
-         output.write('\n  ');
+         i = string.find(val, "\n")
          output.write(indent)
-     output.write(val);
+     output.write(val)
      output.write(' """\n')
 
 def buildWrappers():