Document how to use Extend for generic methods on ArrayBuilders (#6932)

* chore: add docs for how to use Extend for generic methods on ArrayBuilders

* chore: move to mod docs and add more examples

arrow-array/src/builder/mod.rs

@@ -78,6 +78,73 @@
 //! ))
 //! ```
 //!
+//! # Using the [`Extend`] trait to append values from an iterable:
+//!
+//! ```
+//! # use arrow_array::{Array};
+//! # use arrow_array::builder::{ArrayBuilder, StringBuilder};
+//!
+//! let mut builder = StringBuilder::new();
+//! builder.extend(vec![Some("🍐"), Some("🍎"), None]);
+//! assert_eq!(builder.finish().len(), 3);
+//! ```
+//!
+//! # Using the [`Extend`] trait to write generic functions:
+//!
+//! ```
+//! # use arrow_array::{Array, ArrayRef, StringArray};
+//! # use arrow_array::builder::{ArrayBuilder, Int32Builder, ListBuilder, StringBuilder};
+//!
+//! // For generic methods that fill a list of values for an [`ArrayBuilder`], use the [`Extend`] trait.
+//! fn filter_and_fill<V, I: IntoIterator<Item = V>>(builder: &mut impl Extend<V>, values: I, filter: V)
+//! where V: PartialEq
+//! {
+//!     builder.extend(values.into_iter().filter(|v| *v == filter));
+//! }
+//! let mut string_builder = StringBuilder::new();
+//! filter_and_fill(
+//!     &mut string_builder,
+//!     vec![Some("🍐"), Some("🍎"), None],
+//!     Some("🍎"),
+//! );
+//! assert_eq!(string_builder.finish().len(), 1);
+//!
+//! let mut int_builder = Int32Builder::new();
+//! filter_and_fill(
+//!     &mut int_builder,
+//!     vec![Some(11), Some(42), None],
+//!     Some(42),
+//! );
+//! assert_eq!(int_builder.finish().len(), 1);
+//!
+//! // For generic methods that fill lists-of-lists for an [`ArrayBuilder`], use the [`Extend`] trait.
+//! fn filter_and_fill_if_contains<T, V, I: IntoIterator<Item = Option<V>>>(
+//!     list_builder: &mut impl Extend<Option<V>>,
+//!     values: I,
+//!     filter: Option<T>,
+//! ) where
+//!     T: PartialEq,
+//!     for<'a> &'a V: IntoIterator<Item = &'a Option<T>>,
+//! {
+//!     list_builder.extend(values.into_iter().filter(|string: &Option<V>| {
+//!         string
+//!             .as_ref()
+//!             .map(|str: &V| str.into_iter().any(|ch: &Option<T>| ch == &filter))
+//!             .unwrap_or(false)
+//!     }));
+//!  }
+//! let builder = StringBuilder::new();
+//! let mut list_builder = ListBuilder::new(builder);
+//! let pear_pear = vec![Some("🍐"),Some("🍐")];
+//! let pear_app = vec![Some("🍐"),Some("🍎")];
+//! filter_and_fill_if_contains(
+//!     &mut list_builder,
+//!     vec![Some(pear_pear), Some(pear_app), None],
+//!     Some("🍎"),
+//! );
+//! assert_eq!(list_builder.finish().len(), 1);
+//! ```
+//!
 //! # Custom Builders
 //!
 //! It is common to have a collection of statically defined Rust types that
@@ -134,6 +201,8 @@
 //!     }
 //! }
 //!
+//! /// For building arrays in generic code, use Extend instead of the append_* methods
+//! /// e.g. append_value, append_option, append_null
 //! impl<'a> Extend<&'a MyRow> for MyRowBuilder {
 //!     fn extend<T: IntoIterator<Item = &'a MyRow>>(&mut self, iter: T) {
 //!         iter.into_iter().for_each(|row| self.append(row));