diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/IoWorker.java b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/IoWorker.java index b62a0c34..46c0b44e 100644 --- a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/IoWorker.java +++ b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/IoWorker.java @@ -12,7 +12,7 @@ /// opened the file. The TUI dispatches all such calls to this worker so the /// render loop on the main thread never crosses the arena's owning thread. /// -/// {@link #pending()} drives the status-line counter; callers should check it +/// [#pending()] drives the status-line counter; callers should check it /// when computing UI state. public final class IoWorker implements AutoCloseable { @@ -40,8 +40,8 @@ public void submit(Runnable task) { return; } pending.incrementAndGet(); - // Unbounded {@link LinkedBlockingQueue} never rejects on capacity; {@code add} is the - // right idiom (throws {@code IllegalStateException} on the impossible case) so we don't + // Unbounded [LinkedBlockingQueue] never rejects on capacity; `add` is the + // right idiom (throws `IllegalStateException` on the impossible case) so we don't // silently drop tasks if anyone ever swaps in a bounded queue. queue.add(() -> { try { diff --git a/cli/src/test/java/io/github/dfa1/vortex/cli/FilterCommandTest.java b/cli/src/test/java/io/github/dfa1/vortex/cli/FilterCommandTest.java index 0428849e..c48e5263 100644 --- a/cli/src/test/java/io/github/dfa1/vortex/cli/FilterCommandTest.java +++ b/cli/src/test/java/io/github/dfa1/vortex/cli/FilterCommandTest.java @@ -23,7 +23,7 @@ class FilterCommandTest { @BeforeEach void setUp() throws IOException { - // 3-row Vortex file with one I64 column {@code id} = [1, 2, 3]. + // 3-row Vortex file with one I64 column `id` = [1, 2, 3]. file = writeSmallVortex(tmp, "filter.vortex"); } diff --git a/cli/src/test/java/io/github/dfa1/vortex/cli/ImportCommandTest.java b/cli/src/test/java/io/github/dfa1/vortex/cli/ImportCommandTest.java index 0abe0039..7e8c25ec 100644 --- a/cli/src/test/java/io/github/dfa1/vortex/cli/ImportCommandTest.java +++ b/cli/src/test/java/io/github/dfa1/vortex/cli/ImportCommandTest.java @@ -31,7 +31,7 @@ void noArgs_returnsUsageError() { @Test void delimiterMissingValue_returnsUsageError() { - // Given / When — {@code --delimiter} at the tail with no value + // Given / When — `--delimiter` at the tail with no value CliTestSupport.Captured result = capture(() -> ImportCommand.run(new String[]{"import", "--delimiter"})); @@ -125,9 +125,9 @@ void csvWithCustomDelimiter_imports(@TempDir Path tmp) throws IOException { ImportCommand.run(new String[]{"import", "--delimiter", "\t", csv.toString()})); // Then — without the explicit delimiter the import would treat the whole row as one - // column. Success here confirms the {@code --delimiter} flag plumbs through. - // Output filename: input is {@code data.tsv}, deriveOutputPath only strips - // {@code .csv}/{@code .parquet} suffixes, so the result is {@code data.tsv.vortex}. + // column. Success here confirms the `--delimiter` flag plumbs through. + // Output filename: input is `data.tsv`, deriveOutputPath only strips + // `.csv`/`.parquet` suffixes, so the result is `data.tsv.vortex`. assertThat(result.status()).isEqualTo(ExitStatus.OK); assertThat(tmp.resolve("data.tsv.vortex")).exists(); } diff --git a/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/KeyDecoderTest.java b/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/KeyDecoderTest.java index ddd81ad3..764fa709 100644 --- a/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/KeyDecoderTest.java +++ b/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/KeyDecoderTest.java @@ -124,8 +124,8 @@ void next_multiDigitTildeCode_handlesTwoDigits() throws IOException { @Test void next_ss3SequenceVariant_decodesArrows() throws IOException { - // Given — DEC keypad / VT100 application-cursor mode uses {@code ESC O A} - // instead of {@code ESC [ A}. KeyDecoder must accept both prefixes so the + // Given — DEC keypad / VT100 application-cursor mode uses `ESC O A` + // instead of `ESC [ A`. KeyDecoder must accept both prefixes so the // TUI works under tmux / screen / putty configurations that ship SS3. assertThat(KeyDecoder.next(bytes(0x1B, 'O', 'A'))).isEqualTo(Key.ArrowUp.INSTANCE); assertThat(KeyDecoder.next(bytes(0x1B, 'O', 'D'))).isEqualTo(Key.ArrowLeft.INSTANCE); @@ -135,7 +135,7 @@ void next_ss3SequenceVariant_decodesArrows() throws IOException { @Test void next_unknownEscapePrefix_yieldsEscape() throws IOException { - // Given — {@code ESC X} (X is neither '[' nor 'O') is not a recognised + // Given — `ESC X` (X is neither '[' nor 'O') is not a recognised // CSI or SS3 sequence. Must return Escape rather than try to decode further. ByteArrayInputStream in = bytes(0x1B, 'X', 'A'); @@ -148,7 +148,7 @@ void next_unknownEscapePrefix_yieldsEscape() throws IOException { @Test void next_eofMidTildeSequence_returnsEof() throws IOException { - // Given — partial {@code ESC [ 5} with no trailing tilde / digit + // Given — partial `ESC [ 5` with no trailing tilde / digit ByteArrayInputStream in = bytes(0x1B, '[', '5'); // When @@ -160,7 +160,7 @@ void next_eofMidTildeSequence_returnsEof() throws IOException { @Test void next_tildeWithoutTrailingTildeChar_yieldsEscape() throws IOException { - // Given — {@code ESC [ 5 x}: digit followed by a non-tilde non-digit. + // Given — `ESC [ 5 x`: digit followed by a non-tilde non-digit. // The trailing character must be re-yielded by the next call, not lost. ByteArrayInputStream in = bytes(0x1B, '[', '5', 'x', 'y'); @@ -177,7 +177,7 @@ void next_tildeWithoutTrailingTildeChar_yieldsEscape() throws IOException { @Test void next_controlByte_returnsCharWithRawValue() throws IOException { // Given — Ctrl-C is 0x03, no special handling — surfaced as Char so the - // TUI's keymap can match it via {@code Key.Char(3)} if needed. + // TUI's keymap can match it via `Key.Char(3)` if needed. ByteArrayInputStream in = bytes(0x03); // When diff --git a/core/src/main/java/io/github/dfa1/vortex/core/PType.java b/core/src/main/java/io/github/dfa1/vortex/core/PType.java index 64371830..a4917402 100644 --- a/core/src/main/java/io/github/dfa1/vortex/core/PType.java +++ b/core/src/main/java/io/github/dfa1/vortex/core/PType.java @@ -61,13 +61,13 @@ public boolean isSigned() { /// /// Unlike `PType.values()[ordinal]`, this method validates the ordinal against the /// declared range and throws [VortexException] for crafted out-of-range values rather - /// than the JDK's {@link ArrayIndexOutOfBoundsException}. Use this at every decode site that + /// than the JDK's [ArrayIndexOutOfBoundsException]. Use this at every decode site that /// reads a ptype from untrusted metadata. /// /// @param ordinal the enum ordinal, typically taken from a Protobuf `ptype` field - /// @return the {@link PType} for the given ordinal + /// @return the [PType] for the given ordinal /// @throws VortexException if `ordinal` is negative or greater than the largest defined - /// {@link PType} ordinal + /// [PType] ordinal public static PType fromOrdinal(int ordinal) { PType[] all = values(); if (ordinal < 0 || ordinal >= all.length) { diff --git a/core/src/main/java/io/github/dfa1/vortex/encoding/TimeUnit.java b/core/src/main/java/io/github/dfa1/vortex/encoding/TimeUnit.java index e615cc27..258a92a9 100644 --- a/core/src/main/java/io/github/dfa1/vortex/encoding/TimeUnit.java +++ b/core/src/main/java/io/github/dfa1/vortex/encoding/TimeUnit.java @@ -10,7 +10,7 @@ public enum TimeUnit { Milliseconds, /// Seconds — ordinal 3. Seconds, - /// Days — ordinal 4. Not sub-dividable; {@link #divisor()} throws for this value. + /// Days — ordinal 4. Not sub-dividable; [#divisor()] throws for this value. Days; /// Returns the `TimeUnit` for the given wire tag byte. diff --git a/core/src/main/java/io/github/dfa1/vortex/proto/ProtoWriter.java b/core/src/main/java/io/github/dfa1/vortex/proto/ProtoWriter.java index 8d1c4060..5a3c36d1 100644 --- a/core/src/main/java/io/github/dfa1/vortex/proto/ProtoWriter.java +++ b/core/src/main/java/io/github/dfa1/vortex/proto/ProtoWriter.java @@ -95,7 +95,7 @@ void writeEmbedded(byte[] encoded) { /// Returns a mark to pass back to [#endLenDelim(int)]; the caller writes the payload /// in between. Avoids the alloc/copy round-trip of writing into a temporary `ProtoWriter`. /// - /// Reserves the worst-case 5 bytes for a varint32 length; {@link #endLenDelim} backpatches + /// Reserves the worst-case 5 bytes for a varint32 length; [#endLenDelim] backpatches /// the actual length and shifts the payload left if a shorter varint suffices. int beginLenDelim() { ensure(MAX_LEN_VARINT); diff --git a/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java b/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java index 0b0ab6a3..d9253905 100644 --- a/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java +++ b/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java @@ -29,7 +29,7 @@ /// /// The schema is derived from [ResultSetMetaData] — no type inference is needed. /// SQL NULL values are mapped to `0`, `0.0`, `false`, or `""` depending on column type. -/// Use {@link JdbcImportOptions#withFetchSize} to control driver-side streaming for large tables. +/// Use [JdbcImportOptions#withFetchSize] to control driver-side streaming for large tables. public final class JdbcImporter { private JdbcImporter() { diff --git a/performance/src/main/java/io/github/dfa1/vortex/performance/ParquetVsVortexReadBenchmark.java b/performance/src/main/java/io/github/dfa1/vortex/performance/ParquetVsVortexReadBenchmark.java index b803f0dd..ae4182de 100644 --- a/performance/src/main/java/io/github/dfa1/vortex/performance/ParquetVsVortexReadBenchmark.java +++ b/performance/src/main/java/io/github/dfa1/vortex/performance/ParquetVsVortexReadBenchmark.java @@ -42,10 +42,10 @@ /// /// Two Parquet variants: /// - `parquetRead` / `parquetReadMultiColumn`: batch column API -/// ({@link ColumnReader#nextBatch()} + {@link ColumnReader#getDoubles()}) — +/// ([ColumnReader#nextBatch()] + [ColumnReader#getDoubles()]) — /// apples-to-apples comparison with Vortex's batch fold. /// - `parquetReadRowByRow` / `parquetReadMultiColumnRowByRow`: -/// Hardwood row cursor ({@link RowReader}) — measures row-oriented API overhead +/// Hardwood row cursor ([RowReader]) — measures row-oriented API overhead /// on top of format decode cost. /// /// Override the Parquet source with: `-Dbench.parquet=/path/to/file.parquet` diff --git a/performance/src/main/java/io/github/dfa1/vortex/performance/RustVsJavaFilterBenchmark.java b/performance/src/main/java/io/github/dfa1/vortex/performance/RustVsJavaFilterBenchmark.java index 53c0b750..77260eef 100644 --- a/performance/src/main/java/io/github/dfa1/vortex/performance/RustVsJavaFilterBenchmark.java +++ b/performance/src/main/java/io/github/dfa1/vortex/performance/RustVsJavaFilterBenchmark.java @@ -42,7 +42,7 @@ /// with a `close > threshold` predicate at varying selectivity. /// /// Phase 0 instrument for ADR 0010 (lazy decode). The threshold is chosen at -/// setup time so each {@link #selectivity} value selects approximately that +/// setup time so each [#selectivity] value selects approximately that /// fraction of rows. Both readers report the sum of surviving close values so /// the JVM cannot elide the per-row work. /// @@ -52,7 +52,7 @@ /// /// Requires a pre-existing OHLC file: /// `-Dvortex.bench.ohlc=/path/to/file.vtx`. Generate one by running -/// {@link RustVsJavaReadBenchmark} first with the same `vortex.bench.ohlc` +/// [RustVsJavaReadBenchmark] first with the same `vortex.bench.ohlc` /// pointing at the path you want (the read benchmark will write it lazily if /// the file does not exist yet). @State(Scope.Benchmark) @@ -74,7 +74,7 @@ public class RustVsJavaFilterBenchmark { } /// Target fraction of rows that should satisfy `close > threshold`. - /// The threshold is computed in {@link #setup()} from a sample of the + /// The threshold is computed in [#setup()] from a sample of the /// "close" column; the realised selectivity is reported in the setup log /// and may differ slightly from this value on small samples. @Param({"0.001", "0.01", "0.1", "1.0"}) diff --git a/performance/src/main/java/io/github/dfa1/vortex/performance/RustWritesJavaReadsBigFileBenchmark.java b/performance/src/main/java/io/github/dfa1/vortex/performance/RustWritesJavaReadsBigFileBenchmark.java index eb7d203e..c998e657 100644 --- a/performance/src/main/java/io/github/dfa1/vortex/performance/RustWritesJavaReadsBigFileBenchmark.java +++ b/performance/src/main/java/io/github/dfa1/vortex/performance/RustWritesJavaReadsBigFileBenchmark.java @@ -48,7 +48,7 @@ import java.util.Random; import java.util.concurrent.TimeUnit; -/// Big-file scan benchmark for files exceeding 2 GB ({@link io.github.dfa1.vortex.reader.SegmentSpec#length()} +/// Big-file scan benchmark for files exceeding 2 GB ([io.github.dfa1.vortex.reader.SegmentSpec#length()] /// is `long`, so segments up to 4 GB are supported). /// /// Setup: JNI writer produces a >2 GB Vortex file with 4 incompressible I64 columns diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java b/reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java index f6c9c617..02ff6f14 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java @@ -19,7 +19,7 @@ /// Read-side registry: maps [EncodingId] to [EncodingDecoder] implementations. /// /// Instances are immutable after construction. Build one via [#builder()] or -/// via the {@link #loadAll()} and {@link #empty()} convenience factories. +/// via the [#loadAll()] and [#empty()] convenience factories. public final class ReadRegistry { private final Map decoders; diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ArraySegments.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ArraySegments.java index 90051d8e..a30ee36d 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ArraySegments.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ArraySegments.java @@ -10,7 +10,7 @@ /// Internal materialization engine: turns any [Array] into its primary /// [MemorySegment], allocating from a caller-supplied arena for lazy variants. /// -/// If `arr` is a {@link MaskedArray}, the inner (data) segment is returned; +/// If `arr` is a [MaskedArray], the inner (data) segment is returned; /// the validity mask is not surfaced here — callers that need validity must unwrap manually. /// /// **Vortex-internal — not public API.** This class is `public` only because the reader, @@ -20,8 +20,8 @@ /// (which routes here). It backs that seam plus /// [io.github.dfa1.vortex.reader.ReadRegistry#decodeAsSegment] and the scan layer's dictionary /// validation. Application code should prefer the typed accessors on concrete subtypes — -/// {@link LongArray#getLong(long)}, {@link IntArray#getInt(long)}, -/// {@link DoubleArray#getDouble(long)}, and friends. +/// [LongArray#getLong(long)], [IntArray#getInt(long)], +/// [DoubleArray#getDouble(long)], and friends. public final class ArraySegments { private ArraySegments() { diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedBoolArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedBoolArray.java index dc0abb04..36fa0073 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedBoolArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedBoolArray.java @@ -26,7 +26,7 @@ public record ChunkedBoolArray(DType dtype, long length, BoolArray[] children, l /// @param totalRows expected total row count /// @param chunks non-empty list of chunk arrays /// @return a new [ChunkedBoolArray] - /// @throws VortexException on empty input, non-{@link BoolArray} chunks, or row-count mismatch + /// @throws VortexException on empty input, non-[BoolArray] chunks, or row-count mismatch public static ChunkedBoolArray of(DType dtype, long totalRows, List chunks) { if (chunks.isEmpty()) { throw new VortexException("ChunkedBoolArray: empty chunk list"); diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedByteArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedByteArray.java index 1e9cebda..39c483a9 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedByteArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedByteArray.java @@ -23,7 +23,7 @@ public record ChunkedByteArray(DType dtype, long length, ByteArray[] children, l /// @param totalRows expected total row count /// @param chunks non-empty list of chunk arrays /// @return a new [ChunkedByteArray] - /// @throws VortexException on empty input, non-{@link ByteArray} chunks, or row-count mismatch + /// @throws VortexException on empty input, non-[ByteArray] chunks, or row-count mismatch public static ChunkedByteArray of(DType dtype, long totalRows, List chunks) { if (chunks.isEmpty()) { throw new VortexException("ChunkedByteArray: empty chunk list"); diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedDoubleArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedDoubleArray.java index 21481d29..eef78063 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedDoubleArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedDoubleArray.java @@ -25,8 +25,8 @@ public record ChunkedDoubleArray(DType dtype, long length, DoubleArray[] childre /// @param dtype logical element type /// @param totalRows expected total row count /// @param chunks non-empty list of chunk arrays - /// @return a new {@link ChunkedDoubleArray} - /// @throws VortexException on empty input, non-{@link DoubleArray} chunks, or row-count mismatch + /// @return a new [ChunkedDoubleArray] + /// @throws VortexException on empty input, non-[DoubleArray] chunks, or row-count mismatch public static ChunkedDoubleArray of(DType dtype, long totalRows, List chunks) { if (chunks.isEmpty()) { throw new VortexException("ChunkedDoubleArray: empty chunk list"); diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedFloatArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedFloatArray.java index 15e1aaba..4006002c 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedFloatArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedFloatArray.java @@ -23,7 +23,7 @@ public record ChunkedFloatArray(DType dtype, long length, FloatArray[] children, /// @param totalRows expected total row count /// @param chunks non-empty list of chunk arrays /// @return a new [ChunkedFloatArray] - /// @throws VortexException on empty input, non-{@link FloatArray} chunks, or row-count mismatch + /// @throws VortexException on empty input, non-[FloatArray] chunks, or row-count mismatch public static ChunkedFloatArray of(DType dtype, long totalRows, List chunks) { if (chunks.isEmpty()) { throw new VortexException("ChunkedFloatArray: empty chunk list"); diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedIntArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedIntArray.java index 861014b1..16c40af7 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedIntArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedIntArray.java @@ -24,7 +24,7 @@ public record ChunkedIntArray(DType dtype, long length, IntArray[] children, lon /// @param totalRows expected total row count /// @param chunks non-empty list of chunk arrays /// @return a new [ChunkedIntArray] - /// @throws VortexException on empty input, non-{@link IntArray} chunks, or row-count mismatch + /// @throws VortexException on empty input, non-[IntArray] chunks, or row-count mismatch public static ChunkedIntArray of(DType dtype, long totalRows, List chunks) { if (chunks.isEmpty()) { throw new VortexException("ChunkedIntArray: empty chunk list"); diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedLongArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedLongArray.java index 6d8de9ba..6531b6f6 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedLongArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedLongArray.java @@ -34,8 +34,8 @@ public record ChunkedLongArray(DType dtype, long length, LongArray[] children, l /// @param dtype logical element type /// @param totalRows expected total row count across all chunks /// @param chunks non-empty list of chunk arrays - /// @return a new {@link ChunkedLongArray} over the flattened chunks - /// @throws VortexException on empty input, non-{@link LongArray} chunks, or row-count mismatch + /// @return a new [ChunkedLongArray] over the flattened chunks + /// @throws VortexException on empty input, non-[LongArray] chunks, or row-count mismatch public static ChunkedLongArray of(DType dtype, long totalRows, List chunks) { if (chunks.isEmpty()) { throw new VortexException("ChunkedLongArray: empty chunk list"); diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedShortArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedShortArray.java index b43c7163..f6094aeb 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedShortArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedShortArray.java @@ -24,7 +24,7 @@ public record ChunkedShortArray(DType dtype, long length, ShortArray[] children, /// @param totalRows expected total row count /// @param chunks non-empty list of chunk arrays /// @return a new [ChunkedShortArray] - /// @throws VortexException on empty input, non-{@link ShortArray} chunks, or row-count mismatch + /// @throws VortexException on empty input, non-[ShortArray] chunks, or row-count mismatch public static ChunkedShortArray of(DType dtype, long totalRows, List chunks) { if (chunks.isEmpty()) { throw new VortexException("ChunkedShortArray: empty chunk list"); diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DecimalBytePartsArrays.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DecimalBytePartsArrays.java index 11bd87e3..754d1e10 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DecimalBytePartsArrays.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DecimalBytePartsArrays.java @@ -22,7 +22,7 @@ private DecimalBytePartsArrays() { /// /// @param arr source typed Array (must be one of Byte/Short/Int/Long, optionally MaskedArray-wrapped) /// @param i row index - /// @return cell value as a {@link BigInteger} + /// @return cell value as a [BigInteger] /// @throws VortexException for null cells or unsupported array types static BigInteger readMantissa(Array arr, long i) { return switch (arr) { diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictDoubleArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictDoubleArray.java index ab1ff41b..2aee6cdf 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictDoubleArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictDoubleArray.java @@ -15,13 +15,13 @@ /// /// The `codes` array is typed as [Array] because the codes ptype /// varies with dictionary size — U8/U16/U32/U64 backed by -/// {@link ByteArray}/{@link ShortArray}/{@link IntArray}/{@link LongArray}. +/// [ByteArray]/[ShortArray]/[IntArray]/[LongArray]. /// /// @param dtype logical element type (matches `values.dtype()`) /// @param length total logical row count (matches `codes.length()`) /// @param values dictionary pool — element at code `c` is `values.getDouble(c)` /// @param codes per-row index into `values`; must be one of -/// {@link ByteArray}, {@link ShortArray}, {@link IntArray}, {@link LongArray} +/// [ByteArray], [ShortArray], [IntArray], [LongArray] public record DictDoubleArray(DType dtype, long length, DoubleArray values, Array codes) implements DoubleArray { /// Builds a [DictDoubleArray], validating that `codes` is one of the @@ -31,8 +31,8 @@ public record DictDoubleArray(DType dtype, long length, DoubleArray values, Arra /// @param length total logical row count /// @param values dictionary pool /// @param codes per-row code array (must be [ByteArray], [ShortArray], - /// {@link IntArray}, or {@link LongArray}) - /// @return a new {@link DictDoubleArray} + /// [IntArray], or [LongArray]) + /// @return a new [DictDoubleArray] /// @throws VortexException if `codes` is not a supported code-array type or /// its length does not equal `length` public static DictDoubleArray of(DType dtype, long length, DoubleArray values, Array codes) { diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictFloatArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictFloatArray.java index 60a63349..04e08246 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictFloatArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictFloatArray.java @@ -14,13 +14,13 @@ /// /// The `codes` array is typed as [Array] because the codes ptype /// varies with dictionary size — U8/U16/U32/U64 backed by -/// {@link ByteArray}/{@link ShortArray}/{@link IntArray}/{@link LongArray}. +/// [ByteArray]/[ShortArray]/[IntArray]/[LongArray]. /// /// @param dtype logical element type (matches `values.dtype()`) /// @param length total logical row count (matches `codes.length()`) /// @param values dictionary pool — element at code `c` is `values.getFloat(c)` /// @param codes per-row index into `values`; must be one of -/// {@link ByteArray}, {@link ShortArray}, {@link IntArray}, {@link LongArray} +/// [ByteArray], [ShortArray], [IntArray], [LongArray] public record DictFloatArray(DType dtype, long length, FloatArray values, Array codes) implements FloatArray { /// Builds a [DictFloatArray], validating that `codes` is one of the @@ -30,8 +30,8 @@ public record DictFloatArray(DType dtype, long length, FloatArray values, Array /// @param length total logical row count /// @param values dictionary pool /// @param codes per-row code array (must be [ByteArray], [ShortArray], - /// {@link IntArray}, or {@link LongArray}) - /// @return a new {@link DictFloatArray} + /// [IntArray], or [LongArray]) + /// @return a new [DictFloatArray] /// @throws VortexException if `codes` is not a supported code-array type or /// its length does not equal `length` public static DictFloatArray of(DType dtype, long length, FloatArray values, Array codes) { diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictIntArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictIntArray.java index 7be87078..bf3279e4 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictIntArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictIntArray.java @@ -15,13 +15,13 @@ /// /// The `codes` array is typed as [Array] because the codes ptype /// varies with dictionary size — U8/U16/U32/U64 backed by -/// {@link ByteArray}/{@link ShortArray}/{@link IntArray}/{@link LongArray}. +/// [ByteArray]/[ShortArray]/[IntArray]/[LongArray]. /// /// @param dtype logical element type (matches `values.dtype()`) /// @param length total logical row count (matches `codes.length()`) /// @param values dictionary pool — element at code `c` is `values.getInt(c)` /// @param codes per-row index into `values`; must be one of -/// {@link ByteArray}, {@link ShortArray}, {@link IntArray}, {@link LongArray} +/// [ByteArray], [ShortArray], [IntArray], [LongArray] public record DictIntArray(DType dtype, long length, IntArray values, Array codes) implements IntArray { /// Builds a [DictIntArray], validating that `codes` is one of the @@ -31,8 +31,8 @@ public record DictIntArray(DType dtype, long length, IntArray values, Array code /// @param length total logical row count /// @param values dictionary pool /// @param codes per-row code array (must be [ByteArray], [ShortArray], - /// {@link IntArray}, or {@link LongArray}) - /// @return a new {@link DictIntArray} + /// [IntArray], or [LongArray]) + /// @return a new [DictIntArray] /// @throws VortexException if `codes` is not a supported code-array type or /// its length does not equal `length` public static DictIntArray of(DType dtype, long length, IntArray values, Array codes) { diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictLongArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictLongArray.java index 2423359b..80682fda 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictLongArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictLongArray.java @@ -17,14 +17,14 @@ /// /// The `codes` array is typed as [Array] because the codes ptype /// varies with dictionary size — U8/U16/U32/U64 backed by -/// {@link ByteArray}/{@link ShortArray}/{@link IntArray}/{@link LongArray}. -/// {@link #of} validates that `codes` is one of those four types. +/// [ByteArray]/[ShortArray]/[IntArray]/[LongArray]. +/// [#of] validates that `codes` is one of those four types. /// /// @param dtype logical element type (matches `values.dtype()`) /// @param length total logical row count (matches `codes.length()`) /// @param values dictionary pool — element at code `c` is `values.getLong(c)` /// @param codes per-row index into `values`; must be one of -/// {@link ByteArray}, {@link ShortArray}, {@link IntArray}, {@link LongArray} +/// [ByteArray], [ShortArray], [IntArray], [LongArray] public record DictLongArray(DType dtype, long length, LongArray values, Array codes) implements LongArray { /// Builds a [DictLongArray], validating that `codes` is one of the @@ -34,8 +34,8 @@ public record DictLongArray(DType dtype, long length, LongArray values, Array co /// @param length total logical row count /// @param values dictionary pool /// @param codes per-row code array (must be [ByteArray], [ShortArray], - /// {@link IntArray}, or {@link LongArray}) - /// @return a new {@link DictLongArray} + /// [IntArray], or [LongArray]) + /// @return a new [DictLongArray] /// @throws VortexException if `codes` is not a supported code-array type or /// its length does not equal `length` public static DictLongArray of(DType dtype, long length, LongArray values, Array codes) { diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java index 5af74ddd..ddfca6c8 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java @@ -89,7 +89,7 @@ MemorySegment buffer(int i) { /// handled by [LazyDecimalBytePartsArray] directly. /// /// @param i row index, `0 <= i < length()` - /// @return decoded value as a {@link BigDecimal} with the dtype's scale + /// @return decoded value as a [BigDecimal] with the dtype's scale /// @throws VortexException if the dtype isn't decimal or the array /// shape isn't the single-buffer layout /// @throws IndexOutOfBoundsException if `i` is outside `[0, length())` diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArray.java index e6272b32..78c3923d 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArray.java @@ -24,8 +24,8 @@ /// The record's [#dtype()] is the parent Extension dtype (e.g. /// `vortex.timestamp`) so it slots transparently into the extension-decode /// pipeline. Children may be any signed integer typed Array -/// ({@link ByteArray}/{@link ShortArray}/{@link IntArray}/{@link LongArray}); the -/// per-row {@link DateTimePartsArrays#readLong} switch handles widening. +/// ([ByteArray]/[ShortArray]/[IntArray]/[LongArray]); the +/// per-row [DateTimePartsArrays#readLong] switch handles widening. /// /// @param dtype logical element type (typically a `DType.Extension`) /// @param length total logical row count diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java index 7d8f310f..8778ba56 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java @@ -18,7 +18,7 @@ /// them with the parent dtype's scale into a [BigDecimal] on demand. No /// arena allocation happens at construction time. /// -/// @param dtype the parent {@link DType.Decimal} dtype (precision + scale + nullable) +/// @param dtype the parent [DType.Decimal] dtype (precision + scale + nullable) /// @param length total logical row count /// @param buf backing little-endian two's-complement integer buffer /// @param byteWidth element width in bytes; one of 1, 2, 4, 8, 16 diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java index 00b17f43..df0099b0 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java @@ -11,11 +11,11 @@ /// emits or accepts) the encoding stores its mantissa as a single signed-integer /// child column, paired with the parent's [DType.Decimal] precision and /// scale. [#getDecimal(long)] reads one cell from the child via -/// {@link DecimalBytePartsArrays#readMantissa(Array, long)} and combines it with -/// the dtype scale to produce a {@link BigDecimal} on demand — no buffer +/// [DecimalBytePartsArrays#readMantissa(Array, long)] and combines it with +/// the dtype scale to produce a [BigDecimal] on demand — no buffer /// materialisation occurs at construction time. /// -/// @param dtype the parent {@link DType.Decimal} dtype (precision + scale + nullable) +/// @param dtype the parent [DType.Decimal] dtype (precision + scale + nullable) /// @param length total logical row count /// @param msp child array holding the most-significant integer part of the mantissa public record LazyDecimalBytePartsArray(DType dtype, long length, Array msp) implements DecimalArray { diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpEncodingDecoder.java index 8fb0399f..1ff5907d 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpEncodingDecoder.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpEncodingDecoder.java @@ -79,8 +79,8 @@ public Array decode(DecodeContext ctx) { private static Array decodeF64(DecodeContext ctx, ALPMetadata meta, int expE, int expF, long n) { // Decode formula mirrors the Rust reference (`ALPFloat::decode_single`): two-step - // {@code encoded * F10[f] * IF10[e]}. A pre-multiplied {@code scale = F10[f] * IF10[e]} - // gives different IEEE rounding for non-trivial {@code expF}, breaking round-trip with + // `encoded * F10[f] * IF10[e]`. A pre-multiplied `scale = F10[f] * IF10[e]` + // gives different IEEE rounding for non-trivial `expF`, breaking round-trip with // the encoder's verify step. double df = F10_F64[expF]; double de = IF10_F64[expE]; diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecodeContext.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecodeContext.java index 1d1bbc79..06b7687e 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecodeContext.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecodeContext.java @@ -12,7 +12,7 @@ /// Decoding context passed to each [EncodingDecoder]. /// /// Buffers are [MemorySegment] slices materialized from the file's segment table; -/// children are decoded recursively via {@link #decodeChild(int)}. +/// children are decoded recursively via [#decodeChild(int)]. /// The arena is scoped to one chunk epoch — all decode output allocated from it is /// valid until the next chunk is opened. /// diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/EncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/EncodingDecoder.java index 581453c1..ab4f9783 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/EncodingDecoder.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/EncodingDecoder.java @@ -8,7 +8,7 @@ /// are discovered via [java.util.ServiceLoader]. /// /// Register via [io.github.dfa1.vortex.reader.ReadRegistry] — implementations -/// are discoverable via {@link java.util.ServiceLoader}. +/// are discoverable via [java.util.ServiceLoader]. public interface EncodingDecoder { /// Returns the wire identifier of this decoder. diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/UnknownArrayNode.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/UnknownArrayNode.java index cc0f662c..3b4aba1f 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/UnknownArrayNode.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/UnknownArrayNode.java @@ -5,7 +5,7 @@ /// Array node whose encoding id is not a recognised [io.github.dfa1.vortex.encoding.EncodingId]. /// Produced when a file uses an encoding this build does not know about. Decoded as /// [io.github.dfa1.vortex.reader.array.UnknownArray] when -/// {@link io.github.dfa1.vortex.reader.ReadRegistry#isAllowUnknown()} is set; otherwise the decode call throws. +/// [io.github.dfa1.vortex.reader.ReadRegistry#isAllowUnknown()] is set; otherwise the decode call throws. /// /// @param rawEncodingId the raw encoding id string from the file /// @param metadata encoding-specific metadata bytes, or `null` diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java index 1e981b8c..5b09b309 100644 --- a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java +++ b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java @@ -62,8 +62,8 @@ public static TimeUnit readUnit(DType.Extension ext) { /// /// @param raw epoch count /// @param unit time resolution; must not be [TimeUnit#Days] - /// @return matching {@link Instant} - /// @throws VortexException if `unit` is {@link TimeUnit#Days} + /// @return matching [Instant] + /// @throws VortexException if `unit` is [TimeUnit#Days] public static Instant instantFromRaw(long raw, TimeUnit unit) { return switch (unit) { case Seconds -> Instant.ofEpochSecond(raw); diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/LayoutDepthBombSecurityTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/LayoutDepthBombSecurityTest.java index 6e6f0738..ba5cfddc 100644 --- a/reader/src/test/java/io/github/dfa1/vortex/reader/LayoutDepthBombSecurityTest.java +++ b/reader/src/test/java/io/github/dfa1/vortex/reader/LayoutDepthBombSecurityTest.java @@ -26,15 +26,15 @@ /** * Adversarial tests for the layout-tree recursion in - * {@link PostscriptParser}'s {@code convertLayout}. + * [PostscriptParser]'s `convertLayout`. * *

The reader walks the layout tree recursively when materialising a file's - * {@code Layout} object. Without a depth cap a crafted file with thousands of - * nested children produces a {@link StackOverflowError} during {@code VortexReader.open}, - * breaking the contract that every malformed input must surface as a {@link VortexException}. + * `Layout` object. Without a depth cap a crafted file with thousands of + * nested children produces a [StackOverflowError] during `VortexReader.open`, + * breaking the contract that every malformed input must surface as a [VortexException]. * *

This test pins the contract: deeply nested layouts must be rejected as - * {@link VortexException}, never a {@link StackOverflowError}. + * [VortexException], never a [StackOverflowError]. */ class LayoutDepthBombSecurityTest { @@ -55,8 +55,8 @@ void deeplyNestedLayout_throwsVortexException(@TempDir Path tmp) throws Exceptio // ── File builders ───────────────────────────────────────────────────────── /** - * Builds a .vtx file whose root Layout has {@code depth} levels of single-child nesting, - * each level reusing the same {@code vortex.flat} layout spec. + * Builds a .vtx file whose root Layout has `depth` levels of single-child nesting, + * each level reusing the same `vortex.flat` layout spec. */ private static Path buildDeeplyNestedFile(Path dir, int depth) throws Exception { byte[] body = new byte[8]; // unused placeholder diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/MalformedFooterSecurityTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/MalformedFooterSecurityTest.java index cf9789f3..a576f097 100644 --- a/reader/src/test/java/io/github/dfa1/vortex/reader/MalformedFooterSecurityTest.java +++ b/reader/src/test/java/io/github/dfa1/vortex/reader/MalformedFooterSecurityTest.java @@ -28,15 +28,15 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy; /** - * Adversarial tests for {@code footer.segmentSpecs[i]} bounds. + * Adversarial tests for `footer.segmentSpecs[i]` bounds. * - *

Every {@link SegmentSpec} declared in the footer is later sliced from the memory-mapped - * file via {@code fileSegment.asSlice(spec.offset(), spec.length())} at scan time. Without - * up-front validation, malformed offsets/lengths surface as {@code IndexOutOfBoundsException} - * from the FFM layer rather than {@link VortexException}, breaking the reader contract. + *

Every [SegmentSpec] declared in the footer is later sliced from the memory-mapped + * file via `fileSegment.asSlice(spec.offset(), spec.length())` at scan time. Without + * up-front validation, malformed offsets/lengths surface as `IndexOutOfBoundsException` + * from the FFM layer rather than [VortexException], breaking the reader contract. * - *

{@link PostscriptParser#validateSegmentSpecs} now rejects negative offsets, negative - * lengths, offsets past end-of-file, and {@code offset + length} overflowing the file size at + *

[PostscriptParser#validateSegmentSpecs] now rejects negative offsets, negative + * lengths, offsets past end-of-file, and `offset + length` overflowing the file size at * the moment the postscript is parsed — before any scan iterator is ever created. */ class MalformedFooterSecurityTest { @@ -76,10 +76,10 @@ void footerSegmentSpec_outOfBounds_throwsVortexException( /** * Crafts a minimal .vtx file with a single I64 flat-layout column and a footer whose - * {@code segmentSpecs[0]} contains the supplied (deliberately bad) offset/length. + * `segmentSpecs[0]` contains the supplied (deliberately bad) offset/length. * *

The file body is 8 bytes of placeholder data: the bad spec means - * {@code VortexReader.open} should never look at them. + * `VortexReader.open` should never look at them. */ private static Path buildFileWithBadSegmentSpec(Path dir, long segOffset, long segLength) throws Exception { byte[] body = new byte[8]; // unused; placeholder data segment diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/MalformedTrailerSecurityTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/MalformedTrailerSecurityTest.java index 21f17339..9f7f9128 100644 --- a/reader/src/test/java/io/github/dfa1/vortex/reader/MalformedTrailerSecurityTest.java +++ b/reader/src/test/java/io/github/dfa1/vortex/reader/MalformedTrailerSecurityTest.java @@ -18,8 +18,8 @@ * Adversarial tests for the 8-byte file trailer and postscript length field. * *

The trailer is the entry point for every Vortex file read; any malformed input here - * must surface as a {@link VortexException}, never as an unchecked JDK exception - * ({@code IndexOutOfBoundsException}, {@code NegativeArraySizeException}, {@code OutOfMemoryError}), + * must surface as a [VortexException], never as an unchecked JDK exception + * (`IndexOutOfBoundsException`, `NegativeArraySizeException`, `OutOfMemoryError`), * a FlatBuffer runtime exception, or a Protobuf parser exception. * *

Trailer layout (LE): @@ -82,8 +82,8 @@ void truncatedMagic_throwsVortexException(@TempDir Path tmp) throws Exception { /** * postscriptLen larger than the file body would make postscriptOffset go negative, - * which previously surfaced as {@code IndexOutOfBoundsException} from - * {@code MemorySegment.asSlice(negative, ...)}. + * which previously surfaced as `IndexOutOfBoundsException` from + * `MemorySegment.asSlice(negative, ...)`. */ @Test void postscriptLenPastFileStart_throwsVortexException(@TempDir Path tmp) throws Exception { @@ -104,7 +104,7 @@ void postscriptLenPastFileStart_throwsVortexException(@TempDir Path tmp) throws /** * postscriptLen == 0 leaves no bytes to FlatBuffer-parse; without validation, the empty - * buffer would either throw {@code ArrayIndexOutOfBoundsException} from the FlatBuffer + * buffer would either throw `ArrayIndexOutOfBoundsException` from the FlatBuffer * runtime or silently parse against a missing root table. */ @Test @@ -124,7 +124,7 @@ void postscriptLenZero_throwsVortexException(@TempDir Path tmp) throws Exception } /** - * Unknown version must surface as a {@link VortexException} rather than silently + * Unknown version must surface as a [VortexException] rather than silently * parsing against an unknown layout. */ @Test @@ -145,7 +145,7 @@ void unknownVersion_throwsVortexException(@TempDir Path tmp) throws Exception { /** * Garbage where the postscript FlatBuffer is expected must surface as a - * {@link VortexException}, not a raw FlatBuffer runtime exception. + * [VortexException], not a raw FlatBuffer runtime exception. */ @Test void garbagePostscriptBytes_throwsVortexException(@TempDir Path tmp) throws Exception { diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/ZipBombSecurityTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/ZipBombSecurityTest.java index 4bb59acb..1ca5967d 100644 --- a/reader/src/test/java/io/github/dfa1/vortex/reader/ZipBombSecurityTest.java +++ b/reader/src/test/java/io/github/dfa1/vortex/reader/ZipBombSecurityTest.java @@ -33,12 +33,12 @@ /** * Regression tests for zip-bomb style attacks against VortexReader. * - *

Root cause: the format trusts {@code row_count} in the layout FlatBuffer without + *

Root cause: the format trusts `row_count` in the layout FlatBuffer without * validating it against actual segment byte sizes. A ~150-byte file can claim 10⁹ rows - * and trigger an 8 GB allocation on the first {@code iter.hasNext()} call. + * and trigger an 8 GB allocation on the first `iter.hasNext()` call. * *

Both attacks are fixed: tests use small row counts safe for CI and assert the - * expected post-fix behavior (no OOM; either completes or throws {@link io.github.dfa1.vortex.core.VortexException}). + * expected post-fix behavior (no OOM; either completes or throws [io.github.dfa1.vortex.core.VortexException]). */ class ZipBombSecurityTest { @@ -172,9 +172,9 @@ private static Path buildDictBomb(Path dir, long claimedRows) throws Exception { // ── FlatBuffer segment builders ─────────────────────────────────────────── /** - * Builds: {@code [rawData][Array FlatBuffer (1 buffer)][4-byte LE fbLen]}. + * Builds: `[rawData][Array FlatBuffer (1 buffer)][4-byte LE fbLen]`. * - *

The Array FlatBuffer describes one buffer at offset 0 with length {@code rawData.length}. + *

The Array FlatBuffer describes one buffer at offset 0 with length `rawData.length`. * Buffer index 0 in the ArrayNode refers to this buffer. */ private static byte[] buildOneBufferSegment(byte[] rawData) { @@ -253,7 +253,7 @@ private static ByteBuffer buildI64Dtype() { return slice(fbb); } - /** Flat layout: {@code vortex.flat} at layoutSpecs[layoutSpecIdx], pointing to segmentSpecs[segIdx]. */ + /** Flat layout: `vortex.flat` at layoutSpecs[layoutSpecIdx], pointing to segmentSpecs[segIdx]. */ private static ByteBuffer buildFlatLayout(int layoutSpecIdx, long rowCount, int segIdx) { var fbb = new FlatBufferBuilder(128); int segV = Layout.createSegmentsVector(fbb, new long[]{segIdx}); @@ -270,8 +270,8 @@ private static ByteBuffer buildFlatLayout(int layoutSpecIdx, long rowCount, int * child[1] = flat(enc=0, rowCount=claimedRows, seg=1) ← codes (INFLATED) * } * - * {@code decodeDictLayout} reads {@code n = codesLayout.rowCount() = claimedRows} - * then calls {@code expandDictPrimitive(..., n, arena)} which allocates {@code n * elemBytes}. + * `decodeDictLayout` reads `n = codesLayout.rowCount() = claimedRows` + * then calls `expandDictPrimitive(..., n, arena)` which allocates `n * elemBytes`. */ private static ByteBuffer buildDictLayout(long claimedRows) { var fbb = new FlatBufferBuilder(256); diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/WriteRegistry.java b/writer/src/main/java/io/github/dfa1/vortex/writer/WriteRegistry.java index 5463a253..c47066e4 100644 --- a/writer/src/main/java/io/github/dfa1/vortex/writer/WriteRegistry.java +++ b/writer/src/main/java/io/github/dfa1/vortex/writer/WriteRegistry.java @@ -12,8 +12,8 @@ /// Write-side registry: maps [EncodingId] to [EncodingEncoder] implementations, /// and [ExtensionId] to [ExtensionEncoder] implementations. /// -/// Instances are immutable after construction. Build one via {@link #builder()} or via the -/// {@link #loadAll()} and {@link #empty()} convenience factories. +/// Instances are immutable after construction. Build one via [#builder()] or via the +/// [#loadAll()] and [#empty()] convenience factories. /// /// Usage: /// ```java diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java index b87cea42..44d33beb 100644 --- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java +++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java @@ -25,7 +25,7 @@ public final class AlpEncodingEncoder implements EncodingEncoder { private static final int MAX_EXPONENT_F64 = 18; private static final int MAX_EXPONENT_F32 = 10; // Wider than Rust's SAMPLE_SIZE=32: at small samples, IEEE precision drift at high - // {@code (expE, expF)} can hide as a 0-patch tie in the size estimate, then explode into + // `(expE, expF)` can hide as a 0-patch tie in the size estimate, then explode into // thousands of patches when the full chunk is encoded. A larger sample is more likely to // include drift-triggering values, letting the search penalise such combinations correctly. private static final int SAMPLE_SIZE = 512; @@ -90,7 +90,7 @@ private static int[] findExponentsF64(double[] values) { // Iterate e ascending and f ascending so the first-encountered minimum has the smallest // e (and smallest e-f for that e). With strict less-than replacement, ties resolve to - // the smaller exponent — important because IEEE precision of {@code F10[f] * IF10[e]} + // the smaller exponent — important because IEEE precision of `F10[f] * IF10[e]` // tends to drift at high (e, f), and Rust's sample-of-32 sometimes detects this drift // as exceptions while ours does not (sample bias). Preferring smaller e protects us. for (int expE = 1; expE < MAX_EXPONENT_F64; expE++) { diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadeStep.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadeStep.java index 7b43644d..f6648fba 100644 --- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadeStep.java +++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadeStep.java @@ -13,7 +13,7 @@ /// child `bufferIndices` are remapped by `+ownedBuffers.size()`. /// /// When `applicable` is false the encoding cannot handle this data; [#ownedBytes()] -/// returns {@link Long#MAX_VALUE}/2 so the step never wins in size-based selection. +/// returns [Long#MAX_VALUE]/2 so the step never wins in size-based selection. /// /// @param partialRoot partially-assembled root encode node (may be `null` when not applicable) /// @param ownedBuffers buffers owned directly by the root node, before child buffers are appended diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeContext.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeContext.java index aba649aa..b9f0adbc 100644 --- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeContext.java +++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeContext.java @@ -13,16 +13,16 @@ /// Encoding context passed to every [EncodingEncoder#encode] and /// [EncodingEncoder#encodeCascade] call. /// -/// Carries a caller-scoped {@link Arena} for encode output buffers, a -/// {@link WriteRegistry} for cross-encoder delegation and extension lookup, +/// Carries a caller-scoped [Arena] for encode output buffers, a +/// [WriteRegistry] for cross-encoder delegation and extension lookup, /// and cascading compression parameters (depth, exclusions, sampling) used by the -/// {@link CascadingCompressor}. +/// [CascadingCompressor]. /// -/// In non-cascading paths, use {@link #of(Arena, WriteRegistry)} — cascade parameters +/// In non-cascading paths, use [#of(Arena, WriteRegistry)] — cascade parameters /// default to depth 0 with no exclusions. -/// In cascading paths, use {@link #ofDepth(int, Arena, WriteRegistry)} and let -/// {@link CascadingCompressor} derive child contexts via {@link #withDecrementedDepth()} -/// and {@link #withExcluded(EncodingId)}. +/// In cascading paths, use [#ofDepth(int, Arena, WriteRegistry)] and let +/// [CascadingCompressor] derive child contexts via [#withDecrementedDepth()] +/// and [#withExcluded(EncodingId)]. /// /// @param arena the arena to allocate encode output buffers from /// @param registry write registry supplying encoder and extension lookup diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/EncodeTestHelper.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/EncodeTestHelper.java index 34bd53cb..1140fa3f 100644 --- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/EncodeTestHelper.java +++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/EncodeTestHelper.java @@ -15,7 +15,7 @@ private EncodeTestHelper() { /// Creates a non-cascading [EncodeContext] using a GC-managed arena and all /// service-loaded [EncodingEncoder]s. /// - /// @return a test-suitable {@link EncodeContext} + /// @return a test-suitable [EncodeContext] public static EncodeContext testCtx() { return EncodeContext.of(Arena.ofAuto(), WriteRegistry.loadAll()); }