build: enforce zero warnings (javac -Xlint:all, javadoc failOnWarnings)

- compiler: -Xlint:all + failOnWarning, so any javac lint fails the build
- javadoc: failOnError + failOnWarnings, bound to the verify phase
- fixes surfaced by the policy:
  - ZstdException gets a serialVersionUID
  - @SuppressWarnings("restricted") on the FFM call sites (libraryLookup,
    downcallHandle, reinterpret) — intrinsic to FFM, acknowledged explicitly
  - complete @param/@return/@throws on all public + protected members

verify green, 40 tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

pom.xml

@@ -102,6 +102,21 @@
 					<version>3.15.0</version>
 					<configuration>
 						<release>25</release>
+						<failOnWarning>true</failOnWarning>
+						<compilerArgs>
+							<arg>-Xlint:all</arg>
+						</compilerArgs>
+					</configuration>
+				</plugin>
+				<plugin>
+					<groupId>org.apache.maven.plugins</groupId>
+					<artifactId>maven-javadoc-plugin</artifactId>
+					<version>3.12.0</version>
+					<configuration>
+						<release>25</release>
+						<failOnError>true</failOnError>
+						<failOnWarnings>true</failOnWarnings>
+						<quiet>true</quiet>
 					</configuration>
 				</plugin>
 				<plugin>
@@ -154,6 +169,19 @@
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-checkstyle-plugin</artifactId>
 			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<executions>
+					<execution>
+						<id>javadoc-no-warnings</id>
+						<phase>verify</phase>
+						<goals>
+							<goal>javadoc</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
 		</plugins>
 	</build>
 </project>

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

@@ -17,6 +17,7 @@
 /// The library is resolved from the platform-specific native JAR on the
 /// classpath, extracted to a temp file, and loaded once at class-init time.
 /// Override with `-Dzstd.lib.path=/path/to/libzstd.so`.
+@SuppressWarnings("restricted") // libraryLookup / downcallHandle are restricted FFM methods
 final class NativeLibrary {
 
     private static final Linker LINKER = Linker.nativeLinker();

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

@@ -12,10 +12,15 @@ public abstract class NativeObject implements AutoCloseable {
 
     private final AtomicReference<MemorySegment> ptr;
 
+    /// Takes ownership of a freshly created native pointer.
+    ///
+    /// @param owningPointer the non-NULL native pointer this object now owns
     protected NativeObject(MemorySegment owningPointer) {
         this.ptr = new AtomicReference<>(owningPointer);
     }
 
+    /// Returns the live native pointer, failing if this object is already closed.
+    ///
     /// @return the live native pointer
     /// @throws IllegalStateException if this object has been closed
     protected final MemorySegment ptr() {
@@ -39,5 +44,8 @@ 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()}
     protected abstract void tryClose(MemorySegment ptr) throws Throwable;
 }

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

@@ -108,6 +108,9 @@ public static long decompressedSize(MemorySegment frame) {
 
     /// Maximum compressed size for an input of `srcSize` bytes — the buffer
     /// size guaranteed to never overflow during compression.
+    ///
+    /// @param srcSize the uncompressed input length in bytes
+    /// @return the worst-case compressed size for that input
     public static long compressBound(long srcSize) {
         try {
             return (long) Bindings.COMPRESS_BOUND.invokeExact(srcSize);
@@ -127,6 +130,8 @@ private static long frameContentSize(byte[] compressed) {
     }
 
     /// Highest supported compression level.
+    ///
+    /// @return the maximum valid compression level
     public static int maxCompressionLevel() {
         try {
             return (int) Bindings.MAX_C_LEVEL.invokeExact();
@@ -136,6 +141,8 @@ public static int maxCompressionLevel() {
     }
 
     /// Lowest supported compression level (negative levels trade ratio for speed).
+    ///
+    /// @return the minimum valid compression level
     public static int minCompressionLevel() {
         try {
             return (int) Bindings.MIN_C_LEVEL.invokeExact();
@@ -145,6 +152,8 @@ public static int minCompressionLevel() {
     }
 
     /// The level used by {@link #compress(byte[])}.
+    ///
+    /// @return the default compression level
     public static int defaultCompressionLevel() {
         try {
             return (int) Bindings.DEFAULT_C_LEVEL.invokeExact();
@@ -154,6 +163,9 @@ public static int defaultCompressionLevel() {
     }
 
     /// Runtime zstd version, e.g. `"1.6.0"`.
+    ///
+    /// @return the linked zstd library version as an `x.y.z` string
+    @SuppressWarnings("restricted") // reinterpret needed to read a C string of unknown length
     public static String version() {
         try {
             MemorySegment p = (MemorySegment) Bindings.VERSION_STRING.invokeExact();
@@ -194,6 +206,7 @@ private static boolean isError(long code) {
         }
     }
 
+    @SuppressWarnings("restricted") // reinterpret needed to read a C string of unknown length
     private static String errorName(long code) {
         try {
             MemorySegment p = (MemorySegment) Bindings.GET_ERROR_NAME.invokeExact(code);

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

@@ -20,6 +20,7 @@ public final class ZstdCompressCtx extends NativeObject {
 
     private int level = Zstd.defaultCompressionLevel();
 
+    /// Creates a new compression context at the default level.
     public ZstdCompressCtx() {
         super(create());
     }
@@ -38,13 +39,17 @@ private static MemorySegment create() {
 
     /// Sets the compression level for subsequent {@link #compress} calls.
     ///
+    /// @param level the compression level to use
     /// @return `this`, for chaining
     public ZstdCompressCtx level(int level) {
         this.level = level;
         return this;
     }
 
     /// Compresses `src` into a new zstd frame using this context.
+    ///
+    /// @param src the bytes to compress
+    /// @return a self-describing zstd frame
     public byte[] compress(byte[] src) {
         try (Arena arena = Arena.ofConfined()) {
             MemorySegment in = Zstd.copyIn(arena, src);
@@ -61,6 +66,10 @@ public byte[] compress(byte[] src) {
     /// 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)}.
+    ///
+    /// @param src  the bytes to compress
+    /// @param dict the dictionary to compress against
+    /// @return a self-describing zstd frame
     public byte[] compress(byte[] src, ZstdDictionary dict) {
         try (Arena arena = Arena.ofConfined()) {
             MemorySegment in = Zstd.copyIn(arena, src);
@@ -76,6 +85,10 @@ public byte[] compress(byte[] src, ZstdDictionary dict) {
 
     /// Compresses `src` against a pre-digested `dict` (the level was
     /// fixed when the {@link ZstdCompressDict} was built).
+    ///
+    /// @param src  the bytes to compress
+    /// @param dict the pre-digested compression dictionary
+    /// @return a self-describing zstd frame
     public byte[] compress(byte[] src, ZstdCompressDict dict) {
         try (Arena arena = Arena.ofConfined()) {
             MemorySegment in = Zstd.copyIn(arena, src);
@@ -96,6 +109,8 @@ public byte[] compress(byte[] src, ZstdCompressDict dict) {
     ///
     /// Size `dst` with {@link 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
     /// @return the number of bytes written into `dst`
     /// @throws ZstdException if `dst` is too small or compression fails
     public long compress(MemorySegment dst, MemorySegment src) {
@@ -105,6 +120,9 @@ public long compress(MemorySegment dst, MemorySegment src) {
 
     /// Zero-copy compression against a pre-digested `dict`, segment to segment.
     ///
+    /// @param dst  the native destination buffer to write the frame into
+    /// @param src  the native source bytes to compress
+    /// @param dict the pre-digested compression dictionary
     /// @return the number of bytes written into `dst`
     public long compress(MemorySegment dst, MemorySegment src, ZstdCompressDict dict) {
         MemorySegment cdict = dict.ptr();
@@ -117,6 +135,8 @@ public long compress(MemorySegment dst, MemorySegment src, ZstdCompressDict dict
     /// compresses into it, and returns a slice trimmed to the actual frame length.
     /// The returned segment is owned by `arena`.
     ///
+    /// @param arena the arena to allocate the output segment in
+    /// @param src   the native source bytes to compress
     /// @return the zstd frame, a slice of an `arena`-owned segment
     public MemorySegment compress(Arena arena, MemorySegment src) {
         MemorySegment dst = arena.allocate(Zstd.compressBound(src.byteSize()));
@@ -127,6 +147,9 @@ public MemorySegment compress(Arena arena, MemorySegment src) {
     /// Zero-copy compression against a pre-digested `dict`, allocating the
     /// output in `arena` and returning a slice trimmed to the frame length.
     ///
+    /// @param arena the arena to allocate the output segment in
+    /// @param src   the native source bytes to compress
+    /// @param dict  the pre-digested compression dictionary
     /// @return the zstd frame, a slice of an `arena`-owned segment
     public MemorySegment compress(Arena arena, MemorySegment src, ZstdCompressDict dict) {
         MemorySegment dst = arena.allocate(Zstd.compressBound(src.byteSize()));

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

@@ -15,12 +15,17 @@ public final class ZstdCompressDict extends NativeObject {
     private final int level;
 
     /// Digests `dict` for compression at the given level.
+    ///
+    /// @param dict  the dictionary to digest
+    /// @param level the compression level to fix for this digested dictionary
     public ZstdCompressDict(ZstdDictionary dict, int level) {
         super(create(dict, level));
         this.level = level;
     }
 
     /// Digests `dict` for compression at the library default level.
+    ///
+    /// @param dict the dictionary to digest
     public ZstdCompressDict(ZstdDictionary dict) {
         this(dict, Zstd.defaultCompressionLevel());
     }
@@ -40,6 +45,8 @@ private static MemorySegment create(ZstdDictionary dict, int level) {
     }
 
     /// The level this dictionary was digested at.
+    ///
+    /// @return the fixed compression level
     public int level() {
         return level;
     }

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

@@ -9,6 +9,7 @@
 /// state allocation. Not thread-safe: confine an instance to one thread or pool it.
 public final class ZstdDecompressCtx extends NativeObject {
 
+    /// Creates a new decompression context.
     public ZstdDecompressCtx() {
         super(create());
     }
@@ -26,6 +27,10 @@ private static MemorySegment create() {
     }
 
     /// Decompresses a frame into a buffer of at most `maxSize` bytes.
+    ///
+    /// @param compressed a complete zstd frame
+    /// @param maxSize    upper bound on the decompressed length
+    /// @return the original bytes
     public byte[] decompress(byte[] compressed, int maxSize) {
         try (Arena arena = Arena.ofConfined()) {
             MemorySegment in = Zstd.copyIn(arena, compressed);
@@ -41,6 +46,11 @@ public byte[] decompress(byte[] compressed, int maxSize) {
     /// 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)}.
+    ///
+    /// @param compressed a complete zstd frame
+    /// @param maxSize    upper bound on the decompressed length
+    /// @param dict       the dictionary the frame was compressed against
+    /// @return the original bytes
     public byte[] decompress(byte[] compressed, int maxSize, ZstdDictionary dict) {
         try (Arena arena = Arena.ofConfined()) {
             MemorySegment in = Zstd.copyIn(arena, compressed);
@@ -54,6 +64,11 @@ public byte[] decompress(byte[] compressed, int maxSize, ZstdDictionary dict) {
     }
 
     /// Decompresses a frame against a pre-digested `dict`.
+    ///
+    /// @param compressed a complete zstd frame
+    /// @param maxSize    upper bound on the decompressed length
+    /// @param dict       the pre-digested decompression dictionary
+    /// @return the original bytes
     public byte[] decompress(byte[] compressed, int maxSize, ZstdDecompressDict dict) {
         try (Arena arena = Arena.ofConfined()) {
             MemorySegment in = Zstd.copyIn(arena, compressed);
@@ -75,6 +90,8 @@ public byte[] decompress(byte[] compressed, int maxSize, ZstdDecompressDict dict
     /// Size `dst` to the decompressed length (read it from the frame with
     /// {@link 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
     /// @return the number of bytes written into `dst`
     /// @throws ZstdException if `dst` is too small or the frame is invalid
     public long decompress(MemorySegment dst, MemorySegment src) {
@@ -84,6 +101,9 @@ public long decompress(MemorySegment dst, MemorySegment src) {
 
     /// Zero-copy decompression against a pre-digested `dict`, segment to segment.
     ///
+    /// @param dst  the native destination buffer to write the result into
+    /// @param src  the native source frame to decompress
+    /// @param dict the pre-digested decompression dictionary
     /// @return the number of bytes written into `dst`
     public long decompress(MemorySegment dst, MemorySegment src, ZstdDecompressDict dict) {
         MemorySegment ddict = dict.ptr();
@@ -100,6 +120,8 @@ public long decompress(MemorySegment dst, MemorySegment src, ZstdDecompressDict
     /// library do); for size-less frames use {@link #decompress(MemorySegment, MemorySegment)}
     /// with a destination you size yourself.
     ///
+    /// @param arena the arena to allocate the output segment in
+    /// @param frame a complete zstd frame storing its decompressed size
     /// @return a segment of exactly the decompressed length, allocated in `arena`
     /// @throws ZstdException if the frame is invalid or stores no size
     public MemorySegment decompress(Arena arena, MemorySegment frame) {
@@ -112,6 +134,9 @@ public MemorySegment decompress(Arena arena, MemorySegment frame) {
     /// Zero-copy decompression against a pre-digested `dict`, allocating the
     /// exact-sized output in `arena`.
     ///
+    /// @param arena the arena to allocate the output segment in
+    /// @param frame a complete zstd frame storing its decompressed size
+    /// @param dict  the pre-digested decompression dictionary
     /// @return a segment of exactly the decompressed length, allocated in `arena`
     public MemorySegment decompress(Arena arena, MemorySegment frame, ZstdDecompressDict dict) {
         long size = Zstd.decompressedSize(frame);

zstd/src/main/java/io/github/dfa1/zstdffm/ZstdDecompressDict.java

@@ -12,6 +12,8 @@
 public final class ZstdDecompressDict extends NativeObject {
 
     /// Digests `dict` for decompression.
+    ///
+    /// @param dict the dictionary to digest
     public ZstdDecompressDict(ZstdDictionary dict) {
         super(create(dict));
     }

zstd/src/main/java/io/github/dfa1/zstdffm/ZstdDictionary.java

@@ -36,6 +36,7 @@ private ZstdDictionary(byte[] bytes) {
     /// dictionary shipped with your application).
     ///
     /// @param raw dictionary bytes; defensively copied
+    /// @return a dictionary wrapping a copy of `raw`
     public static ZstdDictionary of(byte[] raw) {
         return new ZstdDictionary(raw.clone());
     }
@@ -87,6 +88,8 @@ public static ZstdDictionary train(List<byte[]> samples, int maxDictBytes) {
 
     /// The dictionary id zstd stamps into frames compressed with this dictionary,
     /// or `0` for a raw/content-only dictionary with no header.
+    ///
+    /// @return the dictionary id, or `0` if none
     public int id() {
         try (Arena arena = Arena.ofConfined()) {
             MemorySegment seg = Zstd.copyIn(arena, bytes);
@@ -96,11 +99,15 @@ public int id() {
         }
     }
 
+    /// Serialises this dictionary to a fresh byte array.
+    ///
     /// @return a copy of the raw dictionary bytes, suitable for persisting
     public byte[] toByteArray() {
         return bytes.clone();
     }
 
+    /// The size of this dictionary.
+    ///
     /// @return the dictionary size in bytes
     public int size() {
         return bytes.length;
@@ -119,6 +126,7 @@ private static boolean zdictIsError(long code) {
         }
     }
 
+    @SuppressWarnings("restricted") // reinterpret needed to read a C string of unknown length
     private static String zdictErrorName(long code) {
         try {
             MemorySegment p = (MemorySegment) Bindings.ZDICT_GET_ERROR_NAME.invokeExact(code);

zstd/src/main/java/io/github/dfa1/zstdffm/ZstdException.java

@@ -7,6 +7,8 @@
 /// recoverable I/O condition.
 public final class ZstdException extends RuntimeException {
 
+    private static final long serialVersionUID = 1L;
+
     ZstdException(String message) {
         super(message);
     }