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

[Joe Darcy]

On Wed, 16 Aug 2023 10:05:14 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> 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.
>
>> prototypical type
> 
> FWIW, that term is used multiple times in that package. Maybe it's worth defining and `{@index}`-ing, in a separate PR?

Yes, javax.lang.model has long used "prototypical type" -- I'll making the index entry, etc. in a follow-up changeset; good suggestion.

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

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