refactor: use Markdown reference links in Javadoc, ban {@link} via checkstyle (#32)

Converts all 57 {@link ...} / {@linkplain ...} inline tags in /// Markdown
Javadoc to Markdown reference links ([ClassName#method(ParamType)]), matching
the project's stated convention.

Adds a checkstyle RegexpSingleline that bans {@link}/{@linkplain} in /// lines
so the old style cannot creep back, mirroring the existing {@code} ban. Also
fixes a latent bug in both rules' messages: checkstyle renders them with
MessageFormat, which threw "can't parse argument number" on the literal
{@code}/{@link} braces whenever a violation actually fired — reworded to avoid
braces.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

checkstyle.xml

@@ -21,7 +21,15 @@
         <property name="format" value="^\s*///.*\{@code\s"/>
         <property name="minimum" value="0"/>
         <property name="maximum" value="0"/>
-        <property name="message" value="Use backtick syntax instead of {@code} in Markdown Javadoc (///). Example: `value` instead of {@code value}."/>
+        <property name="message" value="Use backtick syntax instead of the @code tag in Markdown Javadoc (///). Example: `value`."/>
+    </module>
+
+    <!-- Ban {@link}/{@linkplain} in /// Markdown Javadoc — use Markdown reference links instead. -->
+    <module name="RegexpSingleline">
+        <property name="format" value="^\s*///.*\{@link(plain)?\s"/>
+        <property name="minimum" value="0"/>
+        <property name="maximum" value="0"/>
+        <property name="message" value="Use Markdown reference links instead of the @link / @linkplain tag in Markdown Javadoc (///). Example: [ClassName#method(ParamType)]."/>
     </module>
 
     <!-- Ban HTML block/structure tags in /// Markdown Javadoc.

zstd/src/main/java/io/github/dfa1/zstd/Bindings.java

@@ -14,7 +14,7 @@
 /// [official manual](https://facebook.github.io/zstd/doc/api_manual_latest.html).
 ///
 /// `size_t` and `unsigned long long` are modelled as
-/// {@link java.lang.foreign.ValueLayout#JAVA_LONG} (LP64); the public API guards
+/// [java.lang.foreign.ValueLayout#JAVA_LONG] (LP64); the public API guards
 /// against negative interpretations where zstd uses sentinel values.
 ///
 /// For the full coverage map — every public zstd symbol, what is bound, and which

zstd/src/main/java/io/github/dfa1/zstd/NativeCall.java

@@ -6,7 +6,7 @@
 
 /// Package-private helpers that adapt raw FFM downcalls to the zstd error
 /// convention: run a native call, decode a zstd `size_t` error code into a
-/// {@link ZstdException}, and guard native-segment arguments. Shared by the
+/// [ZstdException], and guard native-segment arguments. Shared by the
 /// binding classes so the conventions live in one place.
 final class NativeCall {
 
@@ -17,7 +17,7 @@ interface ZstdCall {
     }
 
     /// Invokes a size-returning zstd call and converts a zstd error code into a
-    /// {@link ZstdException}.
+    /// [ZstdException].
     static long checkReturnValue(ZstdCall c) {
         long code;
         try {
@@ -38,7 +38,7 @@ interface NativeFactory {
     }
 
     /// Runs a zstd `create`-style call and rejects the `NULL` it returns on
-    /// allocation failure, raising a {@link ZstdException} that names the call.
+    /// allocation failure, raising a [ZstdException] that names the call.
     static MemorySegment createOrThrow(String what, NativeFactory factory) {
         MemorySegment p;
         try {
@@ -97,7 +97,7 @@ static void requireNative(MemorySegment seg, String name) {
     }
 
     /// Rethrows any `Throwable` as if unchecked, laundering the checked
-    /// `Throwable` that {@link java.lang.invoke.MethodHandle#invokeExact} declares.
+    /// `Throwable` that [java.lang.invoke.MethodHandle#invokeExact] declares.
     /// The shared sink for every binding class's native-call catch blocks.
     @SuppressWarnings("unchecked")
     static <E extends Throwable> RuntimeException rethrow(Throwable t) throws E {

zstd/src/main/java/io/github/dfa1/zstd/NativeLibrary.java

@@ -16,7 +16,7 @@
 import java.util.Locale;
 
 /// Infrastructure — loads the bundled `libzstd` shared library and binds
-/// native symbols to {@link MethodHandle}s via the Foreign Function & Memory API.
+/// native symbols to [MethodHandle]s via the Foreign Function & Memory API.
 ///
 /// The library is resolved only from the platform-specific native JAR on the
 /// classpath, extracted to a temp file, and loaded once at class-init time.

zstd/src/main/java/io/github/dfa1/zstd/NativeObject.java

@@ -5,8 +5,8 @@
 
 /// Base class for wrappers that own a native zstd pointer.
 ///
-/// The pointer lives in an {@link AtomicReference} that is swapped to
-/// {@link MemorySegment#NULL} on {@link #close()}, so {@link #tryClose} runs
+/// The pointer lives in an [AtomicReference] that is swapped to
+/// [MemorySegment#NULL] on [#close()], so [#tryClose] runs
 /// exactly once even under concurrent or repeated close calls.
 public abstract class NativeObject implements AutoCloseable {
 
@@ -46,6 +46,6 @@ public final void close() {
     /// Releases the native resource. Called exactly once with a non-NULL pointer.
     ///
     /// @param ptr the non-NULL native pointer to free
-    /// @throws Throwable if the native free call fails; the exception is swallowed by {@link #close()}
+    /// @throws Throwable if the native free call fails; the exception is swallowed by [#close()]
     protected abstract void tryClose(MemorySegment ptr) throws Throwable;
 }

zstd/src/main/java/io/github/dfa1/zstd/Zstd.java

@@ -10,8 +10,8 @@
 /// One-shot, stateless zstd compression and decompression over `byte[]`.
 ///
 /// Every method is thread-safe and allocates its own native scratch buffers.
-/// For repeated calls on a hot path, reuse a {@link ZstdCompressCtx} /
-/// {@link ZstdDecompressCtx} instead to avoid re-allocating per call.
+/// For repeated calls on a hot path, reuse a [ZstdCompressCtx] /
+/// [ZstdDecompressCtx] instead to avoid re-allocating per call.
 ///
 /// {@snippet :
 /// byte[] packed   = Zstd.compress("hello world".getBytes());
@@ -35,7 +35,7 @@ public static byte[] compress(byte[] src) {
     /// Compresses `src` at the given level.
     ///
     /// @param src   bytes to compress
-    /// @param level compression level in [{@link #minCompressionLevel()}, {@link #maxCompressionLevel()}];
+    /// @param level compression level in [[#minCompressionLevel()], [#maxCompressionLevel()]];
     ///              higher is smaller but slower
     /// @return a self-describing zstd frame
     public static byte[] compress(byte[] src, int level) {
@@ -56,7 +56,7 @@ public static byte[] compress(byte[] src, int level) {
     /// @param compressed a complete zstd frame
     /// @return the original bytes
     /// @throws ZstdException if the frame is invalid or its content size is not stored;
-    ///                       use {@link #decompress(byte[], int)} for the latter
+    ///                       use [#decompress(byte[], int)] for the latter
     public static byte[] decompress(byte[] compressed) {
         Objects.requireNonNull(compressed, "compressed");
         long size = requireStoredContentSize(frameContentSize(compressed));
@@ -82,8 +82,8 @@ public static byte[] decompress(byte[] compressed, int maxSize) {
     }
 
     /// Decompressed size recorded in a zstd frame's header, read directly from a
-    /// native {@link MemorySegment} with no copy — use it to size the destination
-    /// for the zero-copy {@link ZstdDecompressCtx#decompress(MemorySegment, MemorySegment)}.
+    /// native [MemorySegment] with no copy — use it to size the destination
+    /// for the zero-copy [ZstdDecompressCtx#decompress(MemorySegment, MemorySegment)].
     ///
     /// @param frame a complete zstd frame
     /// @return the decompressed length in bytes
@@ -196,7 +196,7 @@ public static int minCompressionLevel() {
         }
     }
 
-    /// The level used by {@link #compress(byte[])}.
+    /// The level used by [#compress(byte[])].
     ///
     /// @return the default compression level
     public static int defaultCompressionLevel() {

zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressCtx.java

@@ -6,8 +6,8 @@
 
 /// A reusable compression context.
 ///
-/// Reusing one context across many {@link #compress} calls amortises native
-/// state allocation, making it cheaper than the stateless {@link Zstd#compress}
+/// Reusing one context across many [#compress] calls amortises native
+/// state allocation, making it cheaper than the stateless [Zstd#compress]
 /// on hot paths. Not thread-safe: confine an instance to one thread or pool it.
 ///
 /// {@snippet :
@@ -31,7 +31,7 @@ private static MemorySegment create() {
         return NativeCall.createOrThrow("ZSTD_createCCtx", () -> (MemorySegment) Bindings.CREATE_CCTX.invokeExact());
     }
 
-    /// Sets the compression level for subsequent {@link #compress} calls.
+    /// Sets the compression level for subsequent [#compress] calls.
     ///
     /// @param level the compression level to use
     /// @return `this`, for chaining
@@ -42,7 +42,7 @@ public ZstdCompressCtx level(int level) {
     }
 
     /// Sets an advanced compression parameter for subsequent
-    /// {@link #compress(byte[])} / {@link #compress(MemorySegment, MemorySegment)}
+    /// [#compress(byte[])] / [#compress(MemorySegment, MemorySegment)]
     /// calls. The setting is sticky across calls until changed.
     ///
     /// Advanced parameters do not apply to the dictionary `compress` overloads.
@@ -233,8 +233,8 @@ private void setParam(ZstdCompressParameter parameter, int value) {
     /// Compresses `src` against `dict` at this context's level.
     ///
     /// The dictionary is re-digested on every call; for repeated compression
-    /// against the same dictionary, digest it once into a {@link ZstdCompressDict}
-    /// and use {@link #compress(byte[], ZstdCompressDict)}.
+    /// against the same dictionary, digest it once into a [ZstdCompressDict]
+    /// and use [#compress(byte[], ZstdCompressDict)].
     ///
     /// @param src  the bytes to compress
     /// @param dict the dictionary to compress against
@@ -255,7 +255,7 @@ public byte[] compress(byte[] src, ZstdDictionary dict) {
     }
 
     /// Compresses `src` against a pre-digested `dict` (the level was
-    /// fixed when the {@link ZstdCompressDict} was built).
+    /// fixed when the [ZstdCompressDict] was built).
     ///
     /// @param src  the bytes to compress
     /// @param dict the pre-digested compression dictionary
@@ -275,12 +275,12 @@ public byte[] compress(byte[] src, ZstdCompressDict dict) {
     }
 
     /// Zero-copy compression: reads `src` and writes the frame straight into
-    /// `dst`, both native {@link MemorySegment}s the caller owns. No heap
+    /// `dst`, both native [MemorySegment]s the caller owns. No heap
     /// `byte[]` bounce — hand zstd the segment addresses directly. This is
     /// the fast path when your bytes are already off-heap (e.g. an mmap slice and
     /// an arena-allocated output); see `docs/zero-copy.md`.
     ///
-    /// Size `dst` with {@link Zstd#compressBound(long)} to guarantee it fits.
+    /// Size `dst` with [Zstd#compressBound(long)] to guarantee it fits.
     ///
     /// @param dst the native destination buffer to write the frame into
     /// @param src the native source bytes to compress
@@ -308,7 +308,7 @@ public long compress(MemorySegment dst, MemorySegment src, ZstdCompressDict dict
     }
 
     /// Zero-copy compression that allocates the output for you: reserves a
-    /// worst-case buffer ({@link Zstd#compressBound(long)}) in `arena`,
+    /// worst-case buffer ([Zstd#compressBound(long)]) in `arena`,
     /// compresses into it, and returns a slice trimmed to the actual frame length.
     /// The returned segment is owned by `arena`.
     ///

zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressDict.java

@@ -7,9 +7,9 @@
 /// A dictionary digested once for compression at a fixed level.
 ///
 /// Building a `ZstdCompressDict` pre-processes the dictionary so that each
-/// {@link ZstdCompressCtx#compress(byte[], ZstdCompressDict)} call skips that
+/// [ZstdCompressCtx#compress(byte[], ZstdCompressDict)] call skips that
 /// cost — the right choice when compressing many payloads against the same
-/// dictionary. The raw {@link ZstdDictionary} bytes are copied into native
+/// dictionary. The raw [ZstdDictionary] bytes are copied into native
 /// memory, so the source may be discarded afterwards.
 ///
 /// Immutable once built and safe to share across threads (the digested dictionary is read-only).

zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressStream.java

@@ -8,7 +8,7 @@
 import static java.lang.foreign.ValueLayout.JAVA_LONG;
 
 /// A low-level, zero-copy streaming compressor driven with native
-/// {@link MemorySegment} buffers — no heap `byte[]` bounce.
+/// [MemorySegment] buffers — no heap `byte[]` bounce.
 ///
 /// Use this when both ends are already off-heap and you want full control over
 /// buffering; for ordinary `java.io` pipelines prefer [ZstdOutputStream].

zstd/src/main/java/io/github/dfa1/zstd/ZstdDecompressCtx.java

@@ -6,7 +6,7 @@
 
 /// A reusable decompression context.
 ///
-/// Reusing one context across many {@link #decompress} calls amortises native
+/// Reusing one context across many [#decompress] calls amortises native
 /// state allocation. Not thread-safe: confine an instance to one thread or pool it.
 public final class ZstdDecompressCtx extends NativeObject {
 
@@ -175,8 +175,8 @@ public byte[] decompress(byte[] compressed, int maxSize) {
     /// Decompresses a frame that was compressed against `dict`.
     ///
     /// The dictionary is re-digested on every call; for repeated use digest it
-    /// once into a {@link ZstdDecompressDict} and use
-    /// {@link #decompress(byte[], int, ZstdDecompressDict)}.
+    /// once into a [ZstdDecompressDict] and use
+    /// [#decompress(byte[], int, ZstdDecompressDict)].
     ///
     /// @param compressed a complete zstd frame
     /// @param maxSize    upper bound on the decompressed length
@@ -216,14 +216,14 @@ public byte[] decompress(byte[] compressed, int maxSize, ZstdDecompressDict dict
     }
 
     /// Zero-copy decompression: reads the frame from `src` and writes the
-    /// result straight into `dst`, both native {@link MemorySegment}s the
+    /// result straight into `dst`, both native [MemorySegment]s the
     /// caller owns. No heap `byte[]` bounce — the segment addresses go
     /// directly to zstd. This is the fast path when input is an mmap slice and
     /// output is an arena buffer that becomes the materialized array as-is;
     /// see `docs/zero-copy.md`.
     ///
     /// Size `dst` to the decompressed length (read it from the frame with
-    /// {@link Zstd#decompress(byte[])}'s header logic, or known out-of-band).
+    /// [Zstd#decompress(byte[])]'s header logic, or known out-of-band).
     ///
     /// @param dst the native destination buffer to write the result into
     /// @param src the native source frame to decompress
@@ -256,7 +256,7 @@ public long decompress(MemorySegment dst, MemorySegment src, ZstdDecompressDict
     /// segment is owned by `arena` and ready to use as a backing buffer.
     ///
     /// Requires the frame to store its decompressed size (frames produced by this
-    /// library do); for size-less frames use {@link #decompress(MemorySegment, MemorySegment)}
+    /// library do); for size-less frames use [#decompress(MemorySegment, MemorySegment)]
     /// with a destination you size yourself.
     ///
     /// @param arena the arena to allocate the output segment in