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

[Alex Buckley]

On 10/31/2024 12:40 PM, Chen Liang wrote:
> 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.

Type has become difficult to read. Please lighten up the introductory 
paragraph. To do that, I recommend unifying the kinds of types/type 
arguments (primitive types, reference types, raw types, wildcard type 
arguments ...) with the mapping from types/type arguments to the 
interface hierarchy. One list, giving the kind of type + an example + 
the appropriate interface or subinterface.

Do the same in AnnotatedType. Also, drop the introduction of "current 
runtime" -- this is about the use of types/type arguments in programs.

Alex