JDK 13 RFR of JDK-708660: (reflect) Clarifications to javadoc for getGeneric*Type methods in j.l.r

[Alex Buckley]

On 6/8/2019 4:04 PM, Joe Darcy wrote:
> Please review the doc clarifications to address
>
>      JDK-708660: (reflect) Clarifications to javadoc for getGeneric*Type
> methods in j.l.r
>      webrev: http://cr.openjdk.java.net/~darcy/7086604.0/
>      specdiff:
> http://cr.openjdk.java.net/~darcy/7086604.0.specdiff/overview-summary.html
>
> A few comments on the changes:
>
> * The phrasing "type arguments" rather than "type parameters" is used as
> appropriate.

Great!

> * The bulk of the changes relate to noting whether or not *declaration
> annotations* as opposed to *type annotations* are returned by a
> particular method; see the JLS for more detailed discussion of the
> differences. The annotations returned from the AnnotatedElement methods
> as implemented by java.lang.{Class, Package, Module} and the classes in
> java.lang.reflect.* are declaration annotations. The annotations
> returned by the subtypes of AnnotatedType are *type annotations*. To
> allow the declaration vs type annotation distinction to be indicated,
> the basic method specs from AnnotatedElement are {@inheritDoc}'ed and
> then augmented with the appropriate declaration or type annotation note.
> For declaration annotations, these notes need to be added in
> java.lang.Class, java.lang.Package, java.lang.Module,
> java.lang.reflect.Parameter, and java.lang.reflection.AccessibleElement,
> the latter being the common superclass of Field, Constructor,
> Executable, etc. Adding the "type annotation" note to AnnotatedType
> suffices to associate it with all the right subinterfaces.

My comments on compiler-dev, in the context of JDK-8225495 for the 
jx.l.m API, apply here too. Having each small reflective method qualify 
what's being returned is letting the major modeling types off the hook:

- j.l.r.AnnotatedElement should own the fact that declaration 
annotations are returned by its methods as found in 
Class/Package/Module/Parameter/AccessibleElement. It should then point 
to its child, j.l.r.AnnotatedType, as the place to read about type 
annotations.

- j.l.r.AnnotatedType should own the fact that type annotations can 
appear within many declarations, statements, and expressions in a 
program, as evidenced by the 20 or so `getAnnotated...` methods revealed 
by javadoc search.

The above is meant to be an outline, not a specific proposal, but the 
text from my jx.l.m upgrade should apply fairly cleanly to 
j.l.r.AnnotatedElement.

Alex