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