docs: complete Javadoc for core public API and add jdbc module

Zero javadoc warnings on `./mvnw javadoc:javadoc -pl core`.
Excludes generated fbs/proto packages from javadoc checks.
Adds jdbc module with JdbcImporter, JdbcImportOptions,
ProgressListener, and SqlTypeToDType (6 unit tests, all green).

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

Author: dfa1

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

@@ -6,6 +6,13 @@
 import java.nio.ByteBuffer;
 
 /// Per-array statistics embedded in the encoding tree.
+///
+/// @param min            minimum value in the array, or {@code null} if unknown
+/// @param max            maximum value in the array, or {@code null} if unknown
+/// @param trueCount      number of {@code true} values for bool columns, or {@code null} if unknown
+/// @param nullCount      number of null values, or {@code null} if unknown
+/// @param isSorted       {@code true} if the array is sorted in ascending order, or {@code null} if unknown
+/// @param isStrictSorted {@code true} if the array is strictly sorted (no duplicates), or {@code null} if unknown
 public record ArrayStats(
 		Object min,
 		Object max,
@@ -16,10 +23,18 @@ public record ArrayStats(
 ) {
 	private static final ArrayStats EMPTY = new ArrayStats(null, null, null, null, null, null);
 
+	/// Returns an empty stats instance with all fields set to {@code null}.
+	///
+	/// @return an empty {@link ArrayStats} with no known statistics
 	public static ArrayStats empty() {
 		return EMPTY;
 	}
 
+	/// Parses stats from a FlatBuffers {@link io.github.dfa1.vortex.fbs.ArrayStats} table.
+	/// Returns an empty instance when {@code fbs} is {@code null} or carries no min/max.
+	///
+	/// @param fbs the FlatBuffers stats table, or {@code null}
+	/// @return parsed stats, or an empty instance if no usable data is present
 	public static ArrayStats fromFbs(io.github.dfa1.vortex.fbs.ArrayStats fbs) {
 		if (fbs == null) {
 			return EMPTY;

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

@@ -1,14 +1,28 @@
 package io.github.dfa1.vortex.core;
 
+/// Block-level compression scheme applied to flat segments in the Vortex file format.
 public enum CompressionScheme {
-	NONE(0), LZ4(1), ZLIB(2), ZSTD(3);
+	/// No compression.
+	NONE(0),
+	/// LZ4 block compression.
+	LZ4(1),
+	/// Zlib deflate compression.
+	ZLIB(2),
+	/// Zstandard compression.
+	ZSTD(3);
 
+	/// Numeric code as stored in the file postscript.
 	public final int code;
 
 	CompressionScheme(int code) {
 		this.code = code;
 	}
 
+	/// Returns the enum constant matching the given numeric code.
+	///
+	/// @param code numeric compression code from the file postscript
+	/// @return the matching {@link CompressionScheme}
+	/// @throws IllegalArgumentException if {@code code} does not correspond to any known scheme
 	public static CompressionScheme of(int code) {
 		return switch (code) {
 			case 0 -> NONE;

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

@@ -17,31 +17,65 @@ public sealed interface DType
 		DType.Utf8, DType.Binary, DType.Struct,
 		DType.List, DType.FixedSizeList, DType.Extension {
 
+	/// Returns whether this type allows null values.
+	///
+	/// @return {@code true} if null values are permitted
 	boolean nullable();
 
+	/// The SQL {@code NULL} type — no values, always nullable.
+	///
+	/// @param nullable whether null values are permitted
 	record Null(boolean nullable) implements DType {
 	}
 
+	/// Boolean logical type.
+	///
+	/// @param nullable whether null values are permitted
 	record Bool(boolean nullable) implements DType {
 	}
 
+	/// Primitive numeric logical type backed by a physical {@link PType}.
+	///
+	/// @param ptype    physical primitive type (e.g. I32, F64)
+	/// @param nullable whether null values are permitted
 	record Primitive(PType ptype, boolean nullable) implements DType {
 	}
 
+	/// Fixed-precision decimal logical type.
+	///
+	/// @param precision total number of significant decimal digits
+	/// @param scale     number of digits to the right of the decimal point
+	/// @param nullable  whether null values are permitted
 	record Decimal(byte precision, byte scale, boolean nullable) implements DType {
 	}
 
+	/// Variable-length UTF-8 string logical type.
+	///
+	/// @param nullable whether null values are permitted
 	record Utf8(boolean nullable) implements DType {
 	}
 
+	/// Variable-length binary (byte string) logical type.
+	///
+	/// @param nullable whether null values are permitted
 	record Binary(boolean nullable) implements DType {
 	}
 
+	/// Struct logical type with named, typed fields.
+	///
+	/// @param fieldNames ordered list of field names
+	/// @param fieldTypes ordered list of field types, parallel to {@code fieldNames}
+	/// @param nullable   whether null values are permitted
 	record Struct(
 			java.util.List<String> fieldNames,
 			java.util.List<DType> fieldTypes,
 			boolean nullable
 	) implements DType {
+		/// Returns the type of the field with the given name.
+		///
+		/// @param name the field name to look up
+		/// @return the {@link DType} of the named field
+		/// @throws IllegalArgumentException if no field with that name exists
 		public DType field(String name) {
 			int i = fieldNames.indexOf(name);
 			if (i < 0) {
@@ -51,12 +85,27 @@ public DType field(String name) {
 		}
 	}
 
+	/// Variable-length list logical type.
+	///
+	/// @param elementType logical type of each list element
+	/// @param nullable    whether null values are permitted
 	record List(DType elementType, boolean nullable) implements DType {
 	}
 
+	/// Fixed-size list logical type where every list has the same length.
+	///
+	/// @param elementType logical type of each list element
+	/// @param fixedSize   number of elements in every list
+	/// @param nullable    whether null values are permitted
 	record FixedSizeList(DType elementType, int fixedSize, boolean nullable) implements DType {
 	}
 
+	/// Extension logical type with user-defined semantics layered over a storage type.
+	///
+	/// @param extensionId  unique string identifier for the extension type (e.g. {@code "vortex.timestamp"})
+	/// @param storageDType underlying storage dtype used for physical encoding
+	/// @param metadata     opaque extension-specific metadata bytes, or {@code null}
+	/// @param nullable     whether null values are permitted
 	record Extension(
 			String extensionId,
 			DType storageDType,
@@ -65,6 +114,10 @@ record Extension(
 	) implements DType {
 	}
 
+	/// Returns a copy of this type with the given nullability.
+	///
+	/// @param nullable the desired nullability for the returned type
+	/// @return a new {@link DType} identical to this one except for its nullability
 	default DType withNullable(boolean nullable) {
 		return switch (this) {
 			case Null _ -> new Null(nullable);

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

@@ -6,6 +6,11 @@
 ///
 /// All spec lists are index-stable: array/layout/segment indices in the tree refer
 /// into these lists by position.
+///
+/// @param arraySpecs       encoding id strings indexed by array spec index
+/// @param layoutSpecs      layout type strings indexed by layout spec index
+/// @param segmentSpecs     segment byte ranges indexed by segment index
+/// @param compressionSpecs compression schemes indexed by compression spec index
 public record Footer(
 		List<String> arraySpecs,
 		List<String> layoutSpecs,

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

@@ -9,35 +9,61 @@
 /// ```
 /// Struct → Zoned(Stats) → Chunked → [Flat, Flat, ...]
 /// ```
+///
+/// @param encodingId encoding id string (e.g. {@code "vortex.flat"})
+/// @param rowCount   number of logical rows covered by this node
+/// @param metadata   optional encoding-specific metadata bytes, or {@code null}
+/// @param children   child layout nodes (empty for leaf nodes)
+/// @param segments   indices into the file's segment table for buffers owned by this node
 public record Layout(
 		String encodingId,
 		long rowCount,
 		ByteBuffer metadata,
 		List<Layout> children,
 		List<Integer> segments
 ) {
+	/// Encoding id for flat (leaf) layouts ({@code "vortex.flat"}).
 	public static final String FLAT = "vortex.flat";
+	/// Encoding id for chunked layouts ({@code "vortex.chunked"}).
 	public static final String CHUNKED = "vortex.chunked";
+	/// Encoding id for struct layouts ({@code "vortex.struct"}).
 	public static final String STRUCT = "vortex.struct";
+	/// Encoding id for zone-map layouts ({@code "vortex.stats"}).
 	public static final String ZONED = "vortex.stats";
+	/// Encoding id for dictionary layouts ({@code "vortex.dict"}).
 	public static final String DICT = "vortex.dict";
 
+	/// Returns {@code true} if this layout is a flat (leaf) layout.
+	///
+	/// @return {@code true} when {@code encodingId} equals {@link #FLAT}
 	public boolean isFlat() {
 		return FLAT.equals(encodingId);
 	}
 
+	/// Returns {@code true} if this layout is a chunked layout.
+	///
+	/// @return {@code true} when {@code encodingId} equals {@link #CHUNKED}
 	public boolean isChunked() {
 		return CHUNKED.equals(encodingId);
 	}
 
+	/// Returns {@code true} if this layout is a struct layout.
+	///
+	/// @return {@code true} when {@code encodingId} equals {@link #STRUCT}
 	public boolean isStruct() {
 		return STRUCT.equals(encodingId);
 	}
 
+	/// Returns {@code true} if this layout is a zone-map (stats) layout.
+	///
+	/// @return {@code true} when {@code encodingId} equals {@link #ZONED}
 	public boolean isZoned() {
 		return ZONED.equals(encodingId);
 	}
 
+	/// Returns {@code true} if this layout is a dictionary layout.
+	///
+	/// @return {@code true} when {@code encodingId} equals {@link #DICT}
 	public boolean isDict() {
 		return DICT.equals(encodingId);
 	}

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

@@ -30,6 +30,8 @@ public enum PType {
 	F64;
 
 	/// Number of bytes per element on the wire (1, 2, 4, or 8).
+	///
+	/// @return the byte size of this physical type
 	public int byteSize() {
 		return switch (this) {
 			case U8, I8 -> 1;
@@ -40,11 +42,15 @@ public int byteSize() {
 	}
 
 	/// Returns {@code true} for {@code F16}, {@code F32}, and {@code F64}.
+	///
+	/// @return {@code true} if this ptype is a floating-point type
 	public boolean isFloating() {
 		return this == F16 || this == F32 || this == F64;
 	}
 
 	/// Returns {@code true} for signed integers ({@code I8}–{@code I64}) and all floating-point types.
+	///
+	/// @return {@code true} if this ptype is signed
 	public boolean isSigned() {
 		return this == I8 || this == I16 || this == I32 || this == I64
 				|| this == F16 || this == F32 || this == F64;

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

@@ -5,6 +5,11 @@
 /// {@code length} is {@code long} because the wire format encodes it as
 /// {@code uint32} (up to 4 GB per segment). Storing it as a Java {@code int}
 /// silently truncates segments larger than 2 GB into negative values.
+///
+/// @param offset             byte offset from the start of the file
+/// @param length             byte length of the segment (unsigned, stored as {@code long})
+/// @param alignmentExponent  log2 of the required byte alignment; 0 means no alignment constraint
+/// @param compression        compression scheme applied to this segment's bytes
 public record SegmentSpec(
 		long offset,
 		long length,

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

@@ -15,28 +15,48 @@
 /// for recovery logic.
 public final class VortexException extends RuntimeException {
 
+	/// The encoding that raised this exception, or {@code null} if not attributed to a specific encoding.
 	private final EncodingId encodingId;
 
+	/// Creates a {@code VortexException} with the given message and no associated encoding.
+	///
+	/// @param message human-readable error description
 	public VortexException(String message) {
 		super(message);
 		this.encodingId = null;
 	}
 
+	/// Creates a {@code VortexException} with the given message and cause, and no associated encoding.
+	///
+	/// @param message human-readable error description
+	/// @param cause   the underlying cause
 	public VortexException(String message, Throwable cause) {
 		super(message, cause);
 		this.encodingId = null;
 	}
 
+	/// Creates a {@code VortexException} attributed to the given encoding.
+	///
+	/// @param encodingId encoding responsible for this error
+	/// @param message    human-readable error description (prefixed with the encoding id)
 	public VortexException(EncodingId encodingId, String message) {
 		super(prefix(encodingId) + message);
 		this.encodingId = encodingId;
 	}
 
+	/// Creates a {@code VortexException} attributed to the given encoding, with a cause.
+	///
+	/// @param encodingId encoding responsible for this error
+	/// @param message    human-readable error description (prefixed with the encoding id)
+	/// @param cause      the underlying cause
 	public VortexException(EncodingId encodingId, String message, Throwable cause) {
 		super(prefix(encodingId) + message, cause);
 		this.encodingId = encodingId;
 	}
 
+	/// Returns the encoding that raised this exception, if known.
+	///
+	/// @return an {@link Optional} containing the {@link EncodingId}, or empty if not attributed
 	public Optional<EncodingId> encodingId() {
 		return Optional.ofNullable(encodingId);
 	}

core/src/main/java/io/github/dfa1/vortex/core/array/Array.java

@@ -15,16 +15,28 @@ public sealed interface Array
                 FloatArray, GenericArray, IntArray, ListArray, ListViewArray, LongArray,
                 MaskedArray, NullArray, ShortArray, StructArray, UnknownArray, VarBinArray {
 
+	/// Returns the number of elements in this array.
+	///
+	/// @return element count
 	long length();
 
+	/// Returns the logical type of elements in this array.
+	///
+	/// @return dtype
 	DType dtype();
 
-	/// Optional method to access the internals (used by some {@link io.github.dfa1.vortex.encoding.Encoding})
+	/// Returns the raw buffer at position {@code i} (used by some {@link io.github.dfa1.vortex.encoding.Encoding}).
+	///
+	/// @param i buffer index
+	/// @return memory segment for buffer {@code i}
 	default MemorySegment buffer(int i) {
 		throw new VortexException(getClass().getSimpleName() + " has no raw buffers");
 	}
 
-	/// Optional method to access any children array (used by some {@link io.github.dfa1.vortex.encoding.Encoding})
+	/// Returns the child array at position {@code i} (used by some {@link io.github.dfa1.vortex.encoding.Encoding}).
+	///
+	/// @param i child index
+	/// @return child array at index {@code i}
 	default Array child(int i) {
 		throw new VortexException(getClass().getSimpleName() + " has no children");
 	}

core/src/main/java/io/github/dfa1/vortex/core/array/BoolArray.java

@@ -14,6 +14,12 @@ public final class BoolArray implements Array {
 	private final MemorySegment buffer;
 	private final ArrayStats stats;
 
+	/// Constructs a {@code BoolArray} backed by the given bit-packed buffer.
+	///
+	/// @param dtype  logical type, must be {@link io.github.dfa1.vortex.core.DType.Bool}
+	/// @param length number of logical boolean elements
+	/// @param buffer bit-packed boolean data (LSB-first, one byte per 8 elements)
+	/// @param stats  per-array statistics, or {@link ArrayStats#empty()} if unknown
 	public BoolArray(DType dtype, long length, MemorySegment buffer, ArrayStats stats) {
 		this.dtype = dtype;
 		this.length = length;
@@ -31,6 +37,9 @@ public long length() {
 		return length;
 	}
 
+	/// Returns the per-array statistics for this array.
+	///
+	/// @return the {@link ArrayStats} associated with this array
 	public ArrayStats stats() {
 		return stats;
 	}
@@ -43,6 +52,10 @@ public MemorySegment buffer(int i) {
 		return buffer;
 	}
 
+	/// Returns the boolean value at the given logical index.
+	///
+	/// @param i zero-based logical index (must be in {@code [0, length)})
+	/// @return the boolean value at position {@code i}
 	public boolean getBoolean(long i) {
 		byte b = buffer.get(ValueLayout.JAVA_BYTE, i >>> 3);
 		return (b & (1 << (i & 7))) != 0;