JDK 15 RFR of JDK-8241789: Make citations of JLS and JVMS consistent in java.lang.Class
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. *
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. *
participants (2)
-
Joe Darcy
-
Jonathan Gibbons