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

[Kevin Bourrillion]

On Tue, 15 Oct 2024 19:54:08 GMT, Chen Liang <liach at openjdk.org> wrote:

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

Okay, I see the connection. I'm trying to think about why I used the word "ambiguous" to talk about the case above. I think there are 2 reasons

1. For purposes of answering "which of the two kinds of annotations is this, anyway?" But in this case, it's not so much that it's ambiguous, it's just that its *both*.
2. Specifically because of the `@DualPurposeAnnot String[] field;` problem. It's maybe "ambiguous" whether this is trying to say something about the field or the _component_ type of the array type.

I think I'll try describing this situation without "ambiguous".

Getting back to record/field, I don't see a problem as long as any annotation interface that targets both kinds doesn't try to document incompatible *meanings* for the two.

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

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