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

[Chen Liang]

On Tue, 15 Oct 2024 16:22:36 GMT, Kevin Bourrillion <duke at openjdk.org> wrote:

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

Yep, the "field or method declaration" is much clearer. I felt the old text "field declaration" was trying to emphasize the modifier status of annotations.

And for count: that's fair. We bump Java version every six months, too!

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

Say you have a record component like:
`record Sample(@Anno int val)`
Where `@Anno` applies to `RECORD_COMPONENT` and `FIELD`.

Then we can observe this annotation on the record component or its field, but not its getter method. This creates a scenario similar to how people can observe an annotation on both the type-use and the declaration for some common annotations like `@Nullable`, yet some annotations are only present on one of the sites.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1801832808
PR Review Comment: https://git.openjdk.org/jdk/pull/21506#discussion_r1801828565