RFR: 8342566: Improve javadoc of java.lang.annotation.ElementType

[Chen Liang]

On Mon, 14 Oct 2024 20:31:51 GMT, Kevin Bourrillion <duke at openjdk.org> wrote:

> 8342566: Improve javadoc of java.lang.annotation.ElementType

src/java.base/share/classes/java/lang/annotation/ElementType.java line 42:

> 40:  * }
> 41:  *
> 42:  * <h2>Declaration annotations and type-use annotations</h2>

Meta: if we add an explicit id to the h2 tag, people can have a stable link to this subsection instead of having to update their link for each release, as the javadoc tool automatically generates an unstable id.

src/java.base/share/classes/java/lang/annotation/ElementType.java line 46:

> 44:  * <p>Most annotations in Java code are <b>declaration
> 45:  * annotations</b>, which act like modifiers of declarations (such as
> 46:  * a field declaration). The constants of this class cover all ten

"such as a field declaration" seems like a carry-over from the old example of `@Target(ElementType.FIELD)`, which is obsolete in the current text. I suggest to remove, or to present a concrete example like "acts like modifiers of decrations, such as the transitive modifier on a field declaration."

The asserted number "ten" might be outdated quickly and forgotten to be updated when we add new declarations such as pattern bindings.

src/java.base/share/classes/java/lang/annotation/ElementType.java line 57:

> 55:  * indicated (normally, immediately preceding that type). To enable
> 56:  * use as a type-use annotation, an annotation interface must
> 57:  * explicitly include {@link #TYPE_USE} in its list of targets. 

I would word like `an annotation interface must have a {@code @Target} that includes {@link #TYPE_USE}.` Main issue with existing text is the plain "target" word was undefined previously.

src/java.base/share/classes/java/lang/annotation/ElementType.java line 61:

> 59:  * <h3 id="ambiguous">Ambiguous contexts</h3>
> 60:  *
> 61:  * <p>For six kinds of declarations, type-use annotations can also

Same number assertion remark; pattern bindings most likely will have this same problem too.

src/java.base/share/classes/java/lang/annotation/ElementType.java line 133:

> 131:     /** 
> 132:      * The declaration of a formal parameter (of a method, constructor,
> 133:      * or lambda expression), exception parameter, or receiver

Receiver parameters are type-use only; they were only added in Java 8. JLS 9.7.4:

> **It is a compile-time error if an annotation of interface A is syntactically a modifier for:**
> - [...]
> - a receiver parameter, but A is not applicable in type contexts.

src/java.base/share/classes/java/lang/annotation/ElementType.java line 227:

> 225:      * RECORD_COMPONENT} or in addition to it. This allows the
> 226:      * annotation to be automatically copied to any generated elements
> 227:      * it applies to.

Doesn't this effectively become another "ambiguous context?" Note that in both cases, the observation of the annotations via the `class` file format (and subsequently, the core reflection API) is inconsistent.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1800319604
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1800315455
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1800318732
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1800320595
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1800326769
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1800327793