Re: [libvirt] [PATCH v3 06/13] docs: only generate function argument info for args with a description
At Thu, 31 Jan 2013 13:41:10 -0700,
Eric Blake wrote:
On 01/30/2013 08:38 AM, Claudio Bley wrote:
> When function arguments or return values lack a description there's no
> use in generating a meaningless "ARG1: " stanza.
Can you point to an example of an argument lacking a description?
Have a look at e.g. #virEventUpdateHandle
This is another case where I think we're better off fixing things
to
fail noisily so that we can fix our docs to be more complete, than
we are to paper over it with this patch.
The point is, we skip checking all functions contained in the
"ignored_functions" dictionary in apibuild.py.
We would have to do the same filtering inside the stylesheet also.
But why bother? We never get to XSL processing when apibuild.py fails
because of missing documentation.
Not to mention the increased maintenance cost keeping those two files
in sync.
Note, however, that I have no deep understanding about what it means
when a function ought to be "ignored" by apibuild.py.
Should we skip this function from the generated HTML documentation
perhaps?
All I could see was that comment parsing and checking is a bit relaxed
when a function is part of ignored_functions in mergeFunctionComment.
That's why I chose to do the same.
Claudio
--
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