Update documentaiton

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>,

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();