Update docs (apache#4071)

arrow-array/src/array/binary_array.rs

@@ -23,8 +23,7 @@ use arrow_buffer::{bit_util, Buffer, MutableBuffer};
 use arrow_data::ArrayData;
 use arrow_schema::DataType;
 
-/// See [`BinaryArray`] and [`LargeBinaryArray`] for storing
-/// binary data.
+/// See [`BinaryArray`] and [`LargeBinaryArray`] for storing binary data
 pub type GenericBinaryArray<OffsetSize> = GenericByteArray<GenericBinaryType<OffsetSize>>;
 
 impl<OffsetSize: OffsetSizeTrait> GenericBinaryArray<OffsetSize> {
@@ -218,7 +217,8 @@ where
     }
 }
 
-/// An array where each element contains 0 or more bytes.
+/// An array of `[u8]` using `i32` offsets
+///
 /// The byte length of each element is represented by an i32.
 ///
 /// # Examples
@@ -258,8 +258,7 @@ where
 ///
 pub type BinaryArray = GenericBinaryArray<i32>;
 
-/// An array where each element contains 0 or more bytes.
-/// The byte length of each element is represented by an i64.
+/// An array of `[u8]` using `i64` offsets
 ///
 /// # Examples
 ///

arrow-array/src/array/boolean_array.rs

@@ -25,7 +25,7 @@ use arrow_schema::DataType;
 use std::any::Any;
 use std::sync::Arc;
 
-/// Array of bools
+/// An array of [boolean values](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-primitive-layout)
 ///
 /// # Example
 ///

arrow-array/src/array/byte_array.rs

@@ -28,7 +28,7 @@ use arrow_schema::{ArrowError, DataType};
 use std::any::Any;
 use std::sync::Arc;
 
-/// Generic struct for variable-size byte arrays
+/// An array of [variable length byte arrays](https://arrow.apache.org/docs/format/Columnar.html#variable-size-binary-layout)
 ///
 /// See [`StringArray`] and [`LargeStringArray`] for storing utf8 encoded string data
 ///

arrow-array/src/array/dictionary_array.rs

@@ -30,8 +30,7 @@ use arrow_schema::{ArrowError, DataType};
 use std::any::Any;
 use std::sync::Arc;
 
-///
-/// A dictionary array where each element is a single value indexed by an integer key.
+/// A dictionary array indexed by `i8`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -44,8 +43,8 @@ use std::sync::Arc;
 /// assert_eq!(array.values(), &values);
 /// ```
 pub type Int8DictionaryArray = DictionaryArray<Int8Type>;
-///
-/// A dictionary array where each element is a single value indexed by an integer key.
+
+/// A dictionary array indexed by `i16`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -58,8 +57,8 @@ pub type Int8DictionaryArray = DictionaryArray<Int8Type>;
 /// assert_eq!(array.values(), &values);
 /// ```
 pub type Int16DictionaryArray = DictionaryArray<Int16Type>;
-///
-/// A dictionary array where each element is a single value indexed by an integer key.
+
+/// A dictionary array indexed by `i32`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -72,8 +71,8 @@ pub type Int16DictionaryArray = DictionaryArray<Int16Type>;
 /// assert_eq!(array.values(), &values);
 /// ```
 pub type Int32DictionaryArray = DictionaryArray<Int32Type>;
-///
-/// A dictionary array where each element is a single value indexed by an integer key.
+
+/// A dictionary array indexed by `i64`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -86,8 +85,8 @@ pub type Int32DictionaryArray = DictionaryArray<Int32Type>;
 /// assert_eq!(array.values(), &values);
 /// ```
 pub type Int64DictionaryArray = DictionaryArray<Int64Type>;
-///
-/// A dictionary array where each element is a single value indexed by an integer key.
+
+/// A dictionary array indexed by `u8`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -100,8 +99,8 @@ pub type Int64DictionaryArray = DictionaryArray<Int64Type>;
 /// assert_eq!(array.values(), &values);
 /// ```
 pub type UInt8DictionaryArray = DictionaryArray<UInt8Type>;
-///
-/// A dictionary array where each element is a single value indexed by an integer key.
+
+/// A dictionary array indexed by `u16`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -114,8 +113,8 @@ pub type UInt8DictionaryArray = DictionaryArray<UInt8Type>;
 /// assert_eq!(array.values(), &values);
 /// ```
 pub type UInt16DictionaryArray = DictionaryArray<UInt16Type>;
-///
-/// A dictionary array where each element is a single value indexed by an integer key.
+
+/// A dictionary array indexed by `u32`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -128,8 +127,8 @@ pub type UInt16DictionaryArray = DictionaryArray<UInt16Type>;
 /// assert_eq!(array.values(), &values);
 /// ```
 pub type UInt32DictionaryArray = DictionaryArray<UInt32Type>;
-///
-/// A dictionary array where each element is a single value indexed by an integer key.
+
+/// A dictionary array indexed by `u64`
 ///
 /// # Example: Using `collect`
 /// ```
@@ -143,7 +142,8 @@ pub type UInt32DictionaryArray = DictionaryArray<UInt32Type>;
 /// ```
 pub type UInt64DictionaryArray = DictionaryArray<UInt64Type>;
 
-/// A dictionary array where each element is a single value indexed by an integer key.
+/// An array of [dictionary encoded values](https://arrow.apache.org/docs/format/Columnar.html#dictionary-encoded-layout)
+///
 /// This is mostly used to represent strings or a limited set of primitive types as integers,
 /// for example when doing NLP analysis or representing chromosomes by name.
 ///
@@ -695,8 +695,9 @@ impl<T: ArrowDictionaryKeyType> std::fmt::Debug for DictionaryArray<T> {
     }
 }
 
-/// A strongly-typed wrapper around a [`DictionaryArray`] that implements [`ArrayAccessor`]
-/// allowing fast access to its elements
+/// A [`DictionaryArray`] typed on its child values array
+///
+/// Implements [`ArrayAccessor`] allowing fast access to its elements
 ///
 /// ```
 /// use arrow_array::{DictionaryArray, StringArray, types::Int32Type};

arrow-array/src/array/fixed_size_binary_array.rs

@@ -25,7 +25,7 @@ use arrow_schema::{ArrowError, DataType};
 use std::any::Any;
 use std::sync::Arc;
 
-/// An array where each element is a fixed-size sequence of bytes.
+/// An array of [fixed size binary arrays](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-primitive-layout)
 ///
 /// # Examples
 ///

arrow-array/src/array/fixed_size_list_array.rs

@@ -24,8 +24,7 @@ use arrow_schema::DataType;
 use std::any::Any;
 use std::sync::Arc;
 
-/// A list array where each element is a fixed-size sequence of values with the same
-/// type whose maximum length is represented by a i32.
+/// An array of [fixed size arrays](https://arrow.apache.org/docs/format/Columnar.html#fixed-size-list-layout)
 ///
 /// # Example
 ///
@@ -59,9 +58,6 @@ use std::sync::Arc;
 /// assert_eq!( &[3, 4, 5], list1.as_any().downcast_ref::<Int32Array>().unwrap().values());
 /// assert_eq!( &[6, 7, 8], list2.as_any().downcast_ref::<Int32Array>().unwrap().values());
 /// ```
-///
-/// For non generic lists, you may wish to consider using
-/// [crate::array::FixedSizeBinaryArray]
 #[derive(Clone)]
 pub struct FixedSizeListArray {
     data_type: DataType, // Must be DataType::FixedSizeList(value_length)

arrow-array/src/array/list_array.rs

@@ -28,7 +28,7 @@ use num::Integer;
 use std::any::Any;
 use std::sync::Arc;
 
-/// trait declaring an offset size, relevant for i32 vs i64 array types.
+/// A type that can be used within a variable-size array to encode offset information
 pub trait OffsetSizeTrait: ArrowNativeType + std::ops::AddAssign + Integer {
     /// True for 64 bit offset size and false for 32 bit offset size
     const IS_LARGE: bool;
@@ -46,12 +46,9 @@ impl OffsetSizeTrait for i64 {
     const PREFIX: &'static str = "Large";
 }
 
-/// Generic struct for a variable-size list array.
+/// An array of [variable length arrays](https://arrow.apache.org/docs/format/Columnar.html#variable-size-list-layout)
 ///
-/// Columnar format in Apache Arrow:
-/// <https://arrow.apache.org/docs/format/Columnar.html#variable-size-list-layout>
-///
-/// For non generic lists, you may wish to consider using [`ListArray`] or [`LargeListArray`]`
+/// See [`ListArray`] and [`LargeListArray`]`
 pub struct GenericListArray<OffsetSize: OffsetSizeTrait> {
     data_type: DataType,
     nulls: Option<NullBuffer>,
@@ -447,8 +444,7 @@ impl<OffsetSize: OffsetSizeTrait> std::fmt::Debug for GenericListArray<OffsetSiz
     }
 }
 
-/// A list array where each element is a variable-sized sequence of values with the same
-/// type whose memory offsets between elements are represented by a i32.
+/// An array of variable size arrays, storing offsets as `i32`.
 ///
 /// # Example
 ///
@@ -475,8 +471,8 @@ impl<OffsetSize: OffsetSizeTrait> std::fmt::Debug for GenericListArray<OffsetSiz
 /// ```
 pub type ListArray = GenericListArray<i32>;
 
-/// A list array where each element is a variable-sized sequence of values with the same
-/// type whose memory offsets between elements are represented by a i64.
+/// An array of variable size arrays, storing offsets as `i64`.
+///
 /// # Example
 ///
 /// ```

arrow-array/src/array/map_array.rs

@@ -23,7 +23,8 @@ use arrow_schema::{ArrowError, DataType, Field};
 use std::any::Any;
 use std::sync::Arc;
 
-/// A nested array type where each record is a key-value map.
+/// An array of key-value maps
+///
 /// Keys should always be non-null, but values can be null.
 ///
 /// [MapArray] is physically a [crate::array::ListArray] that has a

arrow-array/src/array/mod.rs

@@ -67,8 +67,7 @@ pub use union_array::*;
 mod run_array;
 pub use run_array::*;
 
-/// Trait for dealing with different types of array at runtime when the type of the
-/// array is not known in advance.
+/// An array in the [arrow columnar format](https://arrow.apache.org/docs/format/Columnar.html)
 pub trait Array: std::fmt::Debug + Send + Sync {
     /// Returns the array as [`Any`](std::any::Any) so that it can be
     /// downcasted to a specific implementation.
@@ -237,7 +236,7 @@ pub trait Array: std::fmt::Debug + Send + Sync {
     fn get_array_memory_size(&self) -> usize;
 }
 
-/// A reference-counted reference to a generic `Array`.
+/// A reference-counted reference to a generic `Array`
 pub type ArrayRef = Arc<dyn Array>;
 
 /// Ergonomics: Allow use of an ArrayRef as an `&dyn Array`

arrow-array/src/array/null_array.rs

@@ -24,7 +24,7 @@ use arrow_schema::DataType;
 use std::any::Any;
 use std::sync::Arc;
 
-/// An Array where all elements are nulls
+/// An array of [null values](https://arrow.apache.org/docs/format/Columnar.html#null-layout)
 ///
 /// A `NullArray` is a simplified array where all values are null.
 ///