Minor: improve the documentation of NullBuffer and BooleanBuffer

arrow-buffer/src/buffer/boolean.rs

@@ -25,6 +25,14 @@ use crate::{
 use std::ops::{BitAnd, BitOr, BitXor, Not};
 
 /// A slice-able [`Buffer`] containing bit-packed booleans
+///
+/// `BooleanBuffer`s can be creating using [`BooleanBufferBuilder`]
+///
+/// # See Also
+///
+/// * [`NullBuffer`] for representing null values in Arrow arrays
+///
+/// [`NullBuffer`]: crate::NullBuffer
 #[derive(Debug, Clone, Eq)]
 pub struct BooleanBuffer {
     buffer: Buffer,

arrow-buffer/src/buffer/null.rs

@@ -19,13 +19,16 @@ use crate::bit_iterator::{BitIndexIterator, BitIterator, BitSliceIterator};
 use crate::buffer::BooleanBuffer;
 use crate::{Buffer, MutableBuffer};
 
-/// A [`BooleanBuffer`] used to encode validity for arrow arrays
+/// A [`BooleanBuffer`] used to encode validity for Arrow arrays
 ///
-/// As per the [Arrow specification], array validity is encoded in a packed bitmask with a
+/// In the [Arrow specification], array validity is encoded in a packed bitmask with a
 /// `true` value indicating the corresponding slot is not null, and `false` indicating
 /// that it is null.
 ///
+/// `NullBuffer`s can be creating using [`NullBufferBuilder`]
+///
 /// [Arrow specification]: https://arrow.apache.org/docs/format/Columnar.html#validity-bitmaps
+/// [`NullBufferBuilder`]: crate::NullBufferBuilder
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct NullBuffer {
     buffer: BooleanBuffer,
@@ -49,7 +52,8 @@ impl NullBuffer {
 
     /// Create a new [`NullBuffer`] of length `len` where all values are valid
     ///
-    /// Note: it is more efficient to not set the null buffer if it is known to be all valid
+    /// Note: it is more efficient to not set the null buffer if it is known to
+    /// be all valid (aka all values are not null)
     pub fn new_valid(len: usize) -> Self {
         Self {
             buffer: BooleanBuffer::new_set(len),

arrow-buffer/src/builder/boolean.rs

@@ -19,6 +19,12 @@ use crate::{bit_mask, bit_util, BooleanBuffer, Buffer, MutableBuffer};
 use std::ops::Range;
 
 /// Builder for [`BooleanBuffer`]
+///
+/// # See Also
+///
+/// * [`NullBuffer`] for building [`BooleanBuffer`]s for representing nulls
+///
+/// [`NullBuffer`]: crate::NullBuffer
 #[derive(Debug)]
 pub struct BooleanBufferBuilder {
     buffer: MutableBuffer,

arrow-buffer/src/builder/null.rs

@@ -17,12 +17,16 @@
 
 use crate::{BooleanBufferBuilder, MutableBuffer, NullBuffer};
 
-/// Builder for creating the null bit buffer.
+/// Builder for creating [`NullBuffer`]
+///
+/// # Performance
 ///
 /// This builder only materializes the buffer when we append `false`.
 /// If you only append `true`s to the builder, what you get will be
 /// `None` when calling [`finish`](#method.finish).
-/// This optimization is **very** important for the performance.
+///
+/// This optimization is **very** important for the performance as it avoids
+/// allocating memory for the null buffer when there are no nulls.
 #[derive(Debug)]
 pub struct NullBufferBuilder {
     bitmap_builder: Option<BooleanBufferBuilder>,