RFR: 8345777: Improve sections for inherited members [v2]

[Pavel Rappo]

On Thu, 12 Dec 2024 11:41:26 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> > > Omit type bounds and do not create separate links for type parameters in links to inherited nested classes
> > 
> > 
> > But I also wonder if the below is acceptable information loss.
> 
> In my opinion, it is not just acceptable but a clear improvement. Consider the benefits of the additional links for type parameters and bounds:
> 
> * The type parameter links are almost completely redundant with the link to the encosing type, as type parameters are documented prominently at the top of the type documentation.
> * The bound on the last type parameter in this particular case doubles all the links again, leading to 8 links to basically the same resource (except for highlighting individual type parameters).
> 
> I admit that the recursive bound is a special case, and a link would make more sense if it was a different type. But even in that case I would argue that it's not at the link level that we have to provide these details, and in fact we don't do that in other similar places (e.g. lists of super/implementing/extending types etc).
> 
> As to the cost of providing these additional links in this context: there is a cost with every link we add in terms of demanding attention for the user, but in this case it's particularly bad, because the context (list of inherited nested classes) and the content (linked signature of generic class) both basically use the same format (a comma-separated list of links). Which is how we end up with a hairball of largely redundant links when we really wanted to provide a link to one nested class.

Alternatively, we can indicate that the class or interface declaration has more interesting to it by maybe placing … (`…`).

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

PR Comment: https://git.openjdk.org/jdk/pull/22651#issuecomment-2538713103