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 86:

> 84:  * be represented by different objects to distinguish between these two
> 85:  * cases. The <em>definition</em> of {@code java.lang.String} itself
> 86:  * is annotated with neither of the type annotations in question.

Out of curiosity, how does this method from `Types` fit into this paragraph?

     * <p>Since annotations are only meta-data associated with a type,
     * the set of annotations on either argument is <em>not</em> taken
     * into account when computing whether or not two {@code
     * TypeMirror} objects are the same type. In particular, two
     * {@code TypeMirror} objects can have different annotations and
     * still be considered the same.
     *
     * @param t1  the first type
     * @param t2  the second type
     * @return {@code true} if and only if the two types are the same
     */
    boolean isSameType(TypeMirror t1, TypeMirror t2);

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

> 120:  * the declaration. Otherwise, for a non-generic class or interface,
> 121:  * the prototypical type mirror corresponds to an unannotated use of
> 122:  * the type.)

Perhaps I'm not quite following it, but why juxtapose "default" parameterization with being unannotated? I assume, for a generic class or interface, the prototypical type is also unannotated, no?

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

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