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
Attachment:
signature.asc
Description: OpenPGP digital signature
-- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list