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

On 02/01/2013 05:48 AM, Claudio Bley wrote: 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