Tighten comments added on this branch

Trim the verbose doc and inline comments introduced with the dictionary-label
work down to what each actually needs to say. No code changes. Also drop a
stale "independent dictionary" inline comment in the multi-batch test that
contradicted the corrected doc (the file has one shared dictionary page).

Author: preinlein

lading/src/bin/captool/analyze/parquet.rs

@@ -258,13 +258,11 @@ mod tests {
         tmp
     }
 
-    /// `analyze_metric` reads captures written by the production parquet writer.
+    /// `analyze_metric` reads captures written by the production [`Format`] writer.
     ///
-    /// This binds `captool analyze` to the capture writer: the file is produced
-    /// by `lading_capture`'s [`Format`], so any change to the on-disk label
-    /// encoding (e.g. the `Dictionary(Int32, Utf8)` label columns) that the
-    /// analyzer fails to track breaks this test in CI rather than shipping a
-    /// silently broken tool.
+    /// Binds `captool analyze` to the writer's on-disk schema: a label-encoding
+    /// change the analyzer fails to track breaks this test rather than shipping
+    /// silently broken.
     #[test]
     #[expect(
         clippy::float_cmp,

lading_capture/src/formats.rs

@@ -400,13 +400,11 @@ mod tests {
         }
     }
 
-    /// Roundtrip many rows that share identical label key/value strings.
+    /// Roundtrip many rows sharing identical label strings.
     ///
-    /// The property test draws random labels, so cross-row repetition is
-    /// incidental. This locks in that the `Dictionary(Int32, Utf8)` label columns
-    /// roundtrip correctly under the production pattern where a handful of
-    /// distinct strings (e.g. `env=prod`) repeat across every row and are
-    /// dictionary-deduplicated by the writer.
+    /// The property test's random labels only repeat by chance; this pins the
+    /// production pattern where a few distinct strings (`env=prod`) repeat across
+    /// every row and are dictionary-deduplicated.
     #[test]
     fn parquet_round_trip_repeated_labels() {
         let run_id = Uuid::from_u128(0x1234_5678_9abc_def0_1234_5678_9abc_def0);
@@ -417,8 +415,8 @@ mod tests {
         .into_iter()
         .collect();
 
-        // 500 rows all carrying the same two labels, plus one row with a distinct
-        // label so the dictionary holds more than a single entry.
+        // 500 rows sharing two labels, plus one distinct row so the dictionary
+        // holds more than one entry.
         let mut input_lines: Vec<Line> = (0u64..500)
             .map(|i| Line {
                 run_id,
@@ -468,17 +466,14 @@ mod tests {
     /// Decode `Dictionary(Int32, Utf8)` labels when a file is read as several
     /// `RecordBatch`es.
     ///
-    /// The parquet reader emits one `RecordBatch` per `batch_size` rows, so
-    /// production files — which exceed the default batch size — are always read as
-    /// several batches, a path a small single-batch roundtrip never reaches. Here a
-    /// small `batch_size` forces multiple batches, and each batch's labels are
-    /// decoded through the production `resolve_label_dictionary` helper and checked
-    /// against the values written. The test asserts it actually produced more than
-    /// one batch so the multi-batch coverage cannot silently lapse.
+    /// The reader emits one `RecordBatch` per `batch_size` rows, so production
+    /// files are read as several batches — a path a single-batch roundtrip misses.
+    /// A small `batch_size` forces that here; each batch's labels are decoded via
+    /// the production `resolve_label_dictionary` and checked, and the test asserts
+    /// more than one batch so the coverage cannot silently lapse.
     ///
-    /// This does not exercise divergent per-batch dictionaries: the writer emits a
-    /// single row group with one dictionary page, so every read batch shares that
-    /// one dictionary rather than decoding an independent, index-restarted one.
+    /// It does not exercise divergent per-batch dictionaries: the writer emits one
+    /// row group with a single dictionary page, shared by every batch.
     #[test]
     fn parquet_round_trip_multiple_read_batches() {
         let run_id = Uuid::from_u128(0x0fed_cba9_8765_4321_0fed_cba9_8765_4321);
@@ -512,7 +507,7 @@ mod tests {
         let bytes = buffer.into_inner();
 
         // A batch size below the row count forces the reader to emit several
-        // batches, each decoding its labels from an independent dictionary.
+        // batches.
         let bytes_buf = Bytes::copy_from_slice(&bytes);
         let reader = ParquetRecordBatchReaderBuilder::try_new(bytes_buf)
             .expect("reader builder")

lading_capture/src/formats/parquet.rs

@@ -29,17 +29,14 @@ use crate::line;
 /// Resolve a label map column typed as [`label_dictionary_type`] to a typed
 /// dictionary view of its `Utf8` values.
 ///
-/// Both the label `key` and `value` columns are written as
-/// `Dictionary(Int32, Utf8)`, so every reader resolves them the same way. This
-/// is the single canonical decode path: readers in other crates (e.g. `captool`)
-/// call it too, so a schema change here surfaces in every reader at once. On
-/// failure returns a message prefixed with `column_name` (e.g. `"Labels keys"`)
-/// so callers can surface distinct errors for the key and value columns.
+/// The single decode path for both the `key` and `value` columns, shared across
+/// crates (e.g. `captool`) so a schema change surfaces everywhere at once.
+/// `column_name` prefixes the error so callers can tell the two columns apart.
 ///
 /// # Errors
 ///
-/// Returns an error message if `column` is not a `Dictionary(Int32, _)` or its
-/// dictionary values are not `Utf8`.
+/// Errors if `column` is not a `Dictionary(Int32, _)` or its values are not
+/// `Utf8`.
 pub fn resolve_label_dictionary<'a>(
     column: &'a dyn Array,
     column_name: &str,
@@ -237,8 +234,7 @@ impl<W: Write + Seek + Send> Format<W> {
         label_offsets.push(0i32);
         label_offsets.extend_from_slice(&self.buffers.label_offsets);
 
-        // Build the labels map array using pre-allocated buffers. Keys and
-        // values are dictionary-encoded (Int32,Utf8) so downstream readers
+        // Keys and values are dictionary-encoded (Int32,Utf8) so readers
         // materialize each distinct string once; labels dominate capture memory.
         let mut keys_builder = StringDictionaryBuilder::<Int32Type>::new();
         for key in &self.buffers.label_keys {

lading_capture_schema/src/lib.rs

@@ -77,11 +77,10 @@ fn labels_entry_field() -> Arc<Field> {
 
 /// Arrow logical type for label keys and values.
 ///
-/// Labels are a large portion of the memory used by capture consumers, and their
-/// key/value strings repeat heavily across rows. Typing them as
-/// `Dictionary(Int32, Utf8)` lets readers materialize each distinct string once
-/// and reference it by index, cutting resident memory rather than merely the
-/// on-disk size (which parquet page dictionary encoding already handled).
+/// Label strings repeat heavily across rows and dominate capture memory.
+/// `Dictionary(Int32, Utf8)` lets readers hold each distinct string once,
+/// cutting resident memory (not just on-disk size, which parquet already
+/// dictionary-encoded).
 #[must_use]
 pub fn label_dictionary_type() -> DataType {
     DataType::Dictionary(Box::new(DataType::Int32), Box::new(DataType::Utf8))