On Fri, 5 Apr 2024 17:52:25 GMT, Jonathan Gibbons <j...@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
