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

[Joe Darcy]

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