Reference docs for overloaded functions

I notice that the API reference gets a little confused by overloaded functions. Here’s the constructor for NodePath:

An argument list isn’t displayed for any other than the first overload. Because of this, I keep having to go back to the source for any serious reference needs. Is there any way around this?

Additionally, there’s a problem where random comments in the .h are pulled into the documentation for the first function found, e.g. PandaNode’s constructor documentation:

The really confusing thing there is that the extra stuff comes after the prototype but before the description.

Yeah, it’s a conundrum. It’s merely because interrogatedb does not support exporting overloaded functions (and many other things, such as functions that return a list, like NodePath.getChildren())

So eventually, we’ll probably move to a different tool for generating the API reference.

Actually, it’s not really true. interrogatedb has always supported exporting all of the overloaded functions; they’re called “wrappers” in interrogate’s nomenclature, and you can iterate through all the wrappers of a particular function with interrogate_function_number_of_python_wrappers(). One thing it hasn’t supported before, though, is a per-wrapper comment, instead of a single overall comment for the overall function. That’s easy to add, though, and I’ve just done so.

There is this lame thing called interrogate_function_prototype(), which only returned the C-style prototype of one arbitrary overload. I’ve just extended this to return all of the overloads instead (in a multi-line string). I’m not sure if this is the function we were calling to generate that one C-style prototype line, and this may have confused you (and Josh) into thinking that interrogate didn’t support overloads. But I think this is not really a good function to use anyway; for the purposes of generating documentation, it’s better to construct the prototype by hand out of the wrapper parameters, since this is what is actually available to the user. You can do this by iterating through interrogate_wrapper_number_of_parameters().

Also, while I was in there, I added support for the MAKE_SEQ functions to interrogatedb. These are enumerated in a separate list; for a particular class, you can iterate through interrogate_type_number_of_make_seqs(), then query interrogate_make_seq_[seq|num|element]_name() for each one. The three strings represent the name of the generated sequence method, e.g. get_things(), the get_num_things() method, and the get_thing() method; these three names can be used to synthesize a reasonable doc string, I think.

There are still some things missing in interrogatedb, of course. The extensions_native functions are absent, but in the long term, I’d like to move these into the C++ source code somewhere anyway (towards the goal of moving away from PandaModules), and then they could probably be added to interrogatedb. It also still lacks comments for the functions defined in dtool, which is a harder problem to solve.

Not to say that finding an alternative way to generate this documentation is an altogether bad idea; I don’t really know. But we shouldn’t do so just because interrogatedb appears to lack these simple features. :slight_smile:

Oh, you’ll need to rebuild all of your .in files, since I just changed this format a bit.


Hey, that’s awesome, thanks! I’ll soon take a look how I can integrate your fixes into