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

[Chen Liang]

On Thu, 31 Oct 2024 19:35:48 GMT, Chen Liang <liach at openjdk.org> wrote:

>> The Type and AnnotatedType hierarchies have been enigmatic to new users: users have no clue how to categorize arbitrary type objects, when it is safe to cast to more specific types, and the exact conditions for method contracts.
>> 
>> A manifest is [JDK-8306039](https://bugs.openjdk.org/browse/JDK-8306039), where people are massively confused by the conditions for `ParameterizedType::getOwnerType` to return `null`.
>> 
>> To fix these problems, I consulted the JLS, used some terms from there and added JLS links to make the definitions concise and accurate.
>> 
>> Here are some actions:
>> 1. Add section for hierarchy overview for both Type and AnnotatedType
>> 2. Specify the underlying type for different AnnotatedType subinterfaces
>> 3. Define "inner member class" for `getOwnerType`, and refer to it in `AnnotatedType::getAnnotatedOwnerType`.
>> 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 diffs: https://cr.openjdk.org/~liach/8343251-apidiff/java.base/java/lang/reflect/package-summary.html
>> 
>> 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 nine additional commits since the last revision:
> 
>  - Merge branch 'master' of https://github.com/openjdk/jdk into doc/owner-type
>  - Cleanup
>  - 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
>  - 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

Alex, thanks for your review!

Please review the APIdiff for the updated version at https://cr.openjdk.org/~liach/8343251-apidiff/java.base/java/lang/reflect/package-summary.html which includes the HTML rendering as well.

Notably, I gave up the interface hierarchy section and replaced it with a Java type or type argument to modeling interface mapping.  This is more natural from the Java programmer point of view, and makes the documentation more concise.  I have also included relevant examples, as you have recommended.  The terms for AnnotatedXxType are all updated to be "use" instead of "type", and I distinguished type versus type argument as well.

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

PR Comment: https://git.openjdk.org/jdk/pull/19977#issuecomment-2450679110