Summary

Correct a number of misstatements in the core reflection documentation to align with the implementation.

Problem

Some small errors in core reflection documentation.

Solution

Fix the errors: 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.

Specification

--- 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