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

[Claudio Bley]

At Tue, 29 Jan 2013 12:02:35 -0700,
Eric Blake wrote:
> 
> [1  <text/plain; UTF-8 (quoted-printable)>]
> 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.

Fixed.

> > 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.

OK, will do.

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

OK, squashed in.

> 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

With commit 790d364ca282893b12afc9fa2779ba2ff70aa4de in place (ref.
https://www.redhat.com/archives/libvir-list/2013-January/msg02029.html),
we're down to 26 errors.

Of those, 19 are internal functions being part of the
"ignored_functions" dictionary in apibuild.py.

I'm just going to ignore them too, ie. will not generate an error if
documentation is missing.

Then, these are the remaining errors:

  GEN    apibuild.py.stamp
Error: Missing documentation for arg `conn' of function `virConnectCloseFunc'
Error: Missing documentation for arg `reason' of function `virConnectCloseFunc'
Error: Missing documentation for arg `opaque' of function `virConnectCloseFunc'
Error: Missing documentation for arg `disk' of function `virConnectDomainEventBlockJobCallback'
Error: Missing documentation for arg `opaque' of function `virConnectDomainEventBlockJobCallback'
Error: Missing documentation for return of function `virConnectDomainEventCallback'
Error: Missing documentation for return of function `virEventRemoveHandleFunc'
apibuild.py: 7 error(s) encountered during generation

When having
https://www.redhat.com/archives/libvir-list/2013-January/msg02071.html 
applied there are only the last two errors left.

Regarding virEventRemoveHandleFunc, I just overlooked this when
throwing together the above mentioned series. A followup patch is
coming.

It seems to me, that currently the return value of
virConnectDomainEventCallback isn't used at all. Should we just add

Returns [unused] you should always return 0.

Or should we just use the usual "-1 on error, 0 on success" wording?
But what are the consequences if you return -1 from this callback?
-- 
AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany
Phone: +49 341 265 310 19
Web:<http://www.av-test.org>

Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076)
Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern