JDK 9 RFR of JDK-8169479: java.lang.reflect.Constructor class has wrong api documentation

[joe darcy]

Hello,

Please review the changes to address

     JDK-8169479: java.lang.reflect.Constructor class has wrong api 
documentation
     http://cr.openjdk.java.net/~darcy/8169479.0/

Patch inline below. There are a few issues reported in the bug:

* The Constructor.toString method fails to state it prints out "throws" 
information. The implementation already does this and the analogous 
methods Constructor.toGenericString, Method.toString, etc. explicitly 
mention throws information already.

* The specification of Executable.getDeclaringClass can be overridden to 
be more precise in the Constructor and Method subclasses.

* In Constructor.toGenericString, "return type" is used where "class 
name" is meant.

Thanks,

-Joe

--- old/src/java.base/share/classes/java/lang/reflect/Constructor.java 
2016-11-23 07:33:00.095083685 -0800
+++ new/src/java.base/share/classes/java/lang/reflect/Constructor.java 
2016-11-23 07:32:59.927083679 -0800
@@ -200,7 +200,8 @@
      }

      /**
-     * {@inheritDoc}
+     * Returns the {@code Class} object representing the class that
+     * declares the constructor represented by this object.
       */
      @Override
      public Class<T> getDeclaringClass() {
@@ -321,6 +322,11 @@
       *    public java.util.Hashtable(int,float)
       * }</pre>
       *
+     * <p>If the constructor is declared to throw exceptions, the
+     * parameter list is followed by a space, followed by the word
+     * "{@code throws}" followed by a comma-separated list of the
+     * thrown exception types.
+     *
       * <p>The only possible modifiers for constructors are the access
       * modifiers {@code public}, {@code protected} or
       * {@code private}.  Only one of these may appear, or none if the
@@ -357,13 +363,13 @@
       * "<code><i>Type</i>...</code>".
       *
       * A space is used to separate access modifiers from one another
-     * and from the type parameters or return type.  If there are no
+     * and from the type parameters or class name.  If there are no
       * type parameters, the type parameter list is elided; if the type
       * parameter list is present, a space separates the list from the
       * class name.  If the constructor is declared to throw
       * exceptions, the parameter list is followed by a space, followed
       * by the word "{@code throws}" followed by a
-     * comma-separated list of the thrown exception types.
+     * comma-separated list of the generic thrown exception types.
       *
       * <p>The only possible modifiers for constructors are the access
       * modifiers {@code public}, {@code protected} or
--- old/src/java.base/share/classes/java/lang/reflect/Method.java 
2016-11-23 07:33:00.495083699 -0800
+++ new/src/java.base/share/classes/java/lang/reflect/Method.java 
2016-11-23 07:33:00.343083694 -0800
@@ -211,7 +211,8 @@
      }

      /**
-     * {@inheritDoc}
+     * Returns the {@code Class} object representing the class or interface
+     * that declares the method represented by this object.
       */
      @Override
      public Class<?> getDeclaringClass() {
@@ -372,7 +373,7 @@
       * the method name, followed by a parenthesized, comma-separated
       * list of the method's formal parameter types. If the method
       * throws checked exceptions, the parameter list is followed by a
-     * space, followed by the word throws followed by a
+     * space, followed by the word "{@code throws}" followed by a
       * comma-separated list of the thrown exception types.
       * For example:
       * <pre>
@@ -428,8 +429,8 @@
       * parameter list is present, a space separates the list from the
       * class name.  If the method is declared to throw exceptions, the
       * parameter list is followed by a space, followed by the word
-     * throws followed by a comma-separated list of the generic thrown
-     * exception types.
+     * "{@code throws}" followed by a comma-separated list of the generic
+     * thrown exception types.
       *
       * <p>The access modifiers are placed in canonical order as
       * specified by "The Java Language Specification".  This is