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

Reply via email to