RFR: 8339852: Fix typos in java.compiler documentation

[Pavel Rappo]

On Tue, 10 Sep 2024 20:21:47 GMT, Chen Liang <liach at openjdk.org> wrote:

>> For convenience, here's the rendered documentation in question for JDK 23: https://download.java.net/java/early_access/jdk23/docs/api/java.compiler/javax/lang/model/AnnotatedConstruct.html#:~:text=containing
>
> The "type" terminology is outdated and is already migrated to "class or interface" or the applicable subtype elsewhere: https://bugs.openjdk.org/browse/JDK-8257636 and commit 952dc704

> The "type" terminology is outdated and is already migrated to "class or interface" or the applicable subtype elsewhere: https://bugs.openjdk.org/browse/JDK-8257636 and commit [952dc70](https://github.com/openjdk/jdk/commit/952dc704024d44c8f37449382fe769320f9dad1c)

@liach, I respect you as a fellow JLS reader. Not only am I aware of that JBS issue, but I also remember the respective PR being reviewed.

Unsurprisingly, I had a similar knee-jerk reaction to the word "type". So, before publishing this PR, I asked a JLS expert on its use in this context. He replied that although in general "type" should not to be conflated with "interface"/"class", in this context it is reasonable to use "type".

However, if we do decide to abandon "type", we need to inspect every use of it in this class very carefully. The closest terminology that I could find is JLS 9.7.1

> The `TypeName` specifies the annotation interface corresponding to the annotation. The annotation is said to be "of" that interface.

and JLS 9.6.3

> An annotation interface `A` is repeatable if its declaration is (meta-)annotated with an `@Repeatable` annotation ([§9.6.4.8](https://docs.oracle.com/javase/specs/jls/se22/html/jls-9.html#jls-9.6.4.8)) whose value element indicates a containing annotation interface of `A`.

Note how slightly dizzying the terminology is.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20937#discussion_r1752760437