RFR: 8374752: Add more JLS links to javax.lang.model.element.*

[Chen Liang]

On Thu, 8 Jan 2026 01:54:23 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> The various modeling interfaces in javax.lang.model.element.* would benefit from more direct links to the corresponding JLS sections.

src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java line 42:

> 40:  * @jls 8.4 Method Declarations
> 41:  * @jls 8.4 8.6 Instance Initializers
> 42:  * @jls 8.4 8.7 Static Initializers

Suggestion:

 * @jls 8.6 Instance Initializers
 * @jls 8.7 Static Initializers

src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java line 90:

> 88:  * @jls 8.10 Record Classes
> 89:  * @jls 9.1 Interface Declarations
> 90:  * @jls 9.6 Annotation Interfaces

Maybe JLS 9.5 Member Class and Interface Declarations too?

Also the special kinds of classes/interfaces are not really important here; they only appear once. I would make them inline tags at their appearance sites in the 1st paragraph.

src/java.compiler/share/classes/javax/lang/model/element/TypeParameterElement.java line 39:

> 37:  * @see TypeVariable
> 38:  * @jls 8.1.2 Generic Classes and Type Parameters
> 39:  * @jls 9.1.2 Generic Interfaces and Type Parameters

8.4.4 and 8.8.4 too, please. See the links JLS 4.4 makes.

src/java.compiler/share/classes/javax/lang/model/element/VariableElement.java line 40:

> 38:  * @jls 8.9.1 Enum Constants
> 39:  * @jls 8.4.1 Formal Parameters
> 40:  * @jls 8.8.1. Formal Parameters

Suggestion:

 * @jls 8.8.1 Formal Parameters

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

PR Review Comment: https://git.openjdk.org/jdk/pull/29103#discussion_r2670642960
PR Review Comment: https://git.openjdk.org/jdk/pull/29103#discussion_r2670647039
PR Review Comment: https://git.openjdk.org/jdk/pull/29103#discussion_r2670656758
PR Review Comment: https://git.openjdk.org/jdk/pull/29103#discussion_r2670660000