Hello,
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.
* @Overrides are consistently used for the annotation-related methods.
* 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. The
AnnotatedElement interface has three default methods and
java.lang.Module uses those default implementations. While would be
possible to introduce overrides in Module for the sole purpose of
hosting javadoc while the implementations defer to the ones in the
AnnotatedElement interface, I don't think it is worthwhile to do so. The
text for the isAnnotationPresent predicate was *not* updated to note
declaration vs type annotation; this is implicit by the operational
definition of the method in terms of getAnnotation's behavior.
I've filed a follow-up bug to make similar notes in the javax.lang.model
API, JDK-8225495: "Note whether returned annotations are declaration
annotations or type annotations."
Thanks,
-Joe
