Minor: Improve arrow_cast documentation (#5825)

* Minor: Improve arrow_cast documentatin

* tweaks

Author: alamb

arrow-cast/src/base64.rs

@@ -15,7 +15,9 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Functions for Base64 encoding/decoding
+//! Functions for converting data in [`GenericBinaryArray`] such as [`StringArray`] to/from base64 encoded strings
+//!
+//! [`StringArray`]: arrow_array::StringArray
 
 use arrow_array::{Array, GenericBinaryArray, GenericStringArray, OffsetSizeTrait};
 use arrow_buffer::OffsetBuffer;
@@ -25,7 +27,7 @@ use base64::engine::Config;
 
 pub use base64::prelude::*;
 
-/// Bas64 encode each element of `array` with the provided `engine`
+/// Bas64 encode each element of `array` with the provided [`Engine`]
 pub fn b64_encode<E: Engine, O: OffsetSizeTrait>(
     engine: &E,
     array: &GenericBinaryArray<O>,
@@ -51,7 +53,7 @@ pub fn b64_encode<E: Engine, O: OffsetSizeTrait>(
     unsafe { GenericStringArray::new_unchecked(offsets, buffer.into(), array.nulls().cloned()) }
 }
 
-/// Base64 decode each element of `array` with the provided `engine`
+/// Base64 decode each element of `array` with the provided [`Engine`]
 pub fn b64_decode<E: Engine, O: OffsetSizeTrait>(
     engine: &E,
     array: &GenericBinaryArray<O>,

arrow-cast/src/display.rs

@@ -15,10 +15,14 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Functions for printing array values, as strings, for debugging
-//! purposes. See the `pretty` crate for additional functions for
+//! Functions for printing array values as human-readable strings.
+//!
+//! This is often used for debugging or logging purposes.
+//!
+//! See the [`pretty`] crate for additional functions for
 //! record batch pretty printing.
-
+//!
+//! [`pretty`]: crate::pretty
 use std::fmt::{Display, Formatter, Write};
 use std::ops::Range;
 

arrow-cast/src/lib.rs

@@ -15,8 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Cast kernel for [Apache Arrow](https://docs.rs/arrow)
-
+//! Functions for converting from one data type to another in [Apache Arrow](https://docs.rs/arrow)
 pub mod cast;
 pub use cast::*;
 pub mod display;

arrow-cast/src/parse.rs

@@ -15,6 +15,9 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! [`Parser`] implementations for converting strings to Arrow types
+//!
+//! Used by the CSV and JSON readers to convert strings to Arrow types
 use arrow_array::timezone::Tz;
 use arrow_array::types::*;
 use arrow_array::ArrowNativeTypeOp;
@@ -405,8 +408,29 @@ fn string_to_time(s: &str) -> Option<NaiveTime> {
     )
 }
 
-/// Specialized parsing implementations
-/// used by csv and json reader
+/// Specialized parsing implementations to convert strings to Arrow types.
+///
+/// This is used by csv and json reader and can be used directly as well.
+///
+/// # Example
+///
+/// To parse a string to a [`Date32Type`]:
+///
+/// ```
+/// use arrow_cast::parse::Parser;
+/// use arrow_array::types::Date32Type;
+/// let date = Date32Type::parse("2021-01-01").unwrap();
+/// assert_eq!(date, 18628);
+/// ```
+///
+/// To parse a string to a [`TimestampNanosecondType`]:
+///
+/// ```
+/// use arrow_cast::parse::Parser;
+/// use arrow_array::types::TimestampNanosecondType;
+/// let ts = TimestampNanosecondType::parse("2021-01-01T00:00:00.123456789Z").unwrap();
+/// assert_eq!(ts, 1609459200123456789);
+/// ```
 pub trait Parser: ArrowPrimitiveType {
     fn parse(string: &str) -> Option<Self::Native>;
 

arrow-cast/src/pretty.rs

@@ -15,8 +15,12 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Utilities for pretty printing record batches. Note this module is not
-//! available unless `feature = "prettyprint"` is enabled.
+//! Utilities for pretty printing [`RecordBatch`]es and [`Array`]s.
+//!
+//! Note this module is not available unless `feature = "prettyprint"` is enabled.
+//!
+//! [`RecordBatch`]: arrow_array::RecordBatch
+//! [`Array`]: arrow_array::Array
 
 use std::fmt::Display;