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

[Joe Darcy]

Proposed reduced scope changes for JDK-708660 at:

     http://cr.openjdk.java.net/~darcy/7086604.1/

Corresponding patch below.

Type vs declaration annotation clarification for core reflection will be 
done as follow-up work under JDK-8225540.

Thanks,

-Joe

--- old/src/java.base/share/classes/java/lang/Class.java 2019-06-10 
16:13:09.660882746 -0700
+++ new/src/java.base/share/classes/java/lang/Class.java 2019-06-10 
16:13:09.308882746 -0700
@@ -917,7 +917,7 @@
       *
       * <p>If the superclass is a parameterized type, the {@code Type}
       * object returned must accurately reflect the actual type
-     * parameters used in the source code. The parameterized type
+     * arguments used in the source code. The parameterized type
       * representing the superclass is created if it had not been
       * created before. See the declaration of {@link
       * java.lang.reflect.ParameterizedType ParameterizedType} for the
@@ -1097,7 +1097,7 @@
       *
       * <p>If a superinterface is a parameterized type, the
       * {@code Type} object returned for it must accurately reflect
-     * the actual type parameters used in the source code. The
+     * the actual type arguments used in the source code. The
       * parameterized type representing each superinterface is created
       * if it had not been created before. See the declaration of
       * {@link java.lang.reflect.ParameterizedType ParameterizedType}
--- old/src/java.base/share/classes/java/lang/reflect/Executable.java 
2019-06-10 16:13:10.320882746 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/Executable.java 
2019-06-10 16:13:09.968882746 -0700
@@ -266,7 +266,7 @@
       *
       * <p>If a formal parameter type is a parameterized type,
       * the {@code Type} object returned for it must accurately reflect
-     * the actual type parameters used in the source code.
+     * the actual type arguments used in the source code.
       *
       * <p>If a formal parameter type is a type variable or a parameterized
       * type, it is created. Otherwise, it is resolved.
--- old/src/java.base/share/classes/java/lang/reflect/Field.java 
2019-06-10 16:13:10.932882746 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/Field.java 
2019-06-10 16:13:10.588882746 -0700
@@ -243,9 +243,9 @@
       * Returns a {@code Type} object that represents the declared type for
       * the field represented by this {@code Field} object.
       *
-     * <p>If the {@code Type} is a parameterized type, the
-     * {@code Type} object returned must accurately reflect the
-     * actual type parameters used in the source code.
+     * <p>If the declared type of the field is a parameterized type,
+     * the {@code Type} object returned must accurately reflect the
+     * actual type arguments used in the source code.
       *
       * <p>If the type of the underlying field is a type variable or a
       * parameterized type, it is created. Otherwise, it is resolved.
--- old/src/java.base/share/classes/java/lang/reflect/Method.java 
2019-06-10 16:13:11.564882746 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/Method.java 
2019-06-10 16:13:11.224882746 -0700
@@ -269,7 +269,7 @@
       *
       * <p>If the return type is a parameterized type,
       * the {@code Type} object returned must accurately reflect
-     * the actual type parameters used in the source code.
+     * the actual type arguments used in the source code.
       *
       * <p>If the return type is a type variable or a parameterized 
type, it
       * is created. Otherwise, it is resolved.
--- old/src/java.base/share/classes/java/lang/reflect/TypeVariable.java 
2019-06-10 16:13:12.220882746 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/TypeVariable.java 
2019-06-10 16:13:11.852882746 -0700
@@ -72,7 +72,7 @@

      /**
       * Returns the {@code GenericDeclaration} object representing the
-     * generic declaration declared this type variable.
+     * generic declaration declared for this type variable.
       *
       * @return the generic declaration declared for this type variable.
       *

On 6/10/2019 12:54 PM, Joe Darcy wrote:
> Hello,
>
> Given upcoming deadlines and the scope of the feedback suggested, I 
> propose pushing the "type parameters" => "type arguments" fix under 
> JDK-708660 in JDK 13 and then reworking the type annotation vs 
> declaration annotation structure for both core reflection and 
> javax.lang.model in JDK 14 (under separate bugs).
>
> It is fair for the top-level interfaces to more fully discuss type vs 
> declaration annotations. Such top-level discussion is a complement to 
> introducing a statement of the type vs declaration distinction in the 
> method-as-implemented/overridden-in-this-paricular-type since the 
> latter provides better discoverability for developers.
>
> Thanks,
>
> -Joe
>
> On 6/10/2019 12:16 PM, Alex Buckley wrote:
>> 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!
>>
>>
> [snip]
>