[libvirt] [PATCH v2 1/7] docs: abort when missing return or argument documention

[Eric Blake]

On 01/29/2013 08:05 AM, Claudio Bley wrote:
> When a function has no associated information to one of its
> arguments or its return type we report it and stop with an error.

s/documention/documentation/ in the subject.

> 
> Signed-off-by: Claudio Bley <cbley at av-test.de>
> ---
>  docs/apibuild.py |   15 +++++++++++++--
>  1 file changed, 13 insertions(+), 2 deletions(-)

In isolation, this fails 'make check' and 'make syntax-check'; please
fix your series to have this patch apply cleanly, and/or call out the
prerequisite patches that must be reviewed and applied first.

> @@ -2462,6 +2469,10 @@ class docBuilder:
>          output.write("</api>\n")
>          output.close()
>  
> +        if self.errors > 0:
> +            print >>sys.stderr, "apibuild.py: %d error(s) encountered during generation. Stop." % self.errors

"Stop." doesn't add anything to the error message; it's already obvious
from 'make' exiting that things stopped abnormally.

Here's what I suggest squashing in to fix the 'make syntax-check' side
of things:

diff --git i/docs/apibuild.py w/docs/apibuild.py
index 0ca6e7c..79b8795 100755
--- i/docs/apibuild.py
+++ w/docs/apibuild.py
@@ -2191,7 +2191,7 @@ class docBuilder:
                 if ret[0] == "void":
                     output.write("      <return type='void'/>\n")
                 elif ret[1] == None or ret[1] == '':
-                    self.error("Missing documentation for return of
function `%s'." % name)
+                    self.error("Missing documentation for return of
function `%s'" % name)
                 else:
                     output.write("      <return type='%s'
info='%s'/>\n" % (
                              ret[0], escape(ret[1])))
@@ -2200,7 +2200,7 @@ class docBuilder:
                 if param[0] == 'void':
                     continue
                 if param[2] == None or param[2] == '':
-                    self.error("Missing documentation for arg `%s' of
function `%s'." % (name, param[1]))
+                    self.error("Missing documentation for arg `%s' of
function `%s'" % (name, param[1]))
                 else:
                     output.write("      <arg name='%s' type='%s'
info='%s'/>\n" % (param[1], param[0], escape(param[2])))
                     self.indexString(name, param[2])
@@ -2470,7 +2470,7 @@ class docBuilder:
         output.close()

         if self.errors > 0:
-            print >>sys.stderr, "apibuild.py: %d error(s) encountered
during generation. Stop." % self.errors
+            print >>sys.stderr, "apibuild.py: %d error(s) encountered
during generation" % self.errors
             sys.exit(3)

         filename = "%s/%s-refs.xml" % (self.path, self.name)

Then we do have our hands full with some missing docs:

  GEN      apibuild.py.stamp
Error: Missing documentation for return of function `virConnCopyLastError'
Error: Missing documentation for arg `virConnCopyLastError' of function
`conn'
Error: Missing documentation for arg `virConnCopyLastError' of function `to'
Error: Missing documentation for return of function `virConnGetLastError'
Error: Missing documentation for arg `virConnGetLastError' of function
`conn'
Error: Missing documentation for arg `virConnResetLastError' of function
`conn'
Error: Missing documentation for arg `virConnSetErrorFunc' of function
`conn'
Error: Missing documentation for arg `virConnSetErrorFunc' of function
`userData'
Error: Missing documentation for arg `virConnSetErrorFunc' of function
`handler'
Error: Missing documentation for arg `virConnectCloseFunc' of function
`conn'
Error: Missing documentation for arg `virConnectCloseFunc' of function
`reason'
Error: Missing documentation for arg `virConnectCloseFunc' of function
`opaque'
Error: Missing documentation for arg
`virConnectDomainEventBlockJobCallback' of function `disk'
Error: Missing documentation for arg
`virConnectDomainEventBlockJobCallback' of function `opaque'
Error: Missing documentation for return of function
`virConnectDomainEventCallback'
Error: Missing documentation for return of function `virCopyLastError'
Error: Missing documentation for arg `virCopyLastError' of function `to'
Error: Missing documentation for arg `virDefaultErrorFunc' of function `err'
Error: Missing documentation for return of function `virEventAddHandle'
Error: Missing documentation for arg `virEventAddHandle' of function `fd'
Error: Missing documentation for arg `virEventAddHandle' of function
`events'
Error: Missing documentation for arg `virEventAddHandle' of function `cb'
Error: Missing documentation for arg `virEventAddHandle' of function
`opaque'
Error: Missing documentation for arg `virEventAddHandle' of function `ff'
Error: Missing documentation for return of function `virEventAddTimeout'
Error: Missing documentation for arg `virEventAddTimeout' of function
`timeout'
Error: Missing documentation for arg `virEventAddTimeout' of function `cb'
Error: Missing documentation for arg `virEventAddTimeout' of function
`opaque'
Error: Missing documentation for arg `virEventAddTimeout' of function `ff'
Error: Missing documentation for return of function `virEventRemoveHandle'
Error: Missing documentation for arg `virEventRemoveHandle' of function
`watch'
Error: Missing documentation for return of function
`virEventRemoveHandleFunc'
Error: Missing documentation for return of function `virEventRemoveTimeout'
Error: Missing documentation for arg `virEventRemoveTimeout' of function
`timer'
Error: Missing documentation for arg `virEventUpdateHandle' of function
`watch'
Error: Missing documentation for arg `virEventUpdateHandle' of function
`events'
Error: Missing documentation for arg `virEventUpdateTimeout' of function
`timer'
Error: Missing documentation for arg `virEventUpdateTimeout' of function
`timeout'
Error: Missing documentation for arg `virFreeError' of function `err'
Error: Missing documentation for return of function `virGetLastError'
Error: Missing documentation for arg `virResetError' of function `err'
Error: Missing documentation for return of function `virSaveLastError'
Error: Missing documentation for arg `virSetErrorFunc' of function
`userData'
Error: Missing documentation for arg `virSetErrorFunc' of function `handler'
apibuild.py: 44 error(s) encountered during generation


-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 621 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20130129/2e2a5579/attachment-0001.sig>