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

[Pavel Rappo]

On Wed, 16 Aug 2023 04:59:34 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> The goal is this change is to convey to the reader an accurate "vibe" for the dichotomy between elements and type in the javax.lang.model API rather than a primer on category theory (projection-embedding pairs, etc.).
>
> 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.

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

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