[Variant] add doc reference to VariantArrayBuilder

parquet-variant-compute/src/variant_array_builder.rs

@@ -37,6 +37,14 @@ use std::sync::Arc;
 /// This builder always creates a `VariantArray` using [`BinaryViewArray`] for both
 /// the metadata and value fields.
 ///
+/// `VariantArrayBuilder` implements [`VariantBuilderExt`], so you append values
+/// and nested objects or lists the same way as when building a single
+/// [`Variant`] value with [`VariantBuilder`], rather than constructing a
+/// `VariantBuilder` per row.
+///
+/// [`VariantBuilder`]: parquet_variant::VariantBuilder
+/// [`VariantBuilderExt`]: parquet_variant::VariantBuilderExt
+///
 /// # TODO
 /// 1. Support shredding: <https://github.com/apache/arrow-rs/issues/7895>
 ///

parquet-variant/src/builder.rs

@@ -477,6 +477,13 @@ impl<S: BuilderSpecificState> Drop for ParentState<'_, S> {
 
 /// Top level builder for [`Variant`] values
 ///
+/// `VariantBuilder` builds a single, self-contained [`Variant`] value -- useful
+/// for one-off values and unit tests. To build an array (column) of variants,
+/// one per input row, use [`VariantArrayBuilder`] from the
+/// `parquet-variant-compute` crate rather than a `VariantBuilder` per row.
+///
+/// [`VariantArrayBuilder`]: https://docs.rs/parquet-variant-compute/latest/parquet_variant_compute/struct.VariantArrayBuilder.html
+///
 /// # Example: create a Primitive Int8
 /// ```
 /// # use parquet_variant::{Variant, VariantBuilder};