8237805: Use inline @jls @JVMS in core libs where appropriate

Reviewed-by: xiaofeya, dfuchs, prappo

src/java.base/share/classes/java/lang/Class.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -374,15 +374,16 @@ public static Class<?> forName(String className)
      *  {@code Class.forName("Foo", true, this.getClass().getClassLoader())}
      * </blockquote>
      *
-     * Note that this method throws errors related to loading, linking or
-     * initializing as specified in Sections 12.2, 12.3 and 12.4 of <em>The
-     * Java Language Specification</em>.
+     * 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>.
      * 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 12.4 of <em>The Java Language Specification</em>.
+     *                   See Section {@jls 12.4} of <em>The Java Language Specification</em>.
      * @param loader     class loader from which the class must be loaded
      * @return           class object representing the desired class
      *
@@ -660,7 +661,8 @@ public Void run() {
      * 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 5.1.1 and 5.1.4 , for details.
+     * Specification</em>, sections {@jls 5.1.1} and {@jls 5.1.4},
+     * for details.
      *
      * @param     cls the {@code Class} object to be checked
      * @return    the {@code boolean} value indicating whether objects of the
@@ -2399,7 +2401,7 @@ public Method[] getDeclaredMethods() throws SecurityException {
      * object represents an interface, a primitive type, an array class, or
      * void.
      *
-     * <p> See <em>The Java Language Specification</em>, section 8.2.
+     * <p> See <em>The Java Language Specification</em>, section {@jls 8.2}.
      *
      * @return  the array of {@code Constructor} objects representing all the
      *          declared constructors of this class

src/java.base/share/classes/java/lang/Enum.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -44,8 +44,8 @@
  *
  * More information about enums, including descriptions of the
  * implicitly declared methods synthesized by the compiler, can be
- * found in section 8.9 of
- * <cite>The Java&trade; Language Specification</cite>.
+ * found in section {@jls 8.9} of <cite>The Java&trade; Language
+ * Specification</cite>.
  *
  * Enumeration types are all serializable and receive special handling
  * by the serialization mechanism. The serialized representation used

src/java.base/share/classes/java/lang/invoke/MethodHandle.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -222,8 +222,9 @@
  * refers directly to an associated {@code CONSTANT_Methodref},
  * {@code CONSTANT_InterfaceMethodref}, or {@code CONSTANT_Fieldref}
  * constant pool entry.
- * (For full details on method handle constants,
- * see sections 4.4.8 and 5.4.3.5 of the Java Virtual Machine Specification.)
+ * (For full details on method handle constants, see sections {@jvms
+ * 4.4.8} and {@jvms 5.4.3.5} of the Java Virtual Machine
+ * Specification.)
  * <p>
  * Method handles produced by lookups or constant loads from methods or
  * constructors with the variable arity modifier bit ({@code 0x0080})

src/java.base/share/classes/java/lang/invoke/MethodHandleInfo.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -43,7 +43,8 @@
  * Direct method handles may be obtained in any of these ways:
  * <ul>
  * <li>By executing an {@code ldc} instruction on a {@code CONSTANT_MethodHandle} constant.
- *     (See the Java Virtual Machine Specification, sections 4.4.8 and 5.4.3.)
+ *     (See the Java Virtual Machine Specification, sections {@jvms
+ *     4.4.8} and {@jvms 5.4.3}.)
  * <li>By calling one of the <a href="MethodHandles.Lookup.html#lookups">Lookup Factory Methods</a>,
  *     such as {@link Lookup#findVirtual Lookup.findVirtual},
  *     to resolve a symbolic reference into a method handle.

src/java.base/share/classes/java/lang/invoke/MethodHandles.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -318,7 +318,8 @@ public static <T extends Member> T reflectAs(Class<T> expected, MethodHandle tar
      * use cases for methods, constructors, and fields.
      * Each method handle created by a factory method is the functional
      * equivalent of a particular <em>bytecode behavior</em>.
-     * (Bytecode behaviors are described in section 5.4.3.5 of the Java Virtual Machine Specification.)
+     * (Bytecode behaviors are described in section {@jvms 5.4.3.5} of
+     * the Java Virtual Machine Specification.)
      * Here is a summary of the correspondence between these factory methods and
      * the behavior of the resulting method handles:
      * <table class="striped">
@@ -502,7 +503,8 @@ public static <T extends Member> T reflectAs(Class<T> expected, MethodHandle tar
      * If the desired member is {@code protected}, the usual JVM rules apply,
      * including the requirement that the lookup class must either be in the
      * same package as the desired member, or must inherit that member.
-     * (See the Java Virtual Machine Specification, sections 4.9.2, 5.4.3.5, and 6.4.)
+     * (See the Java Virtual Machine Specification, sections {@jvms
+     * 4.9.2}, {@jvms 5.4.3.5}, and {@jvms 6.4}.)
      * In addition, if the desired member is a non-static field or method
      * in a different package, the resulting method handle may only be applied
      * to objects of the lookup class or one of its subclasses.
@@ -515,7 +517,7 @@ public static <T extends Member> T reflectAs(Class<T> expected, MethodHandle tar
      * that the receiver argument must match both the resolved method <em>and</em>
      * the current class.  Again, this requirement is enforced by narrowing the
      * type of the leading parameter to the resulting method handle.
-     * (See the Java Virtual Machine Specification, section 4.10.1.9.)
+     * (See the Java Virtual Machine Specification, section {@jmvs 4.10.1.9}.)
      * <p>
      * The JVM represents constructors and static initializer blocks as internal methods
      * with special names ({@code "<init>"} and {@code "<clinit>"}).
@@ -525,7 +527,8 @@ public static <T extends Member> T reflectAs(Class<T> expected, MethodHandle tar
      * <p>
      * If the relationship between nested types is expressed directly through the
      * {@code NestHost} and {@code NestMembers} attributes
-     * (see the Java Virtual Machine Specification, sections 4.7.28 and 4.7.29),
+     * (see the Java Virtual Machine Specification, sections {@jvms
+     * 4.7.28} and {@jvms 4.7.29}),
      * then the associated {@code Lookup} object provides direct access to
      * the lookup class and all of its nestmates
      * (see {@link java.lang.Class#getNestHost Class.getNestHost}).

src/java.base/share/classes/java/lang/invoke/MethodType.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -91,8 +91,9 @@
  * A method type may be loaded by an {@code ldc} instruction which refers
  * to a suitable {@code CONSTANT_MethodType} constant pool entry.
  * The entry refers to a {@code CONSTANT_Utf8} spelling for the descriptor string.
- * (For full details on method type constants,
- * see sections 4.4.8 and 5.4.3.5 of the Java Virtual Machine Specification.)
+ * (For full details on method type constants, see sections {@jvms
+ * 4.4.8} and {@jvms 5.4.3.5} of the Java Virtual Machine
+ * Specification.)
  * <p>
  * When the JVM materializes a {@code MethodType} from a descriptor string,
  * all classes named in the descriptor must be accessible, and will be loaded.

src/java.base/share/classes/java/lang/reflect/Method.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -503,7 +503,7 @@ void specificToGenericStringHeader(StringBuilder sb) {
      *
      * <p>If the underlying method is an instance method, it is invoked
      * using dynamic method lookup as documented in The Java Language
-     * Specification, section 15.12.4.4; in particular,
+     * Specification, section {@jls 15.12.4.4}; in particular,
      * overriding based on the runtime type of the target object may occur.
      *
      * <p>If the underlying method is static, the class that declared

src/java.base/share/classes/java/lang/reflect/ProxyGenerator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2020, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -383,7 +383,7 @@ private static List<Class<?>> computeUniqueCatchList(Class<?>[] exceptions) {
      * separator, the external representation used by the Java language
      * and APIs, to a fully qualified class name that uses '/' as the
      * package separator, the representation used in the class file
-     * format (see JVMS section 4.2).
+     * format (see JVMS section {@jvms 4.2}).
      */
     private static String dotToSlash(String name) {
         return name.replace('.', '/');