RFR: 8325088: Overloads that differ in type parameters may be lost [v5]

[Pavel Rappo]

On Fri, 5 Apr 2024 17:52:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Approved, with two optional suggestions. Both could be considered style suggestions.
> 
> ## 1
> (Minor) While I like the new multi-valued return for `forMember(ExecutableElement executable)` I'm slightly surprised at the use of `List` rather than, say, a `record` that gives semantic meaning to the alternatives.
> 

Thanks for approval, Jon. This is my response to your minor suggestions only: although I read the bigger suggestion, it is indeed for when "such an improvement becomes necessary."

In essence, what we have here is a tuple, which in this case is best modelled by a list.

>From a perspective of a single documentation bundle, it does not matter which id we pick from a tuple as they are interchangeable. What matters is that we consistently pick the same id element for the same purpose. If we fail to do that, our intra-links will be broken.

>From a perspective of multiple documentation bundles that could link to each other, our choice of id should be consistent _and conventional_ (the convention is dictated by legacy bundles). Why? Because we not only want a new javadoc bundle to be able to link to, but we also want it to be able _to be linked to_.

Currently, we have 1-tuple and 2-tuple. But I can imagine we have 3-tuple in the future. A list can model n-tuple well. At an anchor creating site, we would iterate over the returned list and add nested `<div>`s (scale better than limited `<section><h3><a>`) with an id. At a link site, we would ask `ids.getFirst()`.

Both ordering and flexible arity is well provided by a list; I don't see why we need a record.

Does this make sense?

-------------

PR Comment: https://git.openjdk.org/jdk/pull/18519#issuecomment-2040526300