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

[Joe Darcy]

On Tue, 15 Aug 2023 17:29:15 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> 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 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.

Updated per your suggestions, I'll reflow the paragraphs once we've settled on the final text.

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

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