Minor: Clarify NullBufferBuilder::new capacity parameter

arrow-buffer/src/builder/boolean.rs

@@ -32,7 +32,11 @@ pub struct BooleanBufferBuilder {
 }
 
 impl BooleanBufferBuilder {
-    /// Creates a new `BooleanBufferBuilder`
+    /// Creates a new `BooleanBufferBuilder` with sufficient space for
+    /// `capacity` bits (not bytes).
+    ///
+    /// The capacity is rounded up to the nearest multiple of 8 for the
+    /// allocation.
     #[inline]
     pub fn new(capacity: usize) -> Self {
         let byte_capacity = bit_util::ceil(capacity, 8);

arrow-buffer/src/builder/null.rs

@@ -54,7 +54,10 @@ pub struct NullBufferBuilder {
 
 impl NullBufferBuilder {
     /// Creates a new empty builder.
-    /// `capacity` is the number of bits in the null buffer.
+    ///
+    /// Note that this method does not allocate any memory, regardless of the
+    /// `capacity` parameter. If an allocation is required, `capacity` is the
+    /// size in bits (not bytes) that will be allocated at minimum.
     pub fn new(capacity: usize) -> Self {
         Self {
             bitmap_builder: None,