Reference docs for overloaded functions

[sneftel]

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

NodePath::NodePath(void);

Description: This constructs an empty NodePath with no nodes.
Description: This constructs a new NodePath with a single node. An ordinary, unattached PandaNode is created with the indicated name.
Description: This constructs a NodePath for the indicated node. If the node does not have any parents, this creates a singleton NodePath; otherwise, it automatically finds the path from the node to the root. If the node has multiple paths to the root, one path is chosen arbitrarily and a warning message is printed (but see also NodePath::any_path(), below).
Description: Constructs a NodePath with the indicated parent NodePath and child node; the child node must be a stashed or unstashed child of the parent.
Description:

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:

PandaNode
PandaNode::PandaNode(string const &name);

There are two different interfaces here for making and breaking parent-child connections: the fundamental PandaNode interface, via add_child() and remove_child() (and related functions), and the NodePath support interface, via attach(), detach(), and reparent(). They both do essentially the same thing, but with slightly different inputs. The PandaNode interfaces try to guess which NodePaths should be updated as a result of the scene graph change, while the NodePath interfaces already know.
The NodePath support interface functions are strictly called from within the NodePath class, and are used to implement NodePath::reparent_to() and NodePath::remove_node(), etc. The fundamental interface, on the other hand, is intended to be called directly by the user.
The fundamental interface has a slightly lower overhead because it does not need to create a NodePathComponent chain where one does not already exist; however, the NodePath support interface is more useful when the NodePath already does exist, because it ensures that the particular NodePath calling it is kept appropriately up-to-date.
Description:
Description: Do not call the copy constructor directly; instead, use make_copy() or copy_subgraph() to make a copy of a node.

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

[rdb]

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.

[drwr]

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.

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

David

[rdb]

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