Move examples in arrow-csv to docstrings, polish up docs (#9001)

# Which issue does this PR close?


# Rationale for this change

while reviewing @xanderbailey's PR in
#8960, I found that there are
examples for arrow-csv and they are hard to find. Also each example add
extra binaries and thus slows down CI and tests. For example the
`whitespace_handling` example makes a new 2.9MB binary:

```shell
cargo run -p arrow-csv --example whitespace_handling
...
du -s -h target/debug/examples/whitespace_handling
2.9M	target/debug/examples/whitespace_handling
```

Let's consolidate the examples to make them easier to find


# What changes are included in this PR?

1. Consolidate the examples
2. Improver other csv docs

# Are these changes tested?

We typically require tests for all PRs in order to:
1. Prevent the code from being accidentally broken by subsequent changes
3. Serve as another way to document the expected behavior of the code


# Are there any user-facing changes?

Docs only, no functional changes

Author: alamb

arrow-csv/examples/README.md

@@ -15,7 +15,9 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Transfer data between the Arrow memory format and CSV (comma-separated values).
+//! Transfer data between the [Apache Arrow] memory format and CSV (comma-separated values).
+//!
+//! [Apache Arrow]: https://arrow.apache.org/
 
 #![doc(
     html_logo_url = "https://arrow.apache.org/img/arrow-logo_chevrons_black-txt_white-bg.svg",

arrow-csv/examples/csv_calculation.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! CSV Reader
+//! CSV Reading: [`Reader`] and [`ReaderBuilder`]
 //!
 //! # Basic Usage
 //!
@@ -42,6 +42,46 @@
 //! let batch = csv.next().unwrap().unwrap();
 //! ```
 //!
+//! # Example: Numeric calculations on CSV
+//! This code finds the maximum value in column 0 of a CSV file containing
+//! ```csv
+//! c1,c2,c3,c4
+//! 1,1.1,"hong kong",true
+//! 3,323.12,"XiAn",false
+//! 10,131323.12,"cheng du",false
+//! ```
+//!
+//! ```
+//! # use arrow_array::cast::AsArray;
+//! # use arrow_array::types::Int16Type;
+//! # use arrow_csv::ReaderBuilder;
+//! # use arrow_schema::{DataType, Field, Schema};
+//! # use std::fs::File;
+//! # use std::sync::Arc;
+//! // Open the example file
+//! let file = File::open("test/data/example.csv").unwrap();
+//! let csv_schema = Schema::new(vec![
+//!     Field::new("c1", DataType::Int16, true),
+//!     Field::new("c2", DataType::Float32, true),
+//!     Field::new("c3", DataType::Utf8, true),
+//!     Field::new("c4", DataType::Boolean, true),
+//! ]);
+//! let mut reader = ReaderBuilder::new(Arc::new(csv_schema))
+//!     .with_header(true)
+//!     .build(file)
+//!     .unwrap();
+//! // find the maximum value in column 0 across all batches
+//! let mut max_c0 = 0;
+//! while let Some(r) = reader.next() {
+//!   let r = r.unwrap(); // handle error
+//!   // get the max value in column(0) for this batch
+//!   let col = r.column(0).as_primitive::<Int16Type>();
+//!   let batch_max = col.iter().max().flatten().unwrap_or_default();
+//!   max_c0 = max_c0.max(batch_max);
+//! }
+//! assert_eq!(max_c0, 10);
+//!```
+//!
 //! # Async Usage
 //!
 //! The lower-level [`Decoder`] can be integrated with various forms of async data streams,
@@ -441,13 +481,18 @@ pub fn infer_schema_from_files(
 type Bounds = Option<(usize, usize)>;
 
 /// CSV file reader using [`std::io::BufReader`]
+///
+/// See [`ReaderBuilder`] to construct a CSV reader with options and  the
+/// [module-level documentation](crate::reader) for more details and examples
 pub type Reader<R> = BufReader<StdBufReader<R>>;
 
-/// CSV file reader
+/// CSV file reader implementation. See [`Reader`] for usage
+///
+/// Despite having the same name as [`std::io::BufReader`, this structure does
+/// not buffer reads itself
 pub struct BufReader<R> {
     /// File reader
     reader: R,
-
     /// The decoder
     decoder: Decoder,
 }
@@ -1053,7 +1098,7 @@ fn build_boolean_array(
         .map(|e| Arc::new(e) as ArrayRef)
 }
 
-/// CSV file reader builder
+/// Builder for CSV [`Reader`]s
 #[derive(Debug)]
 pub struct ReaderBuilder {
     /// Schema of the CSV file
@@ -1071,9 +1116,10 @@ pub struct ReaderBuilder {
 }
 
 impl ReaderBuilder {
-    /// Create a new builder for configuring CSV parsing options.
+    /// Create a new builder for configuring [`Reader`] CSV parsing options.
     ///
-    /// To convert a builder into a reader, call `ReaderBuilder::build`
+    /// To convert a builder into a reader, call [`ReaderBuilder::build`]. See
+    /// the [module-level documentation](crate::reader) for more details and examples.
     ///
     /// # Example
     ///

arrow-csv/examples/whitespace_handling.rs

@@ -15,13 +15,12 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! CSV Writer
+//! CSV Writing: [`Writer`] and [`WriterBuilder`]
 //!
 //! This CSV writer allows Arrow data (in record batches) to be written as CSV files.
 //! The writer does not support writing `ListArray` and `StructArray`.
 //!
 //! # Example
-//!
 //! ```
 //! # use arrow_array::*;
 //! # use arrow_array::types::*;
@@ -75,14 +74,13 @@
 //! - `DataType::LargeUtf8`
 //! - `DataType::Utf8View`
 //!
-//! ## Example with whitespace handling
+//! ## Example: Use [`WriterBuilder`] to control whitespace handling
 //!
 //! ```
 //! # use arrow_array::*;
 //! # use arrow_csv::WriterBuilder;
 //! # use arrow_schema::*;
 //! # use std::sync::Arc;
-//!
 //! let schema = Schema::new(vec![
 //!     Field::new("name", DataType::Utf8, false),
 //!     Field::new("comment", DataType::Utf8, false),
@@ -105,17 +103,6 @@
 //! )
 //! .unwrap();
 //!
-//! // Default behavior (no trimming)
-//! let mut output = Vec::new();
-//! WriterBuilder::new()
-//!     .build(&mut output)
-//!     .write(&batch)
-//!     .unwrap();
-//! assert_eq!(
-//!     String::from_utf8(output).unwrap(),
-//!     "name,comment\n  Alice  ,  Great job!  \nBob,Well done\n  Charlie,Excellent  \n"
-//! );
-//!
 //! // Trim both leading and trailing whitespace
 //! let mut output = Vec::new();
 //! WriterBuilder::new()
@@ -126,19 +113,11 @@
 //!     .unwrap();
 //! assert_eq!(
 //!     String::from_utf8(output).unwrap(),
-//!     "name,comment\nAlice,Great job!\nBob,Well done\nCharlie,Excellent\n"
-//! );
-//!
-//! // Trim only leading whitespace
-//! let mut output = Vec::new();
-//! WriterBuilder::new()
-//!     .with_ignore_leading_whitespace(true)
-//!     .build(&mut output)
-//!     .write(&batch)
-//!     .unwrap();
-//! assert_eq!(
-//!     String::from_utf8(output).unwrap(),
-//!     "name,comment\nAlice  ,Great job!  \nBob,Well done\nCharlie,Excellent  \n"
+//!     "\
+//! name,comment\n\
+//! Alice,Great job!\n\
+//! Bob,Well done\n\
+//! Charlie,Excellent\n"
 //! );
 //! ```
 //!
@@ -220,6 +199,8 @@ const DEFAULT_NULL_VALUE: &str = "";
 pub use csv::QuoteStyle;
 
 /// A CSV writer
+///
+/// See the [module documentation](crate::writer) for examples.
 #[derive(Debug)]
 pub struct Writer<W: Write> {
     /// The object to write to
@@ -248,12 +229,15 @@ pub struct Writer<W: Write> {
 
 impl<W: Write> Writer<W> {
     /// Create a new CsvWriter from a writable object, with default options
+    ///
+    /// See [`WriterBuilder`] for configure options, and the [module
+    /// documentation](crate::writer) for examples.
     pub fn new(writer: W) -> Self {
         let delimiter = b',';
         WriterBuilder::new().with_delimiter(delimiter).build(writer)
     }
 
-    /// Write a RecordBatch to a writable object
+    /// Write a RecordBatch to the underlying writer
     pub fn write(&mut self, batch: &RecordBatch) -> Result<(), ArrowError> {
         let num_columns = batch.num_columns();
         if self.beginning {
@@ -418,9 +402,10 @@ impl Default for WriterBuilder {
 }
 
 impl WriterBuilder {
-    /// Create a new builder for configuring CSV writing options.
+    /// Create a new builder for configuring CSV [`Writer`] options.
     ///
-    /// To convert a builder into a writer, call `WriterBuilder::build`
+    /// To convert a builder into a writer, call [`WriterBuilder::build`]. See
+    /// the [module documentation](crate::writer) for more examples.
     ///
     /// # Example
     ///