From 30a3840d5f31f8251fd8a025398d0a5c3cc14599 Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Fri, 24 May 2024 10:35:08 -0400
Subject: [PATCH] Update documentaiton

---
 arrow-arith/src/arity.rs                 | 23 +++++++++++++++++++++--
 arrow-array/src/array/primitive_array.rs |  4 ++--
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/arrow-arith/src/arity.rs b/arrow-arith/src/arity.rs
index 003b1c2ea93f..d85ee67d062b 100644
--- a/arrow-arith/src/arity.rs
+++ b/arrow-arith/src/arity.rs
@@ -243,7 +243,7 @@ where
 /// If the underlying buffers in `a` are not shared with other arrays,  mutates
 /// the underlying buffer in place, without allocating.
 ///
-/// If the underlying buffer in `a   are shared, returns Err(self)
+/// If the underlying buffer in `a` are shared, returns Err(self)
 ///
 /// Like [`unary`] the provided function is evaluated for every index, ignoring validity. This
 /// is beneficial when the cost of the operation is low compared to the cost of branching, and
@@ -252,7 +252,7 @@ where
 ///
 /// # Errors
 ///
-/// * if the arrays have different lengths.
+/// * if the arrays have different lengths
 /// * If the array is not mutable.
 ///
 /// # See Also
@@ -270,6 +270,25 @@ where
 /// let a = binary_mut(a, &b, |a, b| a + b).unwrap().unwrap();
 /// assert_eq!(a, Float32Array::from(vec![Some(6.1), None, Some(8.8)]));
 /// ```
+///
+/// # Example with shared buffers
+/// ```
+/// # use arrow_arith::arity::binary_mut;
+/// # use arrow_array::Float32Array;
+/// # use arrow_array::types::Int32Type;
+/// let a = Float32Array::from(vec![Some(5.1f32), None, Some(6.8)]);
+/// let b = Float32Array::from(vec![Some(1.0f32), None, Some(2.0)]);
+/// // a_clone shares the buffer with a
+/// let a_cloned = a.clone();
+/// // try to update a in place, but it is shared. Returns Err(a)
+/// let a = binary_mut(a, &b, |a, b| a + b).unwrap_err();
+/// assert_eq!(a_cloned, a);
+/// // drop shared reference
+/// drop(a_cloned);
+/// // now a is not shared, so we can update it in place
+/// let a = binary_mut(a, &b, |a, b| a + b).unwrap().unwrap();
+/// assert_eq!(a, Float32Array::from(vec![Some(6.1), None, Some(8.8)]));
+/// ```
 pub fn binary_mut<T, F>(
     a: PrimitiveArray<T>,
     b: &PrimitiveArray<T>,
diff --git a/arrow-array/src/array/primitive_array.rs b/arrow-array/src/array/primitive_array.rs
index ad22f25db966..24502ce69c7b 100644
--- a/arrow-array/src/array/primitive_array.rs
+++ b/arrow-array/src/array/primitive_array.rs
@@ -978,8 +978,8 @@ impl<T: ArrowPrimitiveType> PrimitiveArray<T> {
     /// If the underlying data buffer has no other outstanding references, the
     /// buffer is used without copying.
     ///
-    /// If the underlying data buffer does have outstanding references, the
-    /// buffer is cloned.
+    /// If the underlying data buffer does have outstanding references, returns
+    /// `Err(self)`
     pub fn into_builder(self) -> Result<PrimitiveBuilder<T>, Self> {
         let len = self.len();
         let data = self.into_data();