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

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.