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

>> 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?

Say, all functions found in libvirt.h (or libvirt.h.in for that matter), plus virterror.h are public, everything else is not.

> 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?

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.