Improve arrow-buffer documentation (#9020)

# Which issue does this PR close?

- Related to #8806 

# Rationale for this change

As I study this code, I want to encode my learnings for both my future
self and future readers of this code

# What changes are included in this PR?

Add documentation on the structure of the arrow buffer crate as well as
details on how BooleanBuffer works

# Are these changes tested?

CI
# Are there any user-facing changes?

Just docs, no functional changes

---------

Co-authored-by: Jeffrey Vo <jeffrey.vo.australia@gmail.com>

Author: alamb

arrow-buffer/src/buffer/boolean.rs

@@ -26,17 +26,58 @@ use std::ops::{BitAnd, BitOr, BitXor, Not};
 
 /// A slice-able [`Buffer`] containing bit-packed booleans
 ///
-/// `BooleanBuffer`s can be modified using [`BooleanBufferBuilder`]
+/// This structure represents a sequence of boolean values packed into a
+/// byte-aligned [`Buffer`]. Both the offset and length are represented in bits.
 ///
+/// # Layout
+///
+/// The values are represented as little endian bit-packed values, where the
+/// least significant bit of each byte represents the first boolean value and
+/// then proceeding to the most significant bit.
+///
+/// For example, the 10 bit bitmask `0b0111001101` has length 10, and is
+/// represented using 2 bytes with offset 0 like this:
+///
+/// ```text
+///        ┌─────────────────────────────────┐    ┌─────────────────────────────────┐
+///        │┌───┬───┬───┬───┬───┬───┬───┬───┐│    │┌───┬───┬───┬───┬───┬───┬───┬───┐│
+///        ││ 1 │ 0 │ 1 │ 1 │ 0 │ 0 │ 1 │ 1 ││    ││ 1 │ 0 │ ? │ ? │ ? │ ? │ ? │ ? ││
+///        │└───┴───┴───┴───┴───┴───┴───┴───┘│    │└───┴───┴───┴───┴───┴───┴───┴───┘│
+/// bit    └─────────────────────────────────┘    └─────────────────────────────────┘
+/// offset  0             Byte 0             7    0              Byte 1            7
+///
+///         length = 10 bits, offset = 0
+/// ```
+///
+/// The same bitmask with length 10 and offset 3 would be represented using 2
+/// bytes like this:
+///
+/// ```text
+///       ┌─────────────────────────────────┐    ┌─────────────────────────────────┐
+///       │┌───┬───┬───┬───┬───┬───┬───┬───┐│    │┌───┬───┬───┬───┬───┬───┬───┬───┐│
+///       ││ ? │ ? │ ? │ 1 │ 0 │ 1 │ 1 │ 0 ││    ││ 0 │ 1 │ 1 │ 1 │ 0 │ ? │ ? │ ? ││
+///       │└───┴───┴───┴───┴───┴───┴───┴───┘│    │└───┴───┴───┴───┴───┴───┴───┴───┘│
+/// bit   └─────────────────────────────────┘    └─────────────────────────────────┘
+/// offset 0             Byte 0             7    0              Byte 1            7
+///
+///        length = 10 bits, offset = 3
+/// ```
+///
+/// Note that the bits marked `?` are not logically part of the mask and may
+/// contain either `0` or `1`
 ///
 /// # See Also
+/// * [`BooleanBufferBuilder`] for building [`BooleanBuffer`] instances
 /// * [`NullBuffer`] for representing null values in Arrow arrays
 ///
 /// [`NullBuffer`]: crate::NullBuffer
 #[derive(Debug, Clone, Eq)]
 pub struct BooleanBuffer {
+    /// Underlying buffer (byte aligned)
     buffer: Buffer,
+    /// Offset in bits (not bytes)
     offset: usize,
+    /// Length in bits (not bytes)
     len: usize,
 }
 
@@ -304,12 +345,16 @@ impl BooleanBuffer {
     }
 
     /// Returns the inner [`Buffer`]
+    ///
+    /// Note: this does not account for offset and length of this [`BooleanBuffer`]
     #[inline]
     pub fn inner(&self) -> &Buffer {
         &self.buffer
     }
 
     /// Returns the inner [`Buffer`], consuming self
+    ///
+    /// Note: this does not account for offset and length of this [`BooleanBuffer`]
     pub fn into_inner(self) -> Buffer {
         self.buffer
     }

arrow-buffer/src/lib.rs

@@ -16,6 +16,21 @@
 // under the License.
 
 //! Low-level buffer abstractions for [Apache Arrow Rust](https://docs.rs/arrow)
+//!
+//! # Byte Storage abstractions
+//! - [`MutableBuffer`]: Raw memory buffer that can be mutated and grown
+//! - [`Buffer`]: Immutable buffer that is shared across threads
+//!
+//! # Typed Abstractions
+//!
+//! There are also several wrappers over [`Buffer`] with methods for
+//! easier manipulation:
+//!
+//! - [`BooleanBuffer`][]: Bitmasks (buffer of packed bits)
+//! - [`NullBuffer`][]: Arrow null (validity) bitmaps ([`BooleanBuffer`] with extra utilities)
+//! - [`ScalarBuffer<T>`][]: Typed buffer for primitive types (e.g., `i32`, `f64`)
+//! - [`OffsetBuffer<O>`][]: Offsets used in variable-length types (e.g., strings, lists)
+//! - [`RunEndBuffer<E>`][]: Run-ends used in run-encoded encoded data
 
 #![doc(
     html_logo_url = "https://arrow.apache.org/img/arrow-logo_chevrons_black-txt_white-bg.svg",