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

[Maurizio Cimadamore]

On Thu, 10 Aug 2023 22:37:33 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 five additional commits since the last revision:
> 
>  - 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 114:

> 112:  *
> 113:  * <p>All elements can be {@linkplain
> 114:  * javax.lang.model.element.Element#asType() mapped to} some type. For

I find this sentence not very clear. I'd phrase it more directly as "Class and interface elements map to..." but I think "prototypical type" is also part of the problem (what is it?). Perhaps it would be worth mentioning that this type has some interesting properties:
* if the element is a non-generic class, then the type is equal to a type mirror corresponding to the unannotated use of that type.
* if the element is a generic class, then the type is a parameterization of the class declaration, where the type arguments are the type variables of the declaring class/interface.

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

> 115:  * classes and interfaces, their elements get {@linkplain
> 116:  * javax.lang.model.element.TypeElement#asType() mapped to} a
> 117:  * prototypical type. Conversely, in general, many types can map to a

replace "to a given" with "to the same"

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

> 120:  * java.util.Set<E>}, and the type {@code java.util.Set<String>} would
> 121:  * all {@linkplain javax.lang.model.type.DeclaredType#asElement() map
> 122:  * to} the element for {@code java.util.Set}. Several kinds of types

It would be good to mention at least one `e.g.` for each case - e.g. `DeclaredType` have an element, but `ExecutableType` does not.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/15097#discussion_r1294904085
PR Review Comment: https://git.openjdk.org/jdk/pull/15097#discussion_r1294904356
PR Review Comment: https://git.openjdk.org/jdk/pull/15097#discussion_r1294906404