JDK 15 RFR of JDK-8241789: Make citations of JLS and JVMS consistent in java.lang.Class
Jonathan Gibbons
jonathan.gibbons at oracle.com
Sat Mar 28 14:59:57 UTC 2020
double "the"
899 * the format specified in section {@jvms 4.7.9} of the
900 * <cite>The Java™ Virtual Machine Specification</cite>,
Otherwise OK,
-- Jon
On 3/27/20 9:53 PM, Joe Darcy wrote:
> Hello,
>
> As noticed during the CSR review of JDK-8238359, not all the citations
> of JVMS and JLS are done consistently in java.lang.Class. These
> citations should be done uniformly.
>
> http://cr.openjdk.java.net/~darcy/8241789.0/
>
> Patch below.
>
> The referenced JVMS "table 4.1" had been renumbered so I replaced it
> with a reference to section 4.1.
>
> I did not reflow the paragraphs to make this review easier; I'll do a
> reflow where appropriate before pushing.
>
> Thanks,
>
> -Joe
>
> --- old/src/java.base/share/classes/java/lang/Class.java 2020-03-27
> 21:37:41.703808000 -0700
> +++ new/src/java.base/share/classes/java/lang/Class.java 2020-03-27
> 21:37:41.415664000 -0700
> @@ -139,7 +139,7 @@
> * </pre></blockquote>
> *
> * <p> It is also possible to get the {@code Class} object for a named
> - * type (or for void) using a class literal. See Section 15.8.2 of
> + * type (or for void) using a class literal. See Section {@jls
> 15.8.2} of
> * <cite>The Java™ Language Specification</cite>.
> * For example:
> *
> @@ -376,14 +376,14 @@
> *
> * Note that this method throws errors related to loading, linking
> * or initializing as specified in Sections {@jls 12.2}, {@jls
> - * 12.3}, and {@jls 12.4} of <em>The Java Language
> - * Specification</em>.
> + * 12.3}, and {@jls 12.4} of <cite>The Java™ Language
> + * Specification</cite>.
> * Note that this method does not check whether the requested class
> * is accessible to its caller.
> *
> * @param name fully qualified name of the desired class
> * @param initialize if {@code true} the class will be
> initialized (which implies linking).
> - * See Section {@jls 12.4} of <em>The Java
> Language Specification</em>.
> + * See Section {@jls 12.4} of <cite>The
> Java™ Language Specification</cite>.
> * @param loader class loader from which the class must be
> loaded
> * @return class object representing the desired class
> *
> @@ -660,8 +660,8 @@
> * <p> Specifically, this method tests whether the type
> represented by the
> * specified {@code Class} parameter can be converted to the type
> * represented by this {@code Class} object via an identity
> conversion
> - * or via a widening reference conversion. See <em>The Java Language
> - * Specification</em>, sections {@jls 5.1.1} and {@jls 5.1.4},
> + * or via a widening reference conversion. See <cite>The
> Java™ Language
> + * Specification</cite>, sections {@jls 5.1.1} and {@jls 5.1.4},
> * for details.
> *
> * @param cls the {@code Class} object to be checked
> @@ -745,7 +745,7 @@
> * Returns {@code true} if this class is a synthetic class;
> * returns {@code false} otherwise.
> * @return {@code true} if and only if this class is a synthetic
> class as
> - * defined by the Java Language Specification.
> + * defined by <cite>The Java™ Language
> Specification</cite>.
> * @jls 13.1 The Form of a Binary
> * @since 1.5
> */
> @@ -896,8 +896,8 @@
> * the type variables declared by this generic declaration
> * @throws java.lang.reflect.GenericSignatureFormatError if the
> generic
> * signature of this generic declaration does not conform to
> - * the format specified in
> - * <cite>The Java™ Virtual Machine Specification</cite>
> + * the format specified in section {@jvms 4.7.9} of the
> + * <cite>The Java™ Virtual Machine Specification</cite>,
> * @since 1.5
> */
> @SuppressWarnings("unchecked")
> @@ -945,6 +945,7 @@
> *
> * @throws java.lang.reflect.GenericSignatureFormatError if the
> generic
> * class signature does not conform to the format specified in
> + * section {@jvms 4.7.9} of the
> * <cite>The Java™ Virtual Machine Specification</cite>
> * @throws TypeNotPresentException if the generic superclass
> * refers to a non-existent type declaration
> @@ -1143,7 +1144,7 @@
> *
> * @throws java.lang.reflect.GenericSignatureFormatError
> * if the generic class signature does not conform to the format
> - * specified in
> + * specified in section {@jvms 4.7.9} of the
> * <cite>The Java™ Virtual Machine Specification</cite>
> * @throws TypeNotPresentException if any of the generic
> * superinterfaces refers to a non-existent type declaration
> @@ -1201,8 +1202,8 @@
> * {@code false}. The values of its other modifiers are not
> determined
> * by this specification.
> *
> - * <p> The modifier encodings are defined in <em>The Java Virtual
> Machine
> - * Specification</em>, table 4.1.
> + * <p> The modifier encodings are defined in section {@jvms 4.1}
> of the
> + * <cite>The Java™ Virtual Machine Specification</cite>.
> *
> * @return the {@code int} representing the modifiers for this class
> * @see java.lang.reflect.Modifier
> @@ -1611,7 +1612,7 @@
>
> /**
> * Returns the canonical name of the underlying class as
> - * defined by the Java Language Specification. Returns null if
> + * defined by <cite>The Java™ Language
> Specification</cite>, section {@jls 6.7}. Returns null if
> * the underlying class does not have a canonical name (i.e., if
> * it is a local or anonymous class or an array whose component
> * type does not have a canonical name).
> @@ -1928,7 +1929,8 @@
> * class has no public constructors, or if the class is an array
> class, or
> * if the class reflects a primitive type or void.
> *
> - * Note that while this method returns an array of {@code
> + * @apiNote
> + * While this method returns an array of {@code
> * Constructor<T>} objects (that is an array of constructors from
> * this class), the return type of this method is {@code
> * Constructor<?>[]} and <em>not</em> {@code Constructor<T>[]} as
> @@ -2401,7 +2403,7 @@
> * object represents an interface, a primitive type, an array
> class, or
> * void.
> *
> - * <p> See <em>The Java Language Specification</em>, section
> {@jls 8.2}.
> + * <p> See <cite>The Java™ Language Specification</cite>,
> section {@jls 8.2}.
> *
> * @return the array of {@code Constructor} objects representing
> all the
> * declared constructors of this class
> @@ -3538,9 +3540,10 @@
> * otherwise, if this class is not a system class (i.e., it has a
> * class loader) its class loader's default assertion status is
> returned;
> * otherwise, the system class default assertion status is returned.
> - * <p>
> + *
> + * @apiNote
> * Few programmers will have any need for this method; it is
> provided
> - * for the benefit of the JRE itself. (It allows a class to
> determine at
> + * for the benefit of the JDK itself. (It allows a class to
> determine at
> * the time that it is initialized whether assertions should be
> enabled.)
> * Note that this method is not guaranteed to return the actual
> * assertion status that was (or will be) associated with the
> specified
> @@ -4025,10 +4028,10 @@
> *
> * @apiNote A {@code class} file of version 55.0 or greater may
> record the
> * host of the nest to which it belongs by using the {@code
> NestHost}
> - * attribute (JVMS 4.7.28). Alternatively, a {@code class} file of
> + * attribute (JVMS {@jvms 4.7.28}). Alternatively, a {@code
> class} file of
> * version 55.0 or greater may act as a nest host by enumerating
> the nest's
> * other members with the
> - * {@code NestMembers} attribute (JVMS 4.7.29).
> + * {@code NestMembers} attribute (JVMS {@jvms 4.7.29}).
> * A {@code class} file of version 54.0 or lower does not use these
> * attributes.
> *
>
More information about the core-libs-dev
mailing list