build: restore the core javadoc ratchet, red on CI since 8ff823ec

core/src/main/java/io/github/dfa1/vortex/core/io/PTypeIO.java

@@ -86,6 +86,11 @@ private static MethodHandle[] buildSetters() {
 
     /// Write `bits` at `offset` in `seg`, narrowed or bit-reinterpreted to the ptype's carrier.
     /// Float bits use `Float.intBitsToFloat` / `Double.longBitsToDouble` semantics.
+    ///
+    /// @param seg    destination segment
+    /// @param offset byte offset within `seg` to write at
+    /// @param ptype  physical type deciding the carrier width and interpretation
+    /// @param bits   the value, as raw bits widened to a `long`
     public static void set(MemorySegment seg, long offset, PType ptype, long bits) {
         try {
             SETTERS[ptype.ordinal()].invokeExact(seg, offset, bits);
@@ -96,6 +101,12 @@ public static void set(MemorySegment seg, long offset, PType ptype, long bits) {
 
     /// Bulk-copy a primitive Java array into a freshly allocated little-endian segment.
     /// Element layout conversion (host order → LE) is delegated to `MemorySegment.copy`.
+    ///
+    /// @param ptype      physical type deciding the element width
+    /// @param typedArray the source array; its runtime type must match `ptype`
+    ///                   (`byte[]` for I8/U8, `short[]` for I16/U16, and so on)
+    /// @param count      number of leading elements to copy
+    /// @return a freshly allocated little-endian segment holding `count` elements
     public static MemorySegment copyArray(PType ptype, Object typedArray, int count) {
         MemorySegment src;
         ValueLayout srcLayout;

core/src/main/java/io/github/dfa1/vortex/core/model/DType.java

@@ -129,6 +129,8 @@ default DType withNullable(boolean nullable) {
     /// Non-nullable [Primitive] of [PType#F64].
     Primitive F64 = new Primitive(PType.F64, false);
 
+    /// Creates a non-nullable [Decimal] of the given precision and scale.
+    ///
     /// @param precision total number of significant decimal digits
     /// @param scale     number of digits to the right of the decimal point
     /// @return non-nullable [Decimal]
@@ -327,6 +329,8 @@ record Extension(
         /// that would inflate parser allocations.
         public static final MemorySize MAX_METADATA_SIZE = MemorySize.ofKiB(64);
 
+        /// Bounds the metadata blob, which arrives from an untrusted file.
+        ///
         /// @throws VortexException if `metadata` carries more than
         ///         [#MAX_METADATA_SIZE] readable bytes
         public Extension {

core/src/main/java/io/github/dfa1/vortex/core/model/EditionId.java

@@ -16,6 +16,8 @@
 /// @param version  distinguishes editions cut in the same month; normally `0`
 public record EditionId(EditionFamily family, YearMonth cutMonth, int version) {
 
+    /// Rejects a partially specified id: both the family and the cut month identify an edition.
+    ///
     /// @throws NullPointerException if `family` or `cutMonth` is `null`
     public EditionId {
         Objects.requireNonNull(family, "family");

core/src/main/java/io/github/dfa1/vortex/core/model/MemorySize.java

@@ -12,6 +12,8 @@
 /// @param bytes the byte count; never negative
 public record MemorySize(long bytes) {
 
+    /// Rejects a negative size at construction, so no caller downstream has to re-check one.
+    ///
     /// @throws IllegalArgumentException if `bytes` is negative
     public MemorySize {
         if (bytes < 0) {