RFR: JDK-8281169: Expand discussion of elements and types [v3]

[Joe Darcy]

On Wed, 16 Aug 2023 16:35:46 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> src/java.compiler/share/classes/javax/lang/model/package-info.java line 81:
>> 
>>> 79:  * a {@code @DefinitelyNotNull} type annotation while the type of
>>> 80:  * the parameter is a {@code String} annotated with a {@code
>>> 81:  * @MightBeNull} type annotation. In a reflective API, since the set
>> 
>>> In a reflective API,
>> 
>> Nit: re-reading that bit made me pause for a moment and doubt that javax.lang.model is a reflective API, which I hope it is. We could help the reader by rephrasing that more assertively as "In a reflective API, such as this one," or dropping "In a reflective API" altogether.
>
> Will change the opening sentence to:
> 
> "Types and hierarchies of packages comprising a Java language model, a reflective API that models the declarations and types of the Java programming language."

(The text was initially written when core reflection and javax.lang.model were both discussed.)

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

PR Review Comment: https://git.openjdk.org/jdk/pull/15097#discussion_r1296175168