Add Field::new_list_item and improve DataType::new_list docs

arrow-schema/src/datatype.rs

@@ -577,9 +577,14 @@ impl DataType {
         }
     }
 
-    /// Create a List DataType default name is "item"
+    /// Create a [`DataType::List`] where each elements has the
+    /// specified type and nullability and coventional name
+    /// (`"item"`);
+    ///
+    /// To specify field level metadata, construct the inner `Field`
+    /// directly via [`Field::new`] or [`Field::new_list_item`].
     pub fn new_list(data_type: DataType, nullable: bool) -> Self {
-        DataType::List(Arc::new(Field::new("item", data_type, nullable)))
+        DataType::List(Arc::new(Field::new_list_item(data_type, nullable)))
     }
 }
 

arrow-schema/src/field.rs

@@ -117,7 +117,7 @@ impl Hash for Field {
 }
 
 impl Field {
-    /// Creates a new field
+    /// Creates a new field with the given name, type, and nullability
     pub fn new(name: impl Into<String>, data_type: DataType, nullable: bool) -> Self {
         Field {
             name: name.into(),
@@ -129,6 +129,24 @@ impl Field {
         }
     }
 
+    /// Creates a new field suitable for [`DataType::List`] and
+    /// [`DataType::LargeList`]
+    ///
+    /// While not required, by convention the inner `Field` of these
+    /// types is named `"item"`
+    ///
+    /// # Example
+    /// ```
+    /// # use arrow_schema::{Field, DataType};
+    /// assert_eq!(
+    ///   Field::new("item", DataType::Int32, true),
+    ///   Field::new_list_item(DataType::Int32, true)
+    /// );
+    /// ```
+    pub fn new_list_item(data_type: DataType, nullable: bool) -> Self {
+        Self::new("item", data_type, nullable)
+    }
+
     /// Creates a new field that has additional dictionary information
     pub fn new_dict(
         name: impl Into<String>,