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