style: migrate Javadoc HTML tags → Markdown (S7474)

Replace <p>, <ul>/<li>, <strong>, <pre> and <table> HTML
tags across 38 files with Markdown equivalents (blank lines,
- lists, **bold**, ```java blocks, | tables).

Add RegexpSingleline checkstyle rule to ban HTML block tags
in /// Markdown Javadoc going forward; document convention
in CLAUDE.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: dfa1

CLAUDE.md

@@ -290,6 +290,10 @@ arrives that cannot be addressed by choosing a different encoding for a flat seg
 
 - indents are 4 spaces, enforced by checkstyle
 - Zero SonarQube bugs/smells policy.
+- **Javadoc style:** all `///` Markdown Javadoc — no HTML tags. Use Markdown syntax:
+  blank `///` line for paragraph break, `- item` for lists, ` ```java ``` ` for code
+  blocks, `**text**` for bold. Checkstyle enforces this (`RegexpSingleline` rule in
+  `checkstyle.xml` blocks `<p>`, `<ul>`, `<li>`, `<strong>`, `<pre>`, `<table>`, etc.).
 - No `sun.misc.Unsafe` or internal JDK APIs.
 - Prefer explicit over clever. Fail fast on unhandled cases.
 - Always prefer idiomatic modern Java. Reuse the standard library and language

checkstyle.xml

@@ -16,6 +16,16 @@
         <property name="message" value="Line has trailing spaces."/>
     </module>
 
+    <!-- Ban HTML block/structure tags in /// Markdown Javadoc.
+         Use Markdown syntax instead: blank lines for paragraphs, - for lists,
+         ``` for code blocks, **text** for bold. -->
+    <module name="RegexpSingleline">
+        <property name="format" value="^\s*///.*&lt;(p|ul|/ul|li|/li|pre|/pre|strong|/strong|table|/table|tr|/tr|th|/th|td|/td)(\s|&gt;|/)"/>
+        <property name="minimum" value="0"/>
+        <property name="maximum" value="0"/>
+        <property name="message" value="HTML tags forbidden in Markdown Javadoc (///). Use Markdown: blank line for paragraph, - for list, ``` for code, **text** for bold."/>
+    </module>
+
     <module name="SuppressionSingleFilter">
         <property name="files" value="[\\/](fbs|proto)[\\/]"/>
     </module>

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

@@ -59,7 +59,7 @@ public boolean isSigned() {
     /// Returns the {@link PType} for the given enum ordinal — the integer value the wire format
     /// uses to identify a physical type.
     ///
-    /// <p>Unlike {@code PType.values()[ordinal]}, this method validates the ordinal against the
+    /// Unlike {@code PType.values()[ordinal]}, this method validates the ordinal against the
     /// declared range and throws {@link VortexException} for crafted out-of-range values rather
     /// than the JDK's {@link ArrayIndexOutOfBoundsException}. Use this at every decode site that
     /// reads a ptype from untrusted metadata.

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

@@ -6,12 +6,12 @@
 
 /// Unrecoverable Vortex error: malformed file, unsupported feature, or encoding failure.
 ///
-/// <p><strong>Non-recoverable contract:</strong> once thrown, the underlying file or stream is
+/// **Non-recoverable contract:** once thrown, the underlying file or stream is
 /// in an indeterminate state. Callers must propagate this exception — do not catch-and-swallow,
 /// do not retry on the same input. The correct response is to abort the read, surface the error,
 /// and close the {@code VortexFile}.
 ///
-/// <p>Carries an optional {@link EncodingId} for diagnostic attribution; it is not intended
+/// Carries an optional {@link EncodingId} for diagnostic attribution; it is not intended
 /// for recovery logic.
 public final class VortexException extends RuntimeException {
 

inspector/src/main/java/io/github/dfa1/vortex/inspect/ZonedStatsSchema.java

@@ -10,25 +10,23 @@
 /// Reconstructs the per-zone statistics-table {@link DType} for a
 /// {@code vortex.stats} (Zoned) layout.
 ///
-/// <p>The shape is sourced from the Rust reference implementation:
-/// <ul>
-///   <li>Metadata format
+/// The shape is sourced from the Rust reference implementation:
+/// - Metadata format
 ///       (<a href="https://github.com/spiraldb/vortex/blob/develop/vortex-layout/src/layouts/zoned/mod.rs">
 ///       vortex-layout/src/layouts/zoned/mod.rs</a> — {@code ZonedMetadata}):
 ///       bytes [0..4) are the zone length as a little-endian {@code u32};
 ///       remaining bytes form a {@code Stat} bitset (LSB-first per byte). Each
 ///       set bit at index {@code i} indicates that the {@link Stat} with that
-///       ordinal is present in the auxiliary stats table.</li>
-///   <li>Schema construction
+///       ordinal is present in the auxiliary stats table.
+/// - Schema construction
 ///       (<a href="https://github.com/spiraldb/vortex/blob/develop/vortex-layout/src/layouts/zoned/schema.rs">
 ///       vortex-layout/src/layouts/zoned/schema.rs</a> — {@code stats_table_dtype}):
 ///       for each present stat in ordinal order, append a struct field with the
 ///       stat's name and the stat's nullable dtype. {@code Max} and {@code Min}
 ///       each get an extra trailing field {@code max_is_truncated} /
-///       {@code min_is_truncated} of type {@code Bool} (non-nullable).</li>
-/// </ul>
+///       {@code min_is_truncated} of type {@code Bool} (non-nullable).
 ///
-/// <p>{@code Sum} widening rules and Decimal handling are not yet implemented —
+/// {@code Sum} widening rules and Decimal handling are not yet implemented —
 /// when the column dtype has no resolvable stat dtype the stat is skipped so
 /// the inspector degrades to "no schema" rather than failing.
 public final class ZonedStatsSchema {
@@ -92,7 +90,7 @@ public static long zoneLength(ByteBuffer metadata) {
 
     /// Returns the stats present in the layout metadata bitset, in ordinal order.
     ///
-    /// <p>Unknown bits (set at an index past {@link Stat#values()}'s length, which
+    /// Unknown bits (set at an index past {@link Stat#values()}'s length, which
     /// would mean a newer Vortex writer) are silently skipped — matching the Rust
     /// reader's forward-compatibility behaviour.
     ///
@@ -122,12 +120,12 @@ public static List<Stat> presentStats(ByteBuffer metadata) {
     /// Reconstructs the per-zone stats-table dtype for the given column dtype
     /// and metadata.
     ///
-    /// <p>The result is a {@link io.github.dfa1.vortex.core.DType.Struct} mirroring
+    /// The result is a {@link io.github.dfa1.vortex.core.DType.Struct} mirroring
     /// the order produced by Rust's {@code stats_table_dtype}: for every present stat
     /// in ordinal order, append a {@code (name, nullable dtype)} field; Max/Min each
     /// add a trailing {@code _is_truncated} Bool (non-nullable) flag.
     ///
-    /// <p>If a stat has no resolvable dtype for the given column (e.g. {@code Sum}
+    /// If a stat has no resolvable dtype for the given column (e.g. {@code Sum}
     /// over an extension type without storage), it is omitted from the struct.
     ///
     /// @param columnDtype the column's logical dtype (the {@code data} child's dtype)
@@ -168,21 +166,19 @@ public static DType.Struct statsTableDtype(DType columnDtype, List<Stat> present
     /// dtype, or {@code null} if the stat has no defined dtype for that column
     /// (in which case it is dropped from the stats table).
     ///
-    /// <p>Mirrors Rust's {@code Stat::dtype(&DType)} plus the aggregate-function
+    /// Mirrors Rust's {@code Stat::dtype(&DType)} plus the aggregate-function
     /// return-type rules (see
     /// <a href="https://github.com/spiraldb/vortex/blob/develop/vortex-array/src/aggregate_fn/fns">
     /// vortex-array/src/aggregate_fn/fns</a>):
-    /// <ul>
-    ///   <li>min/max → same dtype as column (except DType.Null → null);</li>
-    ///   <li>is_constant/is_sorted/is_strict_sorted → non-nullable Bool;</li>
-    ///   <li>null_count → non-nullable U64;</li>
-    ///   <li>uncompressed_size_in_bytes → non-nullable U64;</li>
-    ///   <li>nan_count → non-nullable U64 (only for float columns);</li>
-    ///   <li>sum → nullable U64 / I64 / F64 depending on column ptype; null for
-    ///       unsupported column dtypes.</li>
-    /// </ul>
+    /// - min/max → same dtype as column (except DType.Null → null);
+    /// - is_constant/is_sorted/is_strict_sorted → non-nullable Bool;
+    /// - null_count → non-nullable U64;
+    /// - uncompressed_size_in_bytes → non-nullable U64;
+    /// - nan_count → non-nullable U64 (only for float columns);
+    /// - sum → nullable U64 / I64 / F64 depending on column ptype; null for
+    ///       unsupported column dtypes.
     ///
-    /// <p>For Extension column dtypes, the storage dtype is consulted as a backward-compat
+    /// For Extension column dtypes, the storage dtype is consulted as a backward-compat
     /// fallback (matching the {@code or_else} branch in Rust's
     /// {@code stats_table_dtype}).
     ///

parquet/src/main/java/io/github/dfa1/vortex/parquet/ParquetImporter.java

@@ -33,14 +33,12 @@
 /// 0 for numeric types, {@code false} for bool, {@code ""} for strings.
 ///
 /// Supported Parquet physical types:
-/// <ul>
-///   <li>BOOLEAN → Bool</li>
-///   <li>INT32 (no annotation / IntType 8/16/32, signed or unsigned) → I8/U8/I16/U16/I32/U32</li>
-///   <li>INT64 (no annotation / IntType 64, signed or unsigned) → I64/U64</li>
-///   <li>FLOAT → F32</li>
-///   <li>DOUBLE → F64</li>
-///   <li>BYTE_ARRAY annotated STRING, ENUM, or JSON → Utf8</li>
-/// </ul>
+/// - BOOLEAN → Bool
+/// - INT32 (no annotation / IntType 8/16/32, signed or unsigned) → I8/U8/I16/U16/I32/U32
+/// - INT64 (no annotation / IntType 64, signed or unsigned) → I64/U64
+/// - FLOAT → F32
+/// - DOUBLE → F64
+/// - BYTE_ARRAY annotated STRING, ENUM, or JSON → Utf8
 ///
 /// All other physical types (INT96, FIXED_LEN_BYTE_ARRAY, unannotated BYTE_ARRAY, DECIMAL,
 /// DATE, TIME, TIMESTAMP) throw {@link UnsupportedOperationException}.

performance/src/main/java/io/github/dfa1/vortex/performance/RustWritesJavaReadsBigFileBenchmark.java

@@ -50,16 +50,16 @@
 /// Big-file scan benchmark for files exceeding 2 GB ({@link io.github.dfa1.vortex.reader.SegmentSpec#length()}
 /// is {@code long}, so segments up to 4 GB are supported).
 ///
-/// <p>Setup: JNI writer produces a >2 GB Vortex file with 4 incompressible I64 columns
+/// Setup: JNI writer produces a >2 GB Vortex file with 4 incompressible I64 columns
 /// (random longs defeat bit-packing / FoR so the segments stay large). Measurement: pure-Java
 /// `VortexReader` scans every column and sums the first column.
 ///
-/// <p>The trial setup writes ~3 GB to disk and takes tens of seconds, so this benchmark is
+/// The trial setup writes ~3 GB to disk and takes tens of seconds, so this benchmark is
 /// intended for occasional runs (e.g. before tagging a release). To skip the JNI write, pass
 /// {@code -Dvortex.bench.bigfile=/path/to/existing.vtx} — useful when iterating on the read
 /// path against the same fixture.
 ///
-/// <p>Run: {@code java -jar performance/target/benchmarks.jar RustWritesJavaReadsBigFileBenchmark.javaScan}
+/// Run: {@code java -jar performance/target/benchmarks.jar RustWritesJavaReadsBigFileBenchmark.javaScan}
 @State(Scope.Benchmark)
 @BenchmarkMode(Mode.Throughput)
 @OutputTimeUnit(TimeUnit.SECONDS)

reader/src/main/java/io/github/dfa1/vortex/reader/ExtensionDecoder.java

@@ -5,7 +5,7 @@
 
 /// Read-side contract for a Vortex extension type.
 ///
-/// <p>Implementations pair a spec identity ({@link ExtensionId}) with the matching
+/// Implementations pair a spec identity ({@link ExtensionId}) with the matching
 /// {@link DType.Extension} dtype. Typed decode methods live on each concrete
 /// implementation — they are not on this interface, so read callers get typed return
 /// values without casting through {@code Object}.

reader/src/main/java/io/github/dfa1/vortex/reader/FlatSegmentDecoder.java

@@ -18,10 +18,10 @@
 /// Parses a flat segment from the memory-mapped file region and dispatches to the
 /// appropriate decoder via the {@link ReadRegistry}.
 ///
-/// <p>Flat segment wire format:
+/// Flat segment wire format:
 /// {@code buffer_data... | FlatBuffer(Array) | u32 LE = FlatBuffer byte length}
 ///
-/// <p>{@link ReadRegistry} is pure dispatch; this class owns all file-format knowledge:
+/// {@link ReadRegistry} is pure dispatch; this class owns all file-format knowledge:
 /// FlatBuffer parsing, buffer-offset arithmetic, and encoding-spec lookup.
 public final class FlatSegmentDecoder {
 

reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java

@@ -18,7 +18,7 @@
 
 /// Read-side registry: maps {@link EncodingId} to {@link EncodingDecoder} implementations.
 ///
-/// <p>Instances are immutable after construction. Build one via {@link #builder()} or
+/// Instances are immutable after construction. Build one via {@link #builder()} or
 /// via the {@link #loadAll()} and {@link #empty()} convenience factories.
 public final class ReadRegistry {
 
@@ -169,7 +169,7 @@ public Builder registerServiceLoaded() {
 
         /// Enable passthrough decode for unknown encoding ids.
         ///
-        /// <p>Default is strict: unknown ids throw {@link VortexException}. When enabled, unknown
+        /// Default is strict: unknown ids throw {@link VortexException}. When enabled, unknown
         /// nodes are wrapped as {@link io.github.dfa1.vortex.reader.array.UnknownArray}.
         /// Mirrors Rust {@code VortexSession::allow_unknown()}.
         ///