RFR: 8313931: Javadoc: links to type parameters actually generate links to classes [v3]

[Jonathan Gibbons]

On Thu, 8 Aug 2024 09:38:57 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> > Just from reading that alone, (and not reading code or sample output yet) that seems mildly questionable, in that we otherwise generally encourage the provision of `@param` tags for all parameters, whether they are type-level or member-level type-parameters, or plain old executable (constructor, method) parameters.
> > (Update: maybe I misread or misunderstood the comment.)
> 
> What I meant is that `javadoc` by itself will not create links to member-level type parameters, but it is possible to create such links using `{@link ...}` or `@see ...`. However, the anchor/id used in those links will only be valid if the target type parameter is documented with a `@param` tag. So it's up to the author to make sure the link targets are defined.
> 
> In contrast, for type-level type parameters which are always linked by `javadoc`, the code in this PR generates the `id` attributes within the signature in the top-level heading if type parameters are not documented by `@param` tags.

Yes, I completely misunderstood the comment the first time I read it. My apologies for the noise. The effect you are actually 
describing is good.

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

PR Comment: https://git.openjdk.org/jdk/pull/20494#issuecomment-2276632414