From 878217b9e330b4f1ed13e798a214ea11fbeb2bbb Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Fri, 8 Sep 2023 06:10:08 -0400
Subject: [PATCH] Add docstring and example to `Scalar` (#4793)

---
 arrow-array/src/scalar.rs | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/arrow-array/src/scalar.rs b/arrow-array/src/scalar.rs
index 7dfdbddd964a..f2a696a8f329 100644
--- a/arrow-array/src/scalar.rs
+++ b/arrow-array/src/scalar.rs
@@ -98,9 +98,32 @@ impl Datum for &dyn Array {
     }
 }
 
-/// A wrapper around a single value [`Array`] indicating kernels should treat it as a scalar value
+/// A wrapper around a single value [`Array`] that implements
+/// [`Datum`] and indicates [compute] kernels should treat this array
+/// as a scalar value (a single value).
 ///
-/// See [`Datum`] for more information
+/// Using a [`Scalar`] is often much more efficient than creating an
+/// [`Array`] with the same (repeated) value.
+///
+/// See [`Datum`] for more information.
+///
+/// # Example
+///
+/// ```rust
+/// # use arrow_array::{Scalar, Int32Array, ArrayRef};
+/// # fn get_array() -> ArrayRef { std::sync::Arc::new(Int32Array::from(vec![42])) }
+/// // Create a (typed) scalar for Int32Array for the value 42
+/// let scalar = Scalar::new(Int32Array::from(vec![42]));
+///
+/// // Create a scalar using PrimtiveArray::scalar
+/// let scalar = Int32Array::new_scalar(42);
+///
+/// // create a scalar from an ArrayRef (for dynamic typed Arrays)
+/// let array: ArrayRef = get_array();
+/// let scalar = Scalar::new(array);
+/// ```
+///
+/// [compute]: https://docs.rs/arrow/latest/arrow/compute/index.html
 #[derive(Debug, Copy, Clone)]
 pub struct Scalar<T: Array>(T);