8220249: fix headings in java.compiler

Reviewed-by: erikj, darcy

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

@@ -52,7 +52,7 @@ import static java.lang.invoke.MethodHandles.Lookup.IMPL_LOOKUP;
  * {@linkplain java.lang.invoke.MethodHandles#dropArguments deletion},
  * and {@linkplain java.lang.invoke.MethodHandles#filterArguments substitution}.
  *
- * <h1>Method handle contents</h1>
+ * <h2>Method handle contents</h2>
  * Method handles are dynamically and strongly typed according to their parameter and return types.
  * They are not distinguished by the name or the defining class of their underlying methods.
  * A method handle must be invoked using a symbolic type descriptor which matches
@@ -89,7 +89,7 @@ import static java.lang.invoke.MethodHandles.Lookup.IMPL_LOOKUP;
  * from its specific class, as the method handle class hierarchy (if any)
  * may change from time to time or across implementations from different vendors.
  *
- * <h1>Method handle compilation</h1>
+ * <h2>Method handle compilation</h2>
  * A Java method call expression naming {@code invokeExact} or {@code invoke}
  * can invoke a method handle from Java source code.
  * From the viewpoint of source code, these methods can take any arguments
@@ -121,7 +121,7 @@ import static java.lang.invoke.MethodHandles.Lookup.IMPL_LOOKUP;
  * The ambiguity with the type {@code Void} is harmless, since there are no references of type
  * {@code Void} except the null reference.
  *
- * <h1>Method handle invocation</h1>
+ * <h2>Method handle invocation</h2>
  * The first time an {@code invokevirtual} instruction is executed
  * it is linked by symbolically resolving the names in the instruction
  * and verifying that the method call is statically legal.
@@ -164,7 +164,7 @@ import static java.lang.invoke.MethodHandles.Lookup.IMPL_LOOKUP;
  * (<em>Note:</em> The adjusted method handle {@code M2} is not directly observable,
  * and implementations are therefore not required to materialize it.)
  *
- * <h1>Invocation checking</h1>
+ * <h2>Invocation checking</h2>
  * In typical programs, method handle type matching will usually succeed.
  * But if a match fails, the JVM will throw a {@link WrongMethodTypeException},
  * either directly (in the case of {@code invokeExact}) or indirectly as if
@@ -205,7 +205,7 @@ import static java.lang.invoke.MethodHandles.Lookup.IMPL_LOOKUP;
  * They should not be passed to untrusted code unless their use from
  * the untrusted code would be harmless.
  *
- * <h1>Method handle creation</h1>
+ * <h2>Method handle creation</h2>
  * Java code can create a method handle that directly accesses
  * any method, constructor, or field that is accessible to that code.
  * This is done via a reflective, capability-based API called
@@ -263,7 +263,7 @@ import static java.lang.invoke.MethodHandles.Lookup.IMPL_LOOKUP;
  * of an {@code invokevirtual} or {@code invokeinterface} instruction on
  * a private method (as applicable).
  *
- * <h1>Usage examples</h1>
+ * <h2>Usage examples</h2>
  * Here are some examples of usage:
  * <blockquote><pre>{@code
 Object x, y; String s; int i;
@@ -309,7 +309,7 @@ mh.invokeExact(System.out, "Hello, world.");
  * be a method which calls {@link java.util.Objects#equals(Object,Object) Objects.equals}
  * on its arguments, and asserts that the result is true.
  *
- * <h1>Exceptions</h1>
+ * <h2>Exceptions</h2>
  * The methods {@code invokeExact} and {@code invoke} are declared
  * to throw {@link java.lang.Throwable Throwable},
  * which is to say that there is no static restriction on what a method handle
@@ -322,7 +322,7 @@ mh.invokeExact(System.out, "Hello, world.");
  * throwables locally, rethrowing only those which are legal in the context,
  * and wrapping ones which are illegal.
  *
- * <h1><a id="sigpoly"></a>Signature polymorphism</h1>
+ * <h2><a id="sigpoly"></a>Signature polymorphism</h2>
  * The unusual compilation and linkage behavior of
  * {@code invokeExact} and plain {@code invoke}
  * is referenced by the term <em>signature polymorphism</em>.
@@ -347,7 +347,7 @@ mh.invokeExact(System.out, "Hello, world.");
  * Tools which determine symbolic linkage are required to accept such
  * untransformed descriptors, without reporting linkage errors.
  *
- * <h1>Interoperation between method handles and the Core Reflection API</h1>
+ * <h2>Interoperation between method handles and the Core Reflection API</h2>
  * Using factory methods in the {@link java.lang.invoke.MethodHandles.Lookup Lookup} API,
  * any class member represented by a Core Reflection API object
  * can be converted to a behaviorally equivalent method handle.
@@ -389,7 +389,7 @@ mh.invokeExact(System.out, "Hello, world.");
  * to call {@code invokeExact} or plain {@code invoke},
  * for any specified type descriptor .
  *
- * <h1>Interoperation between method handles and Java generics</h1>
+ * <h2>Interoperation between method handles and Java generics</h2>
  * A method handle can be obtained on a method, constructor, or field
  * which is declared with Java generic types.
  * As with the Core Reflection API, the type of the method handle
@@ -416,7 +416,7 @@ mh.invokeExact(System.out, "Hello, world.");
  * genericity with a Java type parameter.</li>
  * </ul>
  *
- * <h1><a id="maxarity"></a>Arity limits</h1>
+ * <h2><a id="maxarity"></a>Arity limits</h2>
  * The JVM imposes on all methods and constructors of any kind an absolute
  * limit of 255 stacked arguments.  This limit can appear more restrictive
  * in certain cases:

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2019, 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
@@ -35,7 +35,7 @@ import static java.lang.invoke.MethodHandleStatics.*;
  * A symbolic reference obtained by cracking a direct method handle
  * into its consitutent symbolic parts.
  * To crack a direct method handle, call {@link Lookup#revealDirect Lookup.revealDirect}.
- * <h1><a id="directmh"></a>Direct Method Handles</h1>
+ * <h2><a id="directmh"></a>Direct Method Handles</h2>
  * A <em>direct method handle</em> represents a method, constructor, or field without
  * any intervening argument bindings or other transformations.
  * The method, constructor, or field referred to by a direct method handle is called
@@ -58,7 +58,7 @@ import static java.lang.invoke.MethodHandleStatics.*;
  *     to convert a {@link Field} into a method handle.
  * </ul>
  *
- * <h1>Restrictions on Cracking</h1>
+ * <h2>Restrictions on Cracking</h2>
  * Given a suitable {@code Lookup} object, it is possible to crack any direct method handle
  * to recover a symbolic reference for the underlying method, constructor, or field.
  * Cracking must be done via a {@code Lookup} object equivalent to that which created
@@ -77,7 +77,7 @@ import static java.lang.invoke.MethodHandleStatics.*;
  * handle with symbolic information (or caller binding) from an unexpected scope.
  * Use {@link java.lang.invoke.MethodHandles#reflectAs} to override this limitation.
  *
- * <h1><a id="refkinds"></a>Reference kinds</h1>
+ * <h2><a id="refkinds"></a>Reference kinds</h2>
  * The <a href="MethodHandles.Lookup.html#lookups">Lookup Factory Methods</a>
  * correspond to all major use cases for methods, constructors, and fields.
  * These use cases may be distinguished using small integers as follows:

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2019, 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
@@ -268,7 +268,7 @@ public class MethodHandles {
      * This includes all methods, constructors, and fields which are allowed to the lookup class,
      * even private ones.
      *
-     * <h1><a id="lookups"></a>Lookup Factory Methods</h1>
+     * <h2><a id="lookups"></a>Lookup Factory Methods</h2>
      * The factory methods on a {@code Lookup} object correspond to all major
      * use cases for methods, constructors, and fields.
      * Each method handle created by a factory method is the functional
@@ -395,7 +395,7 @@ public class MethodHandles {
      * <a href="MethodHandle.html#maxarity">too many parameters.</a>
      * </ul>
      *
-     * <h1><a id="access"></a>Access checking</h1>
+     * <h2><a id="access"></a>Access checking</h2>
      * Access checks are applied in the factory methods of {@code Lookup},
      * when a method handle is created.
      * This is a key difference from the Core Reflection API, since
@@ -529,7 +529,7 @@ public class MethodHandles {
      * whose <a href="MethodHandles.Lookup.html#equiv">bytecode behaviors</a> and Java language access permissions
      * can be reliably determined and emulated by method handles.
      *
-     * <h1><a id="secmgr"></a>Security manager interactions</h1>
+     * <h2><a id="secmgr"></a>Security manager interactions</h2>
      * Although bytecode instructions can only refer to classes in
      * a related class loader, this API can search for methods in any
      * class, as long as a reference to its {@code Class} object is
@@ -588,7 +588,7 @@ public class MethodHandles {
      * or else that is being accessed from a lookup class that has
      * rights to access the member or class.
      *
-     * <h1><a id="callsens"></a>Caller sensitive methods</h1>
+     * <h2><a id="callsens"></a>Caller sensitive methods</h2>
      * A small number of Java methods have a special property called caller sensitivity.
      * A <em>caller-sensitive</em> method can behave differently depending on the
      * identity of its immediate caller.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2019, 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
@@ -197,7 +197,7 @@ public class MutableCallSite extends CallSite {
      * processed before the method returns abnormally.
      * Which elements these are (if any) is implementation-dependent.
      *
-     * <h1>Java Memory Model details</h1>
+     * <h4>Java Memory Model details</h4>
      * In terms of the Java Memory Model, this operation performs a synchronization
      * action which is comparable in effect to the writing of a volatile variable
      * by the current thread, and an eventual volatile read by every other thread

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

@@ -234,7 +234,7 @@ import static java.lang.invoke.MethodHandleStatics.UNSAFE;
  * precise phrasing of the specification of access mode methods and memory fence
  * methods may accompany future updates of the Java Language Specification.
  *
- * <h1>Compiling invocation of access mode methods</h1>
+ * <h2>Compiling invocation of access mode methods</h2>
  * A Java method call expression naming an access mode method can invoke a
  * VarHandle from Java source code.  From the viewpoint of source code, these
  * methods can take any arguments and their polymorphic result (if expressed)
@@ -266,7 +266,7 @@ import static java.lang.invoke.MethodHandleStatics.UNSAFE;
  * except the null reference.
  *
  *
- * <h1><a id="invoke">Performing invocation of access mode methods</a></h1>
+ * <h2><a id="invoke">Performing invocation of access mode methods</a></h2>
  * The first time an {@code invokevirtual} instruction is executed it is linked
  * by symbolically resolving the names in the instruction and verifying that
  * the method call is statically legal.  This also holds for calls to access mode
@@ -329,7 +329,7 @@ import static java.lang.invoke.MethodHandleStatics.UNSAFE;
  * Where, in this case, the method handle is bound to the VarHandle instance.
  *
  *
- * <h1>Invocation checking</h1>
+ * <h2>Invocation checking</h2>
  * In typical programs, VarHandle access mode type matching will usually
  * succeed.  But if a match fails, the JVM will throw a
  * {@link WrongMethodTypeException}.
@@ -364,7 +364,7 @@ import static java.lang.invoke.MethodHandleStatics.UNSAFE;
  * untrusted code unless their use from the untrusted code would be harmless.
  *
  *
- * <h1>VarHandle creation</h1>
+ * <h2>VarHandle creation</h2>
  * Java code can create a VarHandle that directly accesses any field that is
  * accessible to that code.  This is done via a reflective, capability-based
  * API called {@link java.lang.invoke.MethodHandles.Lookup
@@ -383,7 +383,7 @@ import static java.lang.invoke.MethodHandleStatics.UNSAFE;
  * class outside the current package, the receiver argument will be narrowed to
  * the type of the accessing class.
  *
- * <h1>Interoperation between VarHandles and the Core Reflection API</h1>
+ * <h2>Interoperation between VarHandles and the Core Reflection API</h2>
  * Using factory methods in the {@link java.lang.invoke.MethodHandles.Lookup
  * Lookup} API, any field represented by a Core Reflection API object
  * can be converted to a behaviorally equivalent VarHandle.
@@ -428,7 +428,7 @@ import static java.lang.invoke.MethodHandleStatics.UNSAFE;
  * any specified access mode type and is equivalent in behaviour to
  * {@link java.lang.invoke.MethodHandles#varHandleInvoker}.
  *
- * <h1>Interoperation between VarHandles and Java generics</h1>
+ * <h2>Interoperation between VarHandles and Java generics</h2>
  * A VarHandle can be obtained for a variable, such as a field, which is
  * declared with Java generic types.  As with the Core Reflection API, the
  * VarHandle's variable type will be constructed from the erasure of the

src/java.base/share/classes/java/lang/invoke/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2019, 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
@@ -53,12 +53,12 @@
  * </li>
  * </ul>
  *
- * <h1><a id="jvm_mods"></a>Dynamic resolution of call sites and constants</h1>
+ * <h2><a id="jvm_mods"></a>Dynamic resolution of call sites and constants</h2>
  * The following low-level information summarizes relevant parts of the
  * Java Virtual Machine specification.  For full details, please see the
  * current version of that specification.
  *
- * <h2><a id="indyinsn"></a>Dynamically-computed call sites</h2>
+ * <h3><a id="indyinsn"></a>Dynamically-computed call sites</h3>
  * An {@code invokedynamic} instruction is originally in an unlinked state.
  * In this state, there is no target method for the instruction to invoke.
  * <p>
@@ -74,7 +74,7 @@
  * The constant pool reference also specifies the invocation's name and method type descriptor,
  * just like {@code invokestatic} and the other invoke instructions.
  *
- * <h2><a id="condycon"></a>Dynamically-computed constants</h2>
+ * <h3><a id="condycon"></a>Dynamically-computed constants</h3>
  * The constant pool may contain constants tagged {@code CONSTANT_Dynamic},
  * equipped with bootstrap methods which perform their resolution.
  * Such a <em>dynamic constant</em> is originally in an unresolved state.
@@ -90,7 +90,7 @@
  * (Roughly speaking, a dynamically-computed constant is to a dynamically-computed call site
  * as a {@code CONSTANT_Fieldref} is to a {@code CONSTANT_Methodref}.)
  *
- * <h2><a id="bsm"></a>Execution of bootstrap methods</h2>
+ * <h3><a id="bsm"></a>Execution of bootstrap methods</h3>
  * Resolving a dynamically-computed call site or constant
  * starts with resolving constants from the constant pool for the
  * following items:
@@ -136,7 +136,7 @@
  * subsequent attempts to execute the {@code invokedynamic} instruction or load the
  * dynamically-computed constant.
  *
- * <h2>Timing of resolution</h2>
+ * <h3>Timing of resolution</h3>
  * An {@code invokedynamic} instruction is linked just before its first execution.
  * A dynamically-computed constant is resolved just before the first time it is used
  * (by pushing it on the stack or linking it as a bootstrap method parameter).
@@ -171,7 +171,7 @@
  * just before its first invocation.
  * There is no way to undo the effect of a completed bootstrap method call.
  *
- * <h2>Types of bootstrap methods</h2>
+ * <h3>Types of bootstrap methods</h3>
  * For a dynamically-computed call site, the bootstrap method is invoked with parameter
  * types {@code MethodHandles.Lookup}, {@code String}, {@code MethodType}, and the types
  * of any static arguments; the return type is {@code CallSite}.