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 63:
> 61: * <h3 id="ambiguous">Ambiguous contexts</h3>
> 62: *
> 63: * <p>For six kinds of declarations, type-use annotations can also
The GitHub UI isn't letting me reply directly to the relevant existing comment.
In any case, I strongly advise against referring to concrete numbers for
language contexts in the JLS. As noted, that is a hazard for the comments
getting out of date with language changes or previewing language changes. The
JLS text does favor use of such numbers, but the JLS as a whole is in the same
maintenance domain so there is a much higher chance that when adding another
context, all the N's in the JLS get updated to (N+1)'s.
src/java.base/share/classes/java/lang/annotation/ElementType.java line 79:
> 77: * (like {@link java.lang.reflect.Field#getAnnotations}) will not
> 78: * return type-use annotations found in the same location, and
> 79: * vice-versa.
If type annotations are going to be discussed, it would be helpful to readers
to include something along the lines of "in core reflection, type annotations
can are retrieved by methods that return AnnotatedType."
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1809223497
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1809226800
