Improve docs and examples for DataTypeExt and FieldExt (#18271)

## Which issue does this PR close?

- Follow on to #17986 from
@paleolimbot


## Rationale for this change

As we thread Field through more of the DataFusion APs, making it easy to
convert back and forth with Field will be increasingly important. We
added some helper methods in
#17986, but I think they could
be better documented (I wrote them so this is not a dig at @paleolimbot
!)

Lets add some more documentation and examples so it is clearer what this
code is doing.

## What changes are included in this PR?

1. Add more Documentation and examples so it is clearer what this code
is doing.


## Are these changes tested?

By CI

## Are there any user-facing changes?
More docs, no functional changes

Author: alamb

datafusion/common/src/datatype.rs

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! [DataTypeExt] extension trait for converting DataTypes to Fields
+//! [`DataTypeExt`] and [`FieldExt`] extension trait for working with DataTypes to Fields
 
 use crate::arrow::datatypes::{DataType, Field, FieldRef};
 use std::sync::Arc;
@@ -27,9 +27,23 @@ pub trait DataTypeExt {
     /// This is used to track the places where we convert a [`DataType`]
     /// into a nameless field to interact with an API that is
     /// capable of representing an extension type and/or nullability.
+    ///
+    /// For example, it will convert a `DataType::Int32` into
+    /// `Field::new("", DataType::Int32, true)`.
+    ///
+    /// ```
+    /// # use datafusion_common::datatype::DataTypeExt;
+    /// # use arrow::datatypes::DataType;
+    /// let dt = DataType::Utf8;
+    /// let field = dt.into_nullable_field();
+    /// // result is a nullable Utf8 field with "" name
+    /// assert_eq!(field.name(), "");
+    /// assert_eq!(field.data_type(), &DataType::Utf8);
+    /// assert!(field.is_nullable());
+    /// ```
     fn into_nullable_field(self) -> Field;
 
-    /// Convert the type to field ref with nullable type and "" name
+    /// Convert the type to [`FieldRef`] with nullable type and "" name
     ///
     /// Concise wrapper around [`DataTypeExt::into_nullable_field`] that
     /// constructs a [`FieldRef`].
@@ -46,20 +60,74 @@ impl DataTypeExt for DataType {
     }
 }
 
-/// DataFusion extension methods for Arrow [`Field`]
+/// DataFusion extension methods for Arrow [`Field`] and [`FieldRef`]
 pub trait FieldExt {
     /// Returns a new Field representing a List of this Field's DataType.
+    ///
+    /// For example if input represents an `Int32`, the return value will
+    /// represent a `List<Int32>`.
+    ///
+    /// Example:
+    /// ```
+    /// # use std::sync::Arc;
+    /// # use arrow::datatypes::{DataType, Field};
+    /// # use datafusion_common::datatype::FieldExt;
+    /// // Int32 field
+    /// let int_field = Field::new("my_int", DataType::Int32, true);
+    /// // convert to a List field
+    /// let list_field = int_field.into_list();
+    /// // List<Int32>
+    /// // Note that the item field name has been renamed to "item"
+    /// assert_eq!(list_field.data_type(), &DataType::List(Arc::new(
+    ///     Field::new("item", DataType::Int32, true)
+    /// )));
+    ///
     fn into_list(self) -> Self;
 
-    /// Return a new Field representing this Field as the item type of a FixedSizeList
+    /// Return a new Field representing this Field as the item type of a
+    /// [`DataType::FixedSizeList`]
+    ///
+    /// For example if input represents an `Int32`, the return value will
+    /// represent a `FixedSizeList<Int32, size>`.
+    ///
+    /// Example:
+    /// ```
+    /// # use std::sync::Arc;
+    /// # use arrow::datatypes::{DataType, Field};
+    /// # use datafusion_common::datatype::FieldExt;
+    /// // Int32 field
+    /// let int_field = Field::new("my_int", DataType::Int32, true);
+    /// // convert to a FixedSizeList field of size 3
+    /// let fixed_size_list_field = int_field.into_fixed_size_list(3);
+    /// // FixedSizeList<Int32, 3>
+    /// // Note that the item field name has been renamed to "item"
+    /// assert_eq!(
+    ///   fixed_size_list_field.data_type(),
+    ///   &DataType::FixedSizeList(Arc::new(
+    ///    Field::new("item", DataType::Int32, true)),
+    ///    3
+    /// ));
+    ///
     fn into_fixed_size_list(self, list_size: i32) -> Self;
 
-    /// Create a field with the default list field name ("item")
+    /// Update the field to have the default list field name ("item")
+    ///
+    /// Lists are allowed to have an arbitrarily named field; however, a name
+    /// other than 'item' will cause it to fail an == check against a more
+    /// idiomatically created list in arrow-rs which causes issues.
+    ///
+    /// For example, if input represents an `Int32` field named "my_int",
+    /// the return value will represent an `Int32` field named "item".
     ///
-    /// Note that lists are allowed to have an arbitrarily named field;
-    /// however, a name other than 'item' will cause it to fail an
-    /// == check against a more idiomatically created list in
-    /// arrow-rs which causes issues.
+    /// Example:
+    /// ```
+    /// # use arrow::datatypes::Field;
+    /// # use datafusion_common::datatype::FieldExt;
+    /// let my_field = Field::new("my_int", arrow::datatypes::DataType::Int32, true);
+    /// let item_field = my_field.into_list_item();
+    /// assert_eq!(item_field.name(), Field::LIST_FIELD_DEFAULT_NAME);
+    /// assert_eq!(item_field.name(), "item");
+    /// ```
     fn into_list_item(self) -> Self;
 }