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

Changes requested by prappo (Reviewer).

src/java.compiler/share/classes/javax/lang/model/element/package-info.java line 113:

> 111:  *
> 112:  * @see javax.lang.model.util.Elements
> 113:  * @see javax.lang.model##elementsAndTypes Element and Types

While it's a nice way to emphasize that one element maps to many types, I think it's a typo: the heading is "Elements and Types".
Suggestion:

 * @see javax.lang.model##elementsAndTypes Elements and Types

src/java.compiler/share/classes/javax/lang/model/type/package-info.java line 37:

> 35:  *
> 36:  * @see javax.lang.model.util.Types
> 37:  * @see javax.lang.model##elementsAndTypes Element and Types

Suggestion:

 * @see javax.lang.model##elementsAndTypes Elements and Types

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

PR Review: https://git.openjdk.org/jdk/pull/15097#pullrequestreview-1580099834
PR Review Comment: https://git.openjdk.org/jdk/pull/15097#discussion_r1295573445
PR Review Comment: https://git.openjdk.org/jdk/pull/15097#discussion_r1295578497