docs: Batch 2+3 Doxygen — core support, encodings, compression (15 headers)

Add /// documentation to all public symbols in:
- Core support: memory.hpp, statistics.hpp, column_reader.hpp,
  column_writer.hpp, column_index.hpp, mmap_reader.hpp
- Encodings: rle.hpp, delta.hpp, dictionary.hpp, byte_stream_split.hpp
- Compression: codec.hpp, snappy.hpp, zstd.hpp, lz4.hpp, gzip.hpp

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

Author: Johnson-Ogundeji

include/signet/column_index.hpp

@@ -2,21 +2,20 @@
 // Copyright 2026 Johnson Ogundeji
 #pragma once
 
-// ---------------------------------------------------------------------------
-// column_index.hpp -- ColumnIndex, OffsetIndex, and ColumnIndexBuilder
-//
-// Per-column-chunk structures for predicate pushdown and random page access.
-// Written after the row groups but before the footer in the Parquet file.
-//
-// ColumnIndex stores per-page min/max statistics, enabling readers to skip
-// pages that cannot contain matching data. OffsetIndex stores page locations
-// for efficient random access into column chunks.
-//
-// Thrift field IDs follow the canonical parquet.thrift specification:
-//   ColumnIndex:  1=null_pages, 2=min_values, 3=max_values, 4=boundary_order, 5=null_counts
-//   OffsetIndex:  1=page_locations (list<PageLocation>)
-//   PageLocation: 1=offset, 2=compressed_page_size, 3=first_row_index
-// ---------------------------------------------------------------------------
+/// @file column_index.hpp
+/// @brief ColumnIndex, OffsetIndex, and ColumnIndexBuilder for predicate pushdown.
+///
+/// Per-column-chunk structures for predicate pushdown and random page access.
+/// Written after the row groups but before the footer in the Parquet file.
+///
+/// ColumnIndex stores per-page min/max statistics, enabling readers to skip
+/// pages that cannot contain matching data. OffsetIndex stores page locations
+/// for efficient random access into column chunks.
+///
+/// Thrift field IDs follow the canonical parquet.thrift specification:
+/// - ColumnIndex:  1=null_pages, 2=min_values, 3=max_values, 4=boundary_order, 5=null_counts
+/// - OffsetIndex:  1=page_locations (list of PageLocation)
+/// - PageLocation: 1=offset, 2=compressed_page_size, 3=first_row_index
 
 #include "signet/thrift/compact.hpp"
 
@@ -26,14 +25,18 @@
 
 namespace signet::forge {
 
-// ---------------------------------------------------------------------------
-// PageLocation -- file offset and size for a single data page
-// ---------------------------------------------------------------------------
+/// File offset and size descriptor for a single data page.
+///
+/// Used by OffsetIndex to record the location of each page within the
+/// Parquet file, enabling random access into column chunks without
+/// sequential scanning.
 struct PageLocation {
-    int64_t offset              = 0;  // File offset of the page
-    int32_t compressed_page_size = 0; // Size of the page (compressed bytes)
-    int64_t first_row_index     = 0;  // First row in this page (relative to row group)
+    int64_t offset              = 0;  ///< Absolute file offset of the page header.
+    int32_t compressed_page_size = 0; ///< Size of the page in compressed bytes.
+    int64_t first_row_index     = 0;  ///< First row in this page (relative to row group).
 
+    /// Serialize this PageLocation to a Thrift compact encoder.
+    /// @param enc  The encoder to write to.
     void serialize(thrift::CompactEncoder& enc) const {
         enc.begin_struct();
 
@@ -53,6 +56,8 @@ struct PageLocation {
         enc.end_struct();
     }
 
+    /// Deserialize this PageLocation from a Thrift compact decoder.
+    /// @param dec  The decoder to read from.
     void deserialize(thrift::CompactDecoder& dec) {
         dec.begin_struct();
         for (;;) {
@@ -69,12 +74,18 @@ struct PageLocation {
     }
 };
 
-// ---------------------------------------------------------------------------
-// OffsetIndex -- page locations for random access within a column chunk
-// ---------------------------------------------------------------------------
+/// Page locations for random access within a column chunk.
+///
+/// Contains a list of PageLocation entries, one per data page in the
+/// column chunk. Written to the Parquet file after row groups to enable
+/// readers to seek directly to any page.
+///
+/// @see ColumnIndex (companion structure for predicate pushdown)
 struct OffsetIndex {
-    std::vector<PageLocation> page_locations;
+    std::vector<PageLocation> page_locations; ///< One entry per data page.
 
+    /// Serialize this OffsetIndex to a Thrift compact encoder.
+    /// @param enc  The encoder to write to.
     void serialize(thrift::CompactEncoder& enc) const {
         enc.begin_struct();
 
@@ -90,6 +101,8 @@ struct OffsetIndex {
         enc.end_struct();
     }
 
+    /// Deserialize this OffsetIndex from a Thrift compact decoder.
+    /// @param dec  The decoder to read from.
     void deserialize(thrift::CompactDecoder& dec) {
         dec.begin_struct();
         for (;;) {
@@ -111,23 +124,32 @@ struct OffsetIndex {
     }
 };
 
-// ---------------------------------------------------------------------------
-// ColumnIndex -- per-page min/max statistics for predicate pushdown
-// ---------------------------------------------------------------------------
+/// Per-page min/max statistics for predicate pushdown.
+///
+/// Stores binary-encoded min/max values for each data page in a column
+/// chunk, along with null-page flags, boundary ordering, and optional
+/// null counts. Readers use filter_pages() to eliminate pages whose value
+/// ranges do not overlap the query predicate.
+///
+/// @see OffsetIndex          (companion for page offsets)
+/// @see ColumnIndexBuilder   (builder pattern for constructing during writes)
 struct ColumnIndex {
-    std::vector<bool>        null_pages;     // true if page is all nulls
-    std::vector<std::string> min_values;     // Min value per page (binary encoded)
-    std::vector<std::string> max_values;     // Max value per page (binary encoded)
+    std::vector<bool>        null_pages;  ///< True if the corresponding page is all nulls.
+    std::vector<std::string> min_values;  ///< Binary-encoded minimum value per page.
+    std::vector<std::string> max_values;  ///< Binary-encoded maximum value per page.
 
+    /// Ordering of min values across pages, used to short-circuit filtering.
     enum class BoundaryOrder : int32_t {
-        UNORDERED  = 0,
-        ASCENDING  = 1,
-        DESCENDING = 2
+        UNORDERED  = 0, ///< Min values have no particular order.
+        ASCENDING  = 1, ///< Min values are non-decreasing across pages.
+        DESCENDING = 2  ///< Min values are non-increasing across pages.
     };
-    BoundaryOrder boundary_order = BoundaryOrder::UNORDERED;
+    BoundaryOrder boundary_order = BoundaryOrder::UNORDERED; ///< Boundary order of min values.
 
-    std::vector<int64_t> null_counts;        // Null count per page (optional)
+    std::vector<int64_t> null_counts; ///< Null count per page (optional).
 
+    /// Serialize this ColumnIndex to a Thrift compact encoder.
+    /// @param enc  The encoder to write to.
     void serialize(thrift::CompactEncoder& enc) const {
         enc.begin_struct();
 
@@ -173,6 +195,8 @@ struct ColumnIndex {
         enc.end_struct();
     }
 
+    /// Deserialize this ColumnIndex from a Thrift compact decoder.
+    /// @param dec  The decoder to read from.
     void deserialize(thrift::CompactDecoder& dec) {
         dec.begin_struct();
         for (;;) {
@@ -224,20 +248,22 @@ struct ColumnIndex {
         dec.end_struct();
     }
 
-    // -------------------------------------------------------------------
-    // filter_pages -- predicate pushdown filter
-    //
-    // Given a range [min_val, max_val] (binary-encoded, same encoding
-    // as min_values/max_values), returns a vector of page indices that
-    // might contain matching data. A page is excluded only if its max
-    // is strictly less than min_val or its min is strictly greater than
-    // max_val. Null pages are always excluded.
-    //
-    // Binary comparison uses lexicographic byte ordering, which is
-    // correct for unsigned integer types and strings. For signed types,
-    // the caller should ensure values use a comparison-safe binary
-    // encoding (e.g., Parquet's standard signed-magnitude encoding).
-    // -------------------------------------------------------------------
+    /// Filter pages by a value range for predicate pushdown.
+    ///
+    /// Given a range [@p min_val, @p max_val] (binary-encoded, same encoding
+    /// as min_values/max_values), returns page indices that might contain
+    /// matching data. A page is excluded only if its max is strictly less
+    /// than @p min_val or its min is strictly greater than @p max_val.
+    /// All-null pages are always excluded.
+    ///
+    /// @note Binary comparison uses lexicographic byte ordering, which is
+    ///       correct for unsigned integer types and strings. For signed
+    ///       types, the caller should ensure values use a comparison-safe
+    ///       binary encoding.
+    ///
+    /// @param min_val  Lower bound of the query range (binary-encoded).
+    /// @param max_val  Upper bound of the query range (binary-encoded).
+    /// @return A vector of page indices (0-based) that may contain matches.
     [[nodiscard]] std::vector<size_t> filter_pages(
             const std::string& min_val,
             const std::string& max_val) const {
@@ -268,23 +294,26 @@ struct ColumnIndex {
     }
 };
 
-// ---------------------------------------------------------------------------
-// ColumnIndexBuilder -- accumulates per-page statistics during writing
-//
-// Usage:
-//   ColumnIndexBuilder builder;
-//   for (each page being written) {
-//       builder.start_page();
-//       builder.set_min(...);
-//       builder.set_max(...);
-//       builder.set_null_page(false);
-//       builder.set_null_count(0);
-//       builder.set_first_row_index(row_offset);
-//       builder.set_page_location(file_offset, compressed_size);
-//   }
-//   ColumnIndex ci = builder.build_column_index();
-//   OffsetIndex oi = builder.build_offset_index();
-// ---------------------------------------------------------------------------
+/// Builder that accumulates per-page statistics during column writing.
+///
+/// Usage:
+/// @code
+///   ColumnIndexBuilder builder;
+///   for (each page being written) {
+///       builder.start_page();
+///       builder.set_min(...);
+///       builder.set_max(...);
+///       builder.set_null_page(false);
+///       builder.set_null_count(0);
+///       builder.set_first_row_index(row_offset);
+///       builder.set_page_location(file_offset, compressed_size);
+///   }
+///   ColumnIndex ci = builder.build_column_index();
+///   OffsetIndex oi = builder.build_offset_index();
+/// @endcode
+///
+/// @see ColumnIndex   (output of build_column_index())
+/// @see OffsetIndex   (output of build_offset_index())
 class ColumnIndexBuilder {
 public:
     /// Start a new page. Must be called before set_min/set_max etc.
@@ -293,42 +322,48 @@ class ColumnIndexBuilder {
     }
 
     /// Record the minimum value for the current page (binary-encoded).
+    /// @param min_val  The binary-encoded minimum value.
     void set_min(const std::string& min_val) {
         if (!pages_.empty()) {
             pages_.back().min_value = min_val;
         }
     }
 
     /// Record the maximum value for the current page (binary-encoded).
+    /// @param max_val  The binary-encoded maximum value.
     void set_max(const std::string& max_val) {
         if (!pages_.empty()) {
             pages_.back().max_value = max_val;
         }
     }
 
     /// Mark the current page as all-nulls (or not).
+    /// @param is_null  True if the page contains only null values.
     void set_null_page(bool is_null) {
         if (!pages_.empty()) {
             pages_.back().null_page = is_null;
         }
     }
 
     /// Record the null count for the current page.
+    /// @param count  Number of null values in the current page.
     void set_null_count(int64_t count) {
         if (!pages_.empty()) {
             pages_.back().null_count = count;
         }
     }
 
     /// Record the first row index for the current page (relative to row group).
+    /// @param row_index  Zero-based row index of the first row in this page.
     void set_first_row_index(int64_t row_index) {
         if (!pages_.empty()) {
             pages_.back().first_row_index = row_index;
         }
     }
 
-    /// Record the page location (file offset and compressed size) for the
-    /// current page.
+    /// Record the page location (file offset and compressed size) for the current page.
+    /// @param offset           Absolute file offset of the page.
+    /// @param compressed_size  Page size in compressed bytes.
     void set_page_location(int64_t offset, int32_t compressed_size) {
         if (!pages_.empty()) {
             pages_.back().offset = offset;
@@ -337,6 +372,10 @@ class ColumnIndexBuilder {
     }
 
     /// Finalize and return the ColumnIndex from accumulated page info.
+    ///
+    /// Automatically detects boundary order from the min_values sequence.
+    ///
+    /// @return A fully populated ColumnIndex ready for serialization.
     [[nodiscard]] ColumnIndex build_column_index() const {
         ColumnIndex ci;
         ci.null_pages.reserve(pages_.size());
@@ -368,6 +407,7 @@ class ColumnIndexBuilder {
     }
 
     /// Finalize and return the OffsetIndex from accumulated page info.
+    /// @return A fully populated OffsetIndex ready for serialization.
     [[nodiscard]] OffsetIndex build_offset_index() const {
         OffsetIndex oi;
         oi.page_locations.reserve(pages_.size());
@@ -392,6 +432,7 @@ class ColumnIndexBuilder {
     [[nodiscard]] size_t num_pages() const { return pages_.size(); }
 
 private:
+    /// Accumulated per-page metadata during building.
     struct PageInfo {
         std::string min_value;
         std::string max_value;
@@ -404,12 +445,7 @@ class ColumnIndexBuilder {
 
     std::vector<PageInfo> pages_;
 
-    // -------------------------------------------------------------------
-    // Detect boundary order from the min_values sequence.
-    // Returns ASCENDING if all min values are non-decreasing,
-    // DESCENDING if all are non-increasing, UNORDERED otherwise.
-    // A single-page or empty sequence is ASCENDING by convention.
-    // -------------------------------------------------------------------
+    /// Detect boundary order from the min_values sequence.
     [[nodiscard]] static ColumnIndex::BoundaryOrder detect_boundary_order(
             const std::vector<std::string>& values) {