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

[Eric Blake]

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.  Why then are we hiding the documentation for this function?  I
don't think it should be in the ignored_functions list.  Or put another
way, I think the point of the ignored_functions list is to let
apibuild.py snarf in entire files that contain both public and private
functions, and to omit ALL documentation for private functions.

Probably what happened is that virEventUpdateHandle used to be
internal-only until 0.9.3, but we never updated the documentation
generation to match when we finally made it public.

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.

-- 
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/20130201/d30fb9c7/attachment-0001.sig>