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