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

[Joe Darcy]

On Thu, 8 Jan 2026 02:23:59 GMT, Chen Liang <liach 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

Whoops, typo; thanks for catching that.

> 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.

Sure; might as well be complete and include 9.5.

However, I think it is better for the flow the 1st paragraph to have the links to enums, records, etc. down at the bottom with the other citations.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/29103#discussion_r2670875658
PR Review Comment: https://git.openjdk.org/jdk/pull/29103#discussion_r2670880736