Minor: Add doc comments and example for ScalarVaue::to_scalar (#7491)

Author: alamb

datafusion/common/src/scalar.rs

@@ -1321,7 +1321,34 @@ impl ScalarValue {
         self.to_array_of_size(1)
     }
 
-    /// Converts a scalar into an arrow [`Scalar`]
+    /// Converts a scalar into an arrow [`Scalar`] (which implements
+    /// the [`Datum`] interface).
+    ///
+    /// This can be used to call arrow compute kernels such as `lt`
+    ///
+    /// # Example
+    /// ```
+    /// use datafusion_common::ScalarValue;
+    /// use arrow::array::{BooleanArray, Int32Array};
+    ///
+    /// let arr = Int32Array::from(vec![Some(1), None, Some(10)]);
+    /// let five = ScalarValue::Int32(Some(5));
+    ///
+    /// let result = arrow::compute::kernels::cmp::lt(
+    ///   &arr,
+    ///   &five.to_scalar(),
+    /// ).unwrap();
+    ///
+    /// let expected = BooleanArray::from(vec![
+    ///     Some(true),
+    ///     None,
+    ///     Some(false)
+    ///   ]
+    /// );
+    ///
+    /// assert_eq!(&result, &expected);
+    /// ```
+    /// [`Datum`]: arrow_array::Datum
     pub fn to_scalar(&self) -> Scalar<ArrayRef> {
         Scalar::new(self.to_array_of_size(1))
     }
@@ -1332,7 +1359,7 @@ impl ScalarValue {
     /// Returns an error if the iterator is empty or if the
     /// [`ScalarValue`]s are not all the same type
     ///
-    /// Example
+    /// # Example
     /// ```
     /// use datafusion_common::ScalarValue;
     /// use arrow::array::{ArrayRef, BooleanArray};