RFR: 8343251: Facelift for Type and AnnotatedType specifications [v2]

[Alex Buckley]

Hi Chen,

On 10/30/2024 11:51 AM, Chen Liang wrote:
>>> 2. Specify the underlying type for different AnnotatedType subinterfaces

The new "Interface Hierarchy" starts with: "Annotated use of types in 
the Java programming language is modeled with these subinterfaces".

Only _annotated_ uses? Even though AnnotatedType generally speaks about 
the *potentially* annotated use of a type" ?

I think your best bet when introducing the interface hierarchy is to 
explain that some types are rich in structure, and each part of the 
structure is itself a type that can potentially be annotated. For 
example, the parameterized type `Collection<? extends Number>` actually 
denotes three uses of types that can potentially be annotated 
individually: (1) the parameterized type as a whole (`@Foo Collection<? 
extends Number>`); (2) the wildcard type argument (`Collection<@Bar ? 
extends Number>`); and (3) the wildcard type bound (`Collection<? 
extends @Quux Number>`). The AnnotatedType interface grants access to 
the potentially annotated use of a type as a whole (`@Foo 
Collection<..>`). If that type is rich in structure, subinterfaces of 
AnnotatedType grant additional access to the potentially annotated uses 
of types in parts of that structure.  [Note I have not said "structural 
type" at any point.]

With this in mind, you can see that e.g. AnnotatedParameterizedType 
doesn't model [the potentially annotated use of] parameterized types as 
such. AnnotatedType already models that: I can call getAnnotations() to 
get the @Foo in `@Foo Collection<..>`. What AnnotatedParameterizedType 
models is the potentially annotated use of types _serving as type 
arguments of a parameterized type_.

Similarly, AnnotatedWildcardType doesn't model wildcard type arguments 
as such -- you get the @Bar in `Collection<@Bar ? extends Number>` from 
the aforementioned AnnotatedParameterizedType, regardless of whether the 
type argument is a wildcard or not. What AnnotatedWildcardType models is 
the potentially annotated use of types _serving as upper or lower bounds 
of a wildcard type argument_. The @Quux in `<@Bar ? extends @Quux Number>`.

I recommend clarifying the interface hierarchy along those lines. Make 
liberal use of the same example type throughout, to demonstrate which 
part is which, and which use-of-a-type is which.

As for getType: before any interface hierarchy, you should explain what 
the underlying type of the annotated-type-as-a-whole is. An 
AnnotatedType that represents `@Foo int` yields the Class object for int 
as the underlying type. An AnnotatedType that represents `@Foo 
Collection<@Bar ? extends @Quux Number>` yields `Collection<? extends 
Number>` as the underlying type. By saying all this first, you can 
streamline the interface hierarchy to avoid mentioning 
getType/underlying types.

>>> 3. Define "inner member class" for `getOwnerType`, and refer to it in `AnnotatedType::getAnnotatedOwnerType`.

This definition and use are very nice to see.

Alex

>>> 4. Improve the specification for `ParameterizedType::getActualTypeArguments` to note the existence of owner types; also for annotated version
>>> 5. Minor improvements to `ParameterizedType::getRawType`
>>> 6. Move the equals specification for `ParameterizedType` to the actual `equals` method.
>>>
>>> API docs: https://cr.openjdk.org/~liach/8343251-api/java.base/java/lang/reflect/package-summary.html#class-summary
>>>
>>> Please review the associated CSR as well.
>>
>> Chen Liang 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:
>>
>>   - Mass improvements
>>   - Merge branch 'master' of https://github.com/openjdk/jdk into doc/owner-type
>>   - Merge branch 'master' of https://github.com/openjdk/jdk into doc/owner-type
>>   - Merge branch 'master' of https://github.com/openjdk/jdk into doc/owner-type
>>   - 8306039: ParameterizedType.getOwnerType() documentation is incomplete about null result
> 
> cc'ing this to the javac list: this brings in a few definitions from the JLS to core reflection, for which the compiler developers know better.
> 
> -------------
> 
> PR Comment: https://git.openjdk.org/jdk/pull/19977#issuecomment-2448079672