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

[Eric Blake]

On 02/06/2013 09:13 AM, Claudio Bley wrote:

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

I'm no python expert, but if you want to write a patch, it sounds
reasonable.  Anything in a .h[.in] file under include/libvirt is public,
anything else is ignored when it comes to documenting public functionality.

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

Well, there's also libvirt-qemu.h and libvirt-lxc.h, but yes, that's the
idea.

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

Correct.  Again, I won't be the person writing it, but I don't mind
reviewing (it will help me learn more python).

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

Sure, if it works.

> 

-- 
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/20130206/9cea2500/attachment-0001.sig>