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

[Hannes Wallnöfer]

On Wed, 7 Aug 2024 20:12:18 GMT, Jonathan Gibbons <jjg 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.

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

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