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

[Joe Darcy]

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