Drake: mkdoc: Make overload docs less fragile to source ordering

[EricCousineau-TRI]

At present, mkdoc orders overloads according to source location, as documented here:
https://drake.mit.edu/doxygen_cxx/group__python__bindings.html

@jwnimmer-tri suggested the following:

• If an overload has a unique number of arguments, just append nargX.
• If two or more overloads share the same amount, just append the nice type names of everything and call it a day.

I've assigned it to myself, will probably not get to it for the next week or two, so if someone else wants to do it before then they can. (Jeremy mentioned he may.)

\cc @sherm1 @edrumwri @mitiguy

[jwnimmer-tri]

The first-pass PR uses doc_#args for arity-based overload disambiguation (not doc_narg#).

I think, for the second pass, instead of using the type names we should try using the parameter names.

And then, if there are still two overloads with the same arity and same parameter names, we just do doc_L### with a line number (instead of failing out of mkdoc), and the pydrake bindings author should go into the C++ code and change the parameter names before proceeding. I suspect that trying to use the type names will be one bridge too far.

[jwnimmer-tri]

For the overloads where arity isn't enough, the tokens are going to look like doc.LinearQuadraticRegulator.doc_5args_system_context_Q_R_N where each argument is either the formal parameter name (when it has one), or the typename when there is no variable name.

[EricCousineau-TRI]

For the final pass, where there is still ambiguity, rather than make authors try to figure out the correct overload, only to realize that they have to use LXYZ, why not accumulate the ambiguous symbols, then cause mkdoc.py to fail loudly?

I think that would be more useful, and we could accompany that with an error message explaining what to do (maybe even point to the source code to change).

[jwnimmer-tri]

There are many ambiguous docstrings, only some of which are ever cited from bindings (i.e., many of the ambiguous ones are dead constants). I don't in principle mind a hard failure, but we're still a few PRs away from measuring that out. I still have another round or two of disambiguation (e.g., overloading on const methods vs non-const methods with the same name) that need to happen first.

[jwnimmer-tri]

For the record, my approach to ambiguity was that every emitted name is unique and unambiguous. If we can't figure out a good name for an overloaded symbol, we emit a constant named doc_was_unable_to_choose_unambiguous_names so that the generation step always succeeds, but it may not have the symbol(s) that the developer wants.