Review feedback

arrow-array/src/array/list_array.rs

@@ -29,6 +29,14 @@ use std::any::Any;
 use std::sync::Arc;
 
 /// A type that can be used within a variable-size array to encode offset information
+///
+/// See [`ListArray`], [`LargeListArray`], [`BinaryArray`], [`LargeBinaryArray`],
+/// [`StringArray`] and [`LargeStringArray`]
+///
+/// [`BinaryArray`]: crate::array::BinaryArray
+/// [`LargeBinaryArray`]: crate::array::LargeBinaryArray
+/// [`StringArray`]: crate::array::StringArray
+/// [`LargeStringArray`]: crate::array::LargeStringArray
 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;
@@ -444,7 +452,7 @@ impl<OffsetSize: OffsetSizeTrait> std::fmt::Debug for GenericListArray<OffsetSiz
     }
 }
 
-/// An array of variable size arrays, storing offsets as `i32`.
+/// An array of variable size lists, storing offsets as `i32`.
 ///
 /// # Example
 ///
@@ -471,7 +479,7 @@ impl<OffsetSize: OffsetSizeTrait> std::fmt::Debug for GenericListArray<OffsetSiz
 /// ```
 pub type ListArray = GenericListArray<i32>;
 
-/// An array of variable size arrays, storing offsets as `i64`.
+/// An array of variable size lists, storing offsets as `i64`.
 ///
 /// # Example
 ///

arrow-array/src/array/primitive_array.rs

@@ -133,8 +133,7 @@ pub type Float32Array = PrimitiveArray<Float32Type>;
 /// ```
 pub type Float64Array = PrimitiveArray<Float64Type>;
 
-/// An array of 64-bit values representing the elapsed time
-/// since UNIX epoch in seconds
+/// An array of seconds since UNIX epoch stored as `i64`
 ///
 /// This type is similar to the [`chrono::DateTime`] type and can hold
 /// values such as `1970-05-09 14:25:11 +01:00`
@@ -182,63 +181,54 @@ pub type Float64Array = PrimitiveArray<Float64Type>;
 ///
 pub type TimestampSecondArray = PrimitiveArray<TimestampSecondType>;
 
-/// An array of 64-bit values representing the elapsed time
-/// since UNIX epoch in milliseconds
+/// An array of milliseconds since UNIX epoch stored as `i64`
 ///
 /// See examples for [`TimestampSecondArray`]
 pub type TimestampMillisecondArray = PrimitiveArray<TimestampMillisecondType>;
 
-/// An array of 64-bit values representing the elapsed time
-/// since UNIX epoch in microseconds
+/// An array of microseconds since UNIX epoch stored as `i64`
 ///
 /// See examples for [`TimestampSecondArray`]
 pub type TimestampMicrosecondArray = PrimitiveArray<TimestampMicrosecondType>;
 
-/// An array of 64-bit values representing the elapsed time
-/// since UNIX epoch in nanoseconds
+/// An array of nanoseconds since UNIX epoch stored as `i64`
 ///
 /// See examples for [`TimestampSecondArray`]
 pub type TimestampNanosecondArray = PrimitiveArray<TimestampNanosecondType>;
 
 // TODO: give examples for the below types
 
-/// An array of 32-bit values representing the elapsed time
-/// since UNIX epoch in days
+/// An array of days since UNIX epoch stored as `i32`
 ///
 /// This type is similar to the [`chrono::NaiveDate`] type and can hold
 /// values such as `2018-11-13`
 pub type Date32Array = PrimitiveArray<Date32Type>;
 
-/// An array of 64-bit values representing the elapsed time
-/// since UNIX epoch in milliseconds
+/// An array of milliseconds since UNIX epoch stored as `i64`
 ///
 /// This type is similar to the [`chrono::NaiveDate`] type and can hold
 /// values such as `2018-11-13`
 pub type Date64Array = PrimitiveArray<Date64Type>;
 
-/// An array of 32-bit values representing the elapsed time
-/// since midnight in seconds
+/// An array of seconds since midnight stored as `i32`
 ///
 /// This type is similar to the [`chrono::NaiveTime`] type and can
 /// hold values such as `00:02:00`
 pub type Time32SecondArray = PrimitiveArray<Time32SecondType>;
 
-/// An array of 32-bit values representing the elapsed time
-/// since midnight in milliseconds
+/// An array of milliseconds since midnight stored as `i32`
 ///
 /// This type is similar to the [`chrono::NaiveTime`] type and can
 /// hold values such as `00:02:00.123`
 pub type Time32MillisecondArray = PrimitiveArray<Time32MillisecondType>;
 
-/// An array of 64-bit values representing the elapsed time
-/// since midnight in microseconds
+/// An array of microseconds since midnight stored as `i64`
 ///
 /// This type is similar to the [`chrono::NaiveTime`] type and can
 /// hold values such as `00:02:00.123456`
 pub type Time64MicrosecondArray = PrimitiveArray<Time64MicrosecondType>;
 
-/// An array of 64-bit values representing the elapsed time
-/// since midnight in nanoseconds
+/// An array of nanoseconds since midnight stored as `i64`
 ///
 /// This type is similar to the [`chrono::NaiveTime`] type and can
 /// hold values such as `00:02:00.123456789`

arrow-array/src/array/struct_array.rs

@@ -22,7 +22,7 @@ use arrow_schema::{ArrowError, DataType, Field, FieldRef, Fields, SchemaBuilder}
 use std::sync::Arc;
 use std::{any::Any, ops::Index};
 
-/// An array of [tuples](https://arrow.apache.org/docs/format/Columnar.html#struct-layout)
+/// An array of [structs](https://arrow.apache.org/docs/format/Columnar.html#struct-layout)
 ///
 /// Each child (called *field*) is represented by a separate array.
 ///

arrow-array/src/lib.rs

@@ -70,19 +70,19 @@
 //!
 //! # Low-level API
 //!
-//! Internally, arrays consist of one or more shared memory regions backed by [`Buffer`],
+//! Internally, arrays consist of one or more shared memory regions backed by a [`Buffer`],
 //! the number and meaning of which depend on the array’s data type, as documented in
 //! the [Arrow specification].
 //!
 //! For example, the type [`Int16Array`] represents an array of 16-bit integers and consists of:
 //!
 //! * An optional [`NullBuffer`] identifying any null values
-//! * A contiguous [`ScalarBuffer<i16>`]
+//! * A contiguous [`ScalarBuffer<i16>`] of values
 //!
 //! Similarly, the type [`StringArray`] represents an array of UTF-8 strings and consists of:
 //!
 //! * An optional [`NullBuffer`] identifying any null values
-//! * An offsets [`ScalarBuffer<i32>`] identifying valid UTF-8 sequences within the values buffer
+//! * An offsets [`OffsetBuffer<i32>`] identifying valid UTF-8 sequences within the values buffer
 //! * A values [`Buffer`] of UTF-8 encoded string data
 //!
 //! Array constructors such as [`PrimitiveArray::try_new`] provide the ability to cheaply
@@ -136,12 +136,15 @@
 //! ```
 //! # use arrow_array::{Array, Float32Array, Int32Array};
 //!
+//! // Safely downcast an `Array` to an `Int32Array` and compute the sum
+//! // using native i32 values
 //! fn sum_int32(array: &dyn Array) -> i32 {
 //!     let integers: &Int32Array = array.as_any().downcast_ref().unwrap();
 //!     integers.iter().map(|val| val.unwrap_or_default()).sum()
 //! }
 //!
-//! // Note: the values for positions corresponding to nulls will be arbitrary
+//! // Safely downcasts the array to a `Float32Array` and returns a &[f32] view of the data
+//! // Note: the values for positions corresponding to nulls will be arbitrary (but still valid f32)
 //! fn as_f32_slice(array: &dyn Array) -> &[f32] {
 //!     array.as_any().downcast_ref::<Float32Array>().unwrap().values()
 //! }
@@ -161,7 +164,7 @@
 //!
 //! [`ScalarBuffer<T>`]: arrow_buffer::ScalarBuffer
 //! [`ScalarBuffer<i16>`]: arrow_buffer::ScalarBuffer
-//! [`ScalarBuffer<i32>`]: arrow_buffer::ScalarBuffer
+//! [`OffsetBuffer<i32>`]: arrow_buffer::OffsetBuffer
 //! [`NullBuffer`]: arrow_buffer::NullBuffer
 //! [Arrow specification]: https://arrow.apache.org/docs/format/Columnar.html
 //! [`&dyn Array`]: Array