Clarify docs of binary and string builders (#2699)

* Clarify docs of binary and string builders

* Improve doc of with capacity based on review feedback

arrow/src/array/builder/generic_binary_builder.rs

@@ -38,9 +38,12 @@ impl<OffsetSize: OffsetSizeTrait> GenericBinaryBuilder<OffsetSize> {
         Self::with_capacity(1024, 1024)
     }
 
-    /// Creates a new [`GenericBinaryBuilder`],
-    /// `item_capacity` is the number of items to pre-allocate space for in this builder
-    /// `data_capacity` is the number of bytes to pre-allocate space for in this builder
+    /// Creates a new [`GenericBinaryBuilder`].
+    ///
+    /// - `item_capacity` is the number of items to pre-allocate.
+    ///   The size of the preallocated buffer of offsets is the number of items plus one.
+    /// - `data_capacity` is the total number of bytes of string data to pre-allocate
+    ///   (for all items, not per item).
     pub fn with_capacity(item_capacity: usize, data_capacity: usize) -> Self {
         let mut offsets_builder = BufferBuilder::<OffsetSize>::new(item_capacity + 1);
         offsets_builder.append(OffsetSize::zero());
@@ -60,7 +63,7 @@ impl<OffsetSize: OffsetSizeTrait> GenericBinaryBuilder<OffsetSize> {
             .append(OffsetSize::from_usize(self.value_builder.len()).unwrap());
     }
 
-    /// Append a null value to the array.
+    /// Append a null value into the builder.
     #[inline]
     pub fn append_null(&mut self) {
         self.null_buffer_builder.append(false);

arrow/src/array/builder/generic_string_builder.rs

@@ -28,16 +28,19 @@ pub struct GenericStringBuilder<OffsetSize: OffsetSizeTrait> {
 }
 
 impl<OffsetSize: OffsetSizeTrait> GenericStringBuilder<OffsetSize> {
-    /// Creates a new [`GenericStringBuilder`],
+    /// Creates a new [`GenericStringBuilder`].
     pub fn new() -> Self {
         Self {
             builder: GenericBinaryBuilder::new(),
         }
     }
 
-    /// Creates a new [`GenericStringBuilder`],
-    /// `data_capacity` is the number of bytes of string data to pre-allocate space for in this builder
-    /// `item_capacity` is the number of items to pre-allocate space for in this builder
+    /// Creates a new [`GenericStringBuilder`].
+    ///
+    /// - `item_capacity` is the number of items to pre-allocate.
+    ///   The size of the preallocated buffer of offsets is the number of items plus one.
+    /// - `data_capacity` is the total number of bytes of string data to pre-allocate
+    ///   (for all items, not per item).
     pub fn with_capacity(item_capacity: usize, data_capacity: usize) -> Self {
         Self {
             builder: GenericBinaryBuilder::with_capacity(item_capacity, data_capacity),
@@ -50,13 +53,13 @@ impl<OffsetSize: OffsetSizeTrait> GenericStringBuilder<OffsetSize> {
         self.builder.append_value(value.as_ref().as_bytes());
     }
 
-    /// Append a null value to the array.
+    /// Append a null value into the builder.
     #[inline]
     pub fn append_null(&mut self) {
         self.builder.append_null()
     }
 
-    /// Append an `Option` value to the array.
+    /// Append an `Option` value into the builder.
     #[inline]
     pub fn append_option(&mut self, value: Option<impl AsRef<str>>) {
         match value {
@@ -78,12 +81,12 @@ impl<OffsetSize: OffsetSizeTrait> GenericStringBuilder<OffsetSize> {
         data.into()
     }
 
-    /// Returns the current values buffer as a slice
+    /// Returns the current values buffer as a slice.
     pub fn values_slice(&self) -> &[u8] {
         self.builder.values_slice()
     }
 
-    /// Returns the current offsets buffer as a slice
+    /// Returns the current offsets buffer as a slice.
     pub fn offsets_slice(&self) -> &[OffsetSize] {
         self.builder.offsets_slice()
     }