On Tue, 15 Oct 2024 16:22:36 GMT, Kevin Bourrillion <d...@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
