Uploaded image for project: 'CCC Migration Project'
  1. CCC Migration Project
  2. CCC-8169479

java.lang.reflect.Constructor class has wrong api documentation

    Details

    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Document existing behavior and make the specification more precise.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      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

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                darcy Joe Darcy
                Reporter:
                darcy Joe Darcy
                Reviewed By:
                Brian Burkhalter, Paul Sandoz (Inactive)
              • Votes:
                0 Vote for this issue
                Watchers:
                0 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: