On Tue, 15 Oct 2024 02:10:30 GMT, Chen Liang <li...@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.
Good idea. I guess we should always do this.
> 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.
It's meant to help make this more concrete for readers who aren't accustomed to
speaking abstractly about "declarations". I've actually expanded it to "field
or method" now. I certainly don't want to reference any particular modifier
though. Does it work now?
I do realize that mentioning counts of things of is a pretty dodgy idea, almost
"daring" the text to go stale. I could go either way about it but I want to try
to defend it for a moment though.
The first question is whether citing a number like this has any positive value
in the first place. This is absolutely subjective and it could just be my own
"psychology" speaking only, but I think it lends "concreteness". When I read
things like this it gives me more of a feeling of security that I'm really
getting the full story and I can count on it. I don't know, I can't claim any
more objective benefit than that, really.
As for the staleness issue, I'd claim that avoiding the numbers would basically
mean we're hoping that the text might stay "accidentally current", when really
we need to re-review the full text any time anything changes to quite
*actively* search for what to freshen up. If a stale number helped us notice
that the text hadn't be rethought yet, maybe it would be a good thing...... meh?
> 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.
Fixed
> 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.
Good catch!
> 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.
Well, this is one of the ambiguous contexts listed above. Not sure if I'm
reading this right. What's the "inconsistency" you mean?
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1801503770
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1801532150
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1801516766
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1801505164
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1801511302
