[libvirt] [PATCH v3 06/13] docs: only generate function argument info for args with a description

[Claudio Bley]

At Fri, 01 Feb 2013 10:22:28 -0700,
Eric Blake wrote:
> 
> On 02/01/2013 05:48 AM, Claudio Bley wrote:
> > 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?
> 
> Indeed, when you frame the question that way, it seems like the smartest
> thing is to omit all output during apibuild.py for any function in the
> ignored_functions list; then the XSL processing wouldn't have anything
> to process in the first place.
> 
> Hmm, I think this points out a bigger problem.  Looking at
> ignored_functions, I see it starts with:
> 
>   "virDomainMigrateFinish": "private function for migration",
> 
> Tracking down that function, it exists in src/libvirt.c, but is NOT in
> libvirt.h.in (just libvirt_internal.h), and is only exported in
> libvirt_private.syms.  So not documenting it is the right thing to do.
> On the other hand, virEventUpdateHandle is a public entry point since
> libvirt 0.9.3, and declared in libvirt.h.in, so it is a public entry
> point.

As you determined this easily by looking at which file a function is
declared in, would it make sense to employ the same logic in
apibuild.py when deciding which function is public or not?

Say, all functions found in libvirt.h (or libvirt.h.in for that
matter), plus virterror.h are public, everything else is not.

> So, we may not need this patch after all; instead, we need a patch that
> fixes the list of ignored_functions to be accurate to what is really
> private, when snarfing in all files that contain documentation for
> public functions.

And another one which actually omits generating entries for /ignored/
functions in libvirt-api.xml et. al., right?

But, apparently, there are no ignored functions in libvirt-api.xml
(et. al.). Probably because of some refactoring which put those
functions out of the way into internal headers...

So, we could just as well ditch the ignored_functions dictionary in
apibuild.py because it only confuses people than being of any help or
use.
-- 
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