On Mon, 14 Oct 2024 20:31:51 GMT, Kevin Bourrillion <d...@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
