Merge fea52de into 4dfbca6

arrow/src/array/array.rs

@@ -324,11 +324,35 @@ pub fn make_array(data: ArrayData) -> ArrayRef {
 }
 
 /// Creates a new empty array
+///
+/// ```
+/// use std::sync::Arc;
+/// use arrow::datatypes::DataType;
+/// use arrow::array::{ArrayRef, Int32Array, new_empty_array};
+///
+/// let empty_array = new_empty_array(&DataType::Int32);
+/// let array: ArrayRef = Arc::new(Int32Array::from(vec![] as Vec<i32>));
+///
+/// assert_eq!(&array, &empty_array);
+/// ```
 pub fn new_empty_array(data_type: &DataType) -> ArrayRef {
     let data = ArrayData::new_empty(data_type);
     make_array(data)
 }
-/// Creates a new array of `data_type` of length `length` filled entirely of `NULL` values
+
+/// Creates a new array of `data_type` of length `length` filled
+/// entirely of `NULL` values
+///
+/// ```
+/// use std::sync::Arc;
+/// use arrow::datatypes::DataType;
+/// use arrow::array::{ArrayRef, Int32Array, new_null_array};
+///
+/// let null_array = new_null_array(&DataType::Int32, 3);
+/// let array: ArrayRef = Arc::new(Int32Array::from(vec![None, None, None]));
+///
+/// assert_eq!(&array, &null_array);
+/// ```
 pub fn new_null_array(data_type: &DataType, length: usize) -> ArrayRef {
     // context: https://github.com/apache/arrow/pull/9469#discussion_r574761687
     match data_type {

arrow/src/array/null.rs

@@ -16,23 +16,6 @@
 // under the License.
 
 //! Contains the `NullArray` type.
-//!
-//! A `NullArray` is a simplified array where all values are null.
-//!
-//! # Example: Create an array
-//!
-//! ```
-//! use arrow::array::{Array, NullArray};
-//!
-//! # fn main() -> arrow::error::Result<()> {
-//! let array = NullArray::new(10);
-//!
-//! assert_eq!(array.len(), 10);
-//! assert_eq!(array.null_count(), 10);
-//!
-//! # Ok(())
-//! # }
-//! ```
 
 use std::any::Any;
 use std::fmt;
@@ -42,12 +25,33 @@ use crate::array::{Array, ArrayData};
 use crate::datatypes::*;
 
 /// An Array where all elements are nulls
+///
+/// A `NullArray` is a simplified array where all values are null.
+///
+/// # Example: Create an array
+///
+/// ```
+/// use arrow::array::{Array, NullArray};
+///
+/// # fn main() -> arrow::error::Result<()> {
+/// let array = NullArray::new(10);
+///
+/// assert_eq!(array.len(), 10);
+/// assert_eq!(array.null_count(), 10);
+///
+/// # Ok(())
+/// # }
+/// ```
 pub struct NullArray {
     data: ArrayData,
 }
 
 impl NullArray {
-    /// Create a new null array of the specified length
+    /// Create a new [`NullArray`] of the specified length
+    ///
+    /// *Note*: Use [`crate::array::new_null_array`] if you need an array of some
+    /// other [`DataType`].
+    ///
     pub fn new(length: usize) -> Self {
         let array_data = ArrayData::builder(DataType::Null).len(length).build();
         NullArray::from(array_data)