Need better support for multi-methods

[cgay]

A current example that is a bit of a conundrum for me....

The transcendentals module has a lot of functions that have 4 methods. For example, take atan2:

atan2(<single-float>, <single-float>)
atan2(<double-float>, <single-float>)
atan2(<single-float>, <double-float>)
atan2(<double-float>, <double-float>)

How to document these?

Problem 1: Obviously we don't want to duplicate the entire section of documentation for all four methods, but there doesn't seem to be any way to reference a particular method specialization's documentation. It's common to do a minor conversion and then call the "primary" method.

Problem 2: Even if we could reference a particular method specialization, I suspect there would be many cases (and atan2 is an example) where it would be easier to read the documentation if it were all in a single section listing all method specializations. A natural way to do this would be to allow multiple :specializer: annotations under one .. method:: atan2. I'm also thinking perhaps we should allow :specializer: to be used (multiple times) under .. generic-function:: for cases like this where everything is sealed and all methods are known.

(If we do allow multiple :specializer: annotations, it will have an effect on how we solve the "reference a particular method" problem.)

I don't have it all figured out, obviously. Anyone have thoughts on this?

[cgay]

I was wrong about the links to specific method specializations not working. I'll try using that and see how it looks.

[cgay]

I think this can work. It would help to have the darker-blue heading line be a different color for the gf and the methods. Or to remove it completely for the methods. (Optionally, because sometimes the gf is can't immediately precede the methods.)

[cgay]

Also possible:

A :see_methods: role to generate links to known methods that (inside a generic-function:: directive) implement the generic or that (inside a class:: directive) specialize at least one argument on the class.