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

[Joe Darcy]

On Wed, 16 Aug 2023 10:27:40 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Joe Darcy has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains seven additional commits since the last revision:
>> 
>>  - Implement review feedback.
>>  - Merge branch 'master' into JDK-8281169
>>  - Iteration of spec update.
>>  - Merge branch 'master' into JDK-8281169
>>  - Checkpoint intermediate state.
>>  - Merge branch 'master' into JDK-8281169
>>  - JDK-8281169: Expand discussion of elements and types
>
> 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."

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

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