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