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

[Pavel Rappo]

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

I urge other reviewers to take an opportunity to look at the `javax.lang.model` specification holistically. This is to make sure that these concepts that package-info.java is talking about do paint the big picture and are uniform across many places, including but not limited to:

  * top-level doc comment for DeclaredType
  * top-level doc comment for TypeElement

FWIW, I like the concept of a _prototypical type_, coined and consistently used by javax.lang.model.

This iteration is succinct, albeit it might need if only a small bit of wordsmithing.

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

PR Comment: https://git.openjdk.org/jdk/pull/15097#issuecomment-1674653182