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
