Minor: Clarify documentation on NullBufferBuilder::allocated_size (#7089)

* Minor: Clarify documentaiton on NullBufferBuilder::allocated_size

* add note about why allocations are 64 bytes

Author: alamb

arrow-buffer/src/buffer/mutable.rs

@@ -288,7 +288,8 @@ impl MutableBuffer {
         self.len
     }
 
-    /// Returns the total capacity in this buffer.
+    /// Returns the total capacity in this buffer, in bytes.
+    ///
     /// The invariant `buffer.len() <= buffer.capacity()` is always upheld.
     #[inline]
     pub const fn capacity(&self) -> usize {

arrow-buffer/src/builder/boolean.rs

@@ -83,7 +83,24 @@ impl BooleanBufferBuilder {
         self.len == 0
     }
 
-    /// Returns the capacity of the buffer
+    /// Returns the capacity of the buffer, in bits (not bytes)
+    ///
+    /// Note this
+    ///
+    /// # Example
+    /// ```
+    /// # use arrow_buffer::builder::BooleanBufferBuilder;
+    /// // empty requires 0 bytes
+    /// let b = BooleanBufferBuilder::new(0);
+    /// assert_eq!(0, b.capacity());
+    /// // Creating space for 1 bit results in 64 bytes (space for 512 bits)
+    /// // (64 is the minimum allocation size for 64 bit architectures)
+    /// let mut b = BooleanBufferBuilder::new(1);
+    /// assert_eq!(512, b.capacity());
+    /// // 1000 bits requires 128 bytes (space for 1024 bits)
+    /// b.append_n(1000, true);
+    /// assert_eq!(1024, b.capacity());
+    /// ```
     #[inline]
     pub fn capacity(&self) -> usize {
         self.buffer.capacity() * 8

arrow-buffer/src/builder/null.rs

@@ -217,7 +217,7 @@ impl NullBufferBuilder {
         self.bitmap_builder.as_mut().map(|b| b.as_slice_mut())
     }
 
-    /// Return the allocated size of this builder, in bytes, useful for memory accounting.
+    /// Return the allocated size of this builder, in bits, useful for memory accounting.
     pub fn allocated_size(&self) -> usize {
         self.bitmap_builder
             .as_ref()