From 732f1065fe05ae737a716bea92536cb8edc2b6a0 Mon Sep 17 00:00:00 2001
From: Jorn Vernee <jvernee@openjdk.org>
Date: Fri, 8 Jul 2022 11:18:32 +0000
Subject: [PATCH] 8289223: Canonicalize header ids in foreign API javadocs

Reviewed-by: mcimadamore
---
 .../share/classes/java/lang/foreign/Linker.java   |  6 +++---
 .../classes/java/lang/foreign/MemoryAddress.java  |  2 +-
 .../classes/java/lang/foreign/MemoryLayout.java   |  4 ++--
 .../classes/java/lang/foreign/MemorySegment.java  |  8 ++++----
 .../classes/java/lang/foreign/MemorySession.java  |  6 +++---
 .../classes/java/lang/foreign/SymbolLookup.java   |  2 +-
 .../classes/java/lang/foreign/package-info.java   | 15 +++++++--------
 7 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/src/java.base/share/classes/java/lang/foreign/Linker.java b/src/java.base/share/classes/java/lang/foreign/Linker.java
index 7d5f48ee839..53196ab2bd0 100644
--- a/src/java.base/share/classes/java/lang/foreign/Linker.java
+++ b/src/java.base/share/classes/java/lang/foreign/Linker.java
@@ -60,7 +60,7 @@
  * is currently executing. This linker also provides access, via its {@linkplain #defaultLookup() default lookup},
  * to the native libraries loaded with the Java runtime.
  *
- * <h2><a id = "downcall-method-handles">Downcall method handles</a></h2>
+ * <h2 id="downcall-method-handles">Downcall method handles</h2>
  *
  * {@linkplain #downcallHandle(FunctionDescriptor) Linking a foreign function} is a process which requires a function descriptor,
  * a set of memory layouts which, together, specify the signature of the foreign function to be linked, and returns,
@@ -91,7 +91,7 @@
  * memory region associated with the struct returned by the downcall method handle.</li>
  * </ul>
  *
- * <h2><a id = "upcall-stubs">Upcall stubs</a></h2>
+ * <h2 id="upcall-stubs">Upcall stubs</h2>
  *
  * {@linkplain #upcallStub(MethodHandle, FunctionDescriptor, MemorySession) Creating an upcall stub} requires a method
  * handle and a function descriptor; in this case, the set of memory layouts in the function descriptor
@@ -114,7 +114,7 @@
  * downcall method handles (as {@link MemorySegment} implements the {@link Addressable} interface) and,
  * when no longer required, they can be {@linkplain MemorySession#close() released}, via their associated {@linkplain MemorySession session}.
  *
- * <h2>Safety considerations</h2>
+ * <h2 id="safety">Safety considerations</h2>
  *
  * Creating a downcall method handle is intrinsically unsafe. A symbol in a foreign library does not, in general,
  * contain enough signature information (e.g. arity and types of foreign function parameters). As a consequence,
diff --git a/src/java.base/share/classes/java/lang/foreign/MemoryAddress.java b/src/java.base/share/classes/java/lang/foreign/MemoryAddress.java
index e60ebb3628e..8b12bef671e 100644
--- a/src/java.base/share/classes/java/lang/foreign/MemoryAddress.java
+++ b/src/java.base/share/classes/java/lang/foreign/MemoryAddress.java
@@ -44,7 +44,7 @@
  * </ul>
  * A memory address is backed by a raw machine pointer, expressed as a {@linkplain #toRawLongValue() long value}.
  *
- * <h2>Dereferencing memory addresses</h2>
+ * <h2 id="dereferencing">Dereferencing memory addresses</h2>
  *
  * A memory address can be read or written using various methods provided in this class (e.g. {@link #get(ValueLayout.OfInt, long)}).
  * Each dereference method takes a {@linkplain ValueLayout value layout}, which specifies the size,
diff --git a/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java b/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java
index b30a14e60a6..fe953d2aa3c 100644
--- a/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java
+++ b/src/java.base/share/classes/java/lang/foreign/MemoryLayout.java
@@ -77,7 +77,7 @@
  * ).withName("TaggedValues");
  * }
  *
- * <h2><a id = "layout-align">Size, alignment and byte order</a></h2>
+ * <h2 id="layout-align">Size, alignment and byte order</h2>
  *
  * All layouts have a size; layout size for value and padding layouts is always explicitly denoted; this means that a layout description
  * always has the same size in bits, regardless of the platform in which it is used. For derived layouts, the size is computed
@@ -105,7 +105,7 @@
  * <p>
  * All value layouts have an <em>explicit</em> byte order (see {@link java.nio.ByteOrder}) which is set when the layout is created.
  *
- * <h2><a id = "layout-paths">Layout paths</a></h2>
+ * <h2 id="layout-paths">Layout paths</h2>
  *
  * A <em>layout path</em> originates from a <em>root</em> layout (typically a group or a sequence layout) and terminates
  * at a layout nested within the root layout - this is the layout <em>selected</em> by the layout path.
diff --git a/src/java.base/share/classes/java/lang/foreign/MemorySegment.java b/src/java.base/share/classes/java/lang/foreign/MemorySegment.java
index 3b29756fb23..17ca1ad1f8d 100644
--- a/src/java.base/share/classes/java/lang/foreign/MemorySegment.java
+++ b/src/java.base/share/classes/java/lang/foreign/MemorySegment.java
@@ -69,7 +69,7 @@
  * {@link ByteBuffer#allocateDirect(int)} method will be backed by off-heap memory.</li>
  * </ul>
  *
- * <h2>Lifecycle and confinement</h2>
+ * <h2 id="lifecyle-confinement">Lifecycle and confinement</h2>
  *
  * Memory segments are associated with a {@linkplain MemorySegment#session() memory session}. As for all resources associated
  * with a memory session, a segment cannot be accessed after its underlying session has been closed. For instance,
@@ -91,7 +91,7 @@
  * from byte buffer instances obtained calling the {@link #asByteBuffer()} method on a memory segment {@code S}
  * are associated with the same memory session as {@code S}.
  *
- * <h2><a id = "segment-deref">Dereferencing memory segments</a></h2>
+ * <h2 id="segment-deref">Dereferencing memory segments</h2>
  *
  * A memory segment can be read or written using various methods provided in this class (e.g. {@link #get(ValueLayout.OfInt, long)}).
  * Each dereference method takes a {@linkplain ValueLayout value layout}, which specifies the size,
@@ -136,7 +136,7 @@
  * intHandle.get(segment, 3L); // get int element at offset 3 * 4 = 12
  * }
  *
- * <h2>Slicing memory segments</h2>
+ * <h2 id="slicing">Slicing memory segments</h2>
  *
  * Memory segments support <em>slicing</em>. A memory segment can be used to {@linkplain MemorySegment#asSlice(long, long) obtain}
  * other segments backed by the same underlying memory region, but with <em>stricter</em> spatial bounds than the ones
@@ -220,7 +220,7 @@
  * constructed from a {@code byte[]} might have a subset of addresses {@code S} which happen to be 8-byte aligned. But determining
  * which segment addresses belong to {@code S} requires reasoning about details which are ultimately implementation-dependent.
  *
- * <h2>Restricted memory segments</h2>
+ * <h2 id="restricted-segments">Restricted memory segments</h2>
  * Sometimes it is necessary to turn a memory address obtained from native code into a memory segment with
  * full spatial, temporal and confinement bounds. To do this, clients can {@linkplain #ofAddress(MemoryAddress, long, MemorySession) obtain}
  * a native segment <em>unsafely</em> from a give memory address, by providing the segment size, as well as the segment {@linkplain MemorySession session}.
diff --git a/src/java.base/share/classes/java/lang/foreign/MemorySession.java b/src/java.base/share/classes/java/lang/foreign/MemorySession.java
index d78ad13f646..c7f21293dfd 100644
--- a/src/java.base/share/classes/java/lang/foreign/MemorySession.java
+++ b/src/java.base/share/classes/java/lang/foreign/MemorySession.java
@@ -51,7 +51,7 @@
  * As a result, resources associated with the global session are never released. Examples of resources associated with
  * the global memory session are {@linkplain MemorySegment#ofArray(int[]) heap segments}.
  *
- * <h2><a id = "thread-confinement">Thread confinement</a></h2>
+ * <h2 id = "thread-confinement">Thread confinement</h2>
  *
  * Memory sessions can be divided into two categories: <em>thread-confined</em> memory sessions, and <em>shared</em>
  * memory sessions.
@@ -66,7 +66,7 @@
  * can be accessed by multiple threads. This might be useful when multiple threads need to access the same resource concurrently
  * (e.g. in the case of parallel processing).
  *
- * <h2>Closeable memory sessions</h2>
+ * <h2 id="closeable">Closeable memory sessions</h2>
  *
  * When a session is associated with off-heap resources, it is often desirable for said resources to be released in a timely fashion,
  * rather than waiting for the session to be deemed <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>
@@ -96,7 +96,7 @@
  * the session becomes unreachable; that is, {@linkplain #addCloseAction(Runnable) close actions} associated with a
  * memory session, whether managed or not, are called <em>exactly once</em>.
  *
- * <h2>Non-closeable views</h2>
+ * <h2 id="non-closeable">Non-closeable views</h2>
  *
  * There are situations in which it might not be desirable for a memory session to be reachable from one or
  * more resources associated with it. For instance, an API might create a private memory session, and allocate
diff --git a/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java b/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java
index aeea22bc132..c6fb83b61a9 100644
--- a/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java
+++ b/src/java.base/share/classes/java/lang/foreign/SymbolLookup.java
@@ -57,7 +57,7 @@
  *     {@link MemorySegment#ofAddress(MemoryAddress, long, MemorySession) resizing} the segment first).</li>
  * </ul>
  *
- * <h2>Obtaining a symbol lookup</h2>
+ * <h2 id="obtaining">Obtaining a symbol lookup</h2>
  *
  * The factory methods {@link #libraryLookup(String, MemorySession)} and {@link #libraryLookup(Path, MemorySession)}
  * create a symbol lookup for a library known to the operating system. The library is specified by either its name or a path.
diff --git a/src/java.base/share/classes/java/lang/foreign/package-info.java b/src/java.base/share/classes/java/lang/foreign/package-info.java
index a0b12c41c5d..87cfc200735 100644
--- a/src/java.base/share/classes/java/lang/foreign/package-info.java
+++ b/src/java.base/share/classes/java/lang/foreign/package-info.java
@@ -27,7 +27,7 @@
 /**
  * <p>Provides low-level access to memory and functions outside the Java runtime.
  *
- * <h2>Foreign memory access</h2>
+ * <h2 id="fma">Foreign memory access</h2>
  *
  * <p>
  * The main abstraction introduced to support foreign memory access is {@link java.lang.foreign.MemorySegment}, which
@@ -58,7 +58,7 @@
  * where the size of each slot is exactly 4 bytes, the initialization logic above will set each slot
  * so that {@code s[i] = i}, again where {@code 0 <= i < 10}.
  *
- * <h3><a id="deallocation"></a>Deterministic deallocation</h3>
+ * <h3 id="deallocation">Deterministic deallocation</h3>
  *
  * When writing code that manipulates memory segments, especially if backed by memory which resides outside the Java heap, it is
  * often crucial that the resources associated with a memory segment are released when the segment is no longer in use,
@@ -81,7 +81,7 @@
  * <em>try-with-resources</em> construct: this idiom ensures that all the memory resources associated with the segment will be released
  * at the end of the block, according to the semantics described in Section {@jls 14.20.3} of <cite>The Java Language Specification</cite>.
  *
- * <h3><a id="safety"></a>Safety</h3>
+ * <h3 id="safety">Safety</h3>
  *
  * This API provides strong safety guarantees when it comes to memory access. First, when dereferencing a memory segment,
  * the access coordinates are validated (upon access), to make sure that access does not occur at any address which resides
@@ -94,7 +94,7 @@
  * We call this guarantee <em>temporal safety</em>. Together, spatial and temporal safety ensure that each memory access
  * operation either succeeds - and accesses a valid memory location - or fails.
  *
- * <h2>Foreign function access</h2>
+ * <h2 id="ffa">Foreign function access</h2>
  * The key abstractions introduced to support foreign function access are {@link java.lang.foreign.SymbolLookup},
  * {@link java.lang.foreign.FunctionDescriptor} and {@link java.lang.foreign.Linker}. The first is used to look up symbols
  * inside libraries; the second is used to model the signature of foreign functions, while the third provides
@@ -134,7 +134,7 @@
  * {@linkplain java.lang.foreign.MemorySegment#setUtf8String(long, java.lang.String) into} zero-terminated, UTF-8 strings and
  * {@linkplain java.lang.foreign.MemorySegment#getUtf8String(long) back}, as demonstrated in the above example.
  *
- * <h3>Foreign addresses</h3>
+ * <h3 id="addresses">Foreign addresses</h3>
  *
  * When a memory segment is created from Java code, the segment properties (spatial bounds, temporal bounds and confinement)
  * are fully known at segment creation. But when interacting with foreign functions, clients will often receive <em>raw</em> pointers.
@@ -165,7 +165,7 @@
  * int x = segment.get(ValueLayout.JAVA_INT, 0);
  * }
  *
- * <h3>Upcalls</h3>
+ * <h3 id="upcalls">Upcalls</h3>
  * The {@link java.lang.foreign.Linker} interface also allows clients to turn an existing method handle (which might point
  * to a Java method) into a memory address, so that Java code can effectively be passed to other foreign functions.
  * For instance, we can write a method that compares two integer values, as follows:
@@ -213,8 +213,7 @@
  * provided when the upcall stub is created. This same session is made available by the {@link java.lang.foreign.MemorySegment}
  * instance returned by that method.
  *
- * <a id="restricted"></a>
- * <h2>Restricted methods</h2>
+ * <h2 id="restricted">Restricted methods</h2>
  * Some methods in this package are considered <em>restricted</em>. Restricted methods are typically used to bind native
  * foreign data and/or functions to first-class Java API elements which can then be used directly by clients. For instance
  * the restricted method {@link java.lang.foreign.MemorySegment#ofAddress(MemoryAddress, long, MemorySession)}