Doc improvements

arrow-array/src/arithmetic.rs

@@ -45,61 +45,83 @@ pub trait ArrowNativeTypeOp: ArrowNativeType {
     /// The multiplicative identity
     const ONE: Self;
 
+    /// A checked add operation
     fn add_checked(self, rhs: Self) -> Result<Self, ArrowError>;
 
+    /// A wrapping add operation
     fn add_wrapping(self, rhs: Self) -> Self;
 
+    /// A checked subtract operation
     fn sub_checked(self, rhs: Self) -> Result<Self, ArrowError>;
 
+    /// A wrapping subtract operation
     fn sub_wrapping(self, rhs: Self) -> Self;
 
+    /// A checked multiplication operation
     fn mul_checked(self, rhs: Self) -> Result<Self, ArrowError>;
 
+    /// A wrapping multiplication operation
     fn mul_wrapping(self, rhs: Self) -> Self;
 
+    /// A checked division operation
     fn div_checked(self, rhs: Self) -> Result<Self, ArrowError>;
 
+    /// A wrapping division operation
     fn div_wrapping(self, rhs: Self) -> Self;
 
+    /// A checked modulo operation
     fn mod_checked(self, rhs: Self) -> Result<Self, ArrowError>;
 
+    /// A wrapping modulo operation
     fn mod_wrapping(self, rhs: Self) -> Self;
 
+    /// A checked negation operation
     fn neg_checked(self) -> Result<Self, ArrowError>;
 
+    /// A wrapping negation operation
     fn neg_wrapping(self) -> Self;
 
+    /// A checked exponentiation operation
     fn pow_checked(self, exp: u32) -> Result<Self, ArrowError>;
 
+    /// A wrapping exponentiation operation
     fn pow_wrapping(self, exp: u32) -> Self;
 
+    /// Returns true if zero else false
     fn is_zero(self) -> bool;
 
+    /// A compare operation
     fn compare(self, rhs: Self) -> Ordering;
 
+    /// A equality operation
     fn is_eq(self, rhs: Self) -> bool;
 
     #[inline]
+    /// A not equal operation
     fn is_ne(self, rhs: Self) -> bool {
         !self.is_eq(rhs)
     }
 
     #[inline]
+    /// A less than operation
     fn is_lt(self, rhs: Self) -> bool {
         self.compare(rhs).is_lt()
     }
 
     #[inline]
+    /// A less than equals operation
     fn is_le(self, rhs: Self) -> bool {
         self.compare(rhs).is_le()
     }
 
     #[inline]
+    /// A greater than operation
     fn is_gt(self, rhs: Self) -> bool {
         self.compare(rhs).is_gt()
     }
 
     #[inline]
+    /// A greater than equals operation
     fn is_ge(self, rhs: Self) -> bool {
         self.compare(rhs).is_ge()
     }

arrow-array/src/array/boolean_array.rs

@@ -91,7 +91,7 @@ impl BooleanArray {
         self.data.is_empty()
     }
 
-    // Returns a new boolean array builder
+    /// Returns a new boolean array builder
     pub fn builder(capacity: usize) -> BooleanBuilder {
         BooleanBuilder::with_capacity(capacity)
     }

arrow-array/src/array/list_array.rs

@@ -29,7 +29,9 @@ use std::any::Any;
 
 /// trait declaring an offset size, relevant for i32 vs i64 array types.
 pub trait OffsetSizeTrait: ArrowNativeType + std::ops::AddAssign + Integer {
+    /// True for 64 bit size and false for 32 bit size
     const IS_LARGE: bool;
+    /// Prefix for the offset size
     const PREFIX: &'static str;
 }
 

arrow-array/src/array/mod.rs

@@ -382,6 +382,7 @@ impl<'a, T: Array> Array for &'a T {
 /// The value at null indexes is unspecified, and implementations must not rely on a specific
 /// value such as [`Default::default`] being returned, however, it must not be undefined
 pub trait ArrayAccessor: Array {
+    /// The Arrow type of the element being accessed.
     type Item: Send + Sync;
 
     /// Returns the element at index `i`

arrow-array/src/array/primitive_array.rs

@@ -165,21 +165,48 @@ pub type TimestampMicrosecondArray = PrimitiveArray<TimestampMicrosecondType>;
 /// A primitive array where each element is of type `TimestampNanosecondType.`
 /// See examples for [`TimestampSecondArray.`](crate::array::TimestampSecondArray)
 pub type TimestampNanosecondArray = PrimitiveArray<TimestampNanosecondType>;
+
+// TODO: give examples for the below types
+
+/// A primitive array where each element is of 32-bit date type.
 pub type Date32Array = PrimitiveArray<Date32Type>;
+/// A primitive array where each element is of 64-bit date type.
 pub type Date64Array = PrimitiveArray<Date64Type>;
+
+/// An array where each element is of 32-bit type representing time elapsed in seconds
+/// since midnight.
 pub type Time32SecondArray = PrimitiveArray<Time32SecondType>;
+/// An array where each element is of 32-bit type representing time elapsed in milliseconds
+/// since midnight.
 pub type Time32MillisecondArray = PrimitiveArray<Time32MillisecondType>;
+/// An array where each element is of 64-bit type representing time elapsed in microseconds
+/// since midnight.
 pub type Time64MicrosecondArray = PrimitiveArray<Time64MicrosecondType>;
+/// An array where each element is of 64-bit type representing time elapsed in nanoseconds
+/// since midnight.
 pub type Time64NanosecondArray = PrimitiveArray<Time64NanosecondType>;
+
+/// An array where each element is a “calendar” interval in months.
 pub type IntervalYearMonthArray = PrimitiveArray<IntervalYearMonthType>;
+/// An array where each element is a “calendar” interval days and milliseconds.
 pub type IntervalDayTimeArray = PrimitiveArray<IntervalDayTimeType>;
+/// An array where each element is a “calendar” interval in  months, days, and nanoseconds.
 pub type IntervalMonthDayNanoArray = PrimitiveArray<IntervalMonthDayNanoType>;
+
+/// An array where each element is an elapsed time type in seconds.
 pub type DurationSecondArray = PrimitiveArray<DurationSecondType>;
+/// An array where each element is an elapsed time type in milliseconds.
 pub type DurationMillisecondArray = PrimitiveArray<DurationMillisecondType>;
+/// An array where each element is an elapsed time type in microseconds.
 pub type DurationMicrosecondArray = PrimitiveArray<DurationMicrosecondType>;
+/// An array where each element is an elapsed time type in nanoseconds.
 pub type DurationNanosecondArray = PrimitiveArray<DurationNanosecondType>;
 
+/// An array where each element is a 128-bits decimal with precision in [1, 38] and
+/// scale in [0, 38].
 pub type Decimal128Array = PrimitiveArray<Decimal128Type>;
+/// An array where each element is a 128-bits decimal with precision in [1, 64] and
+/// scale in [0, 64].
 pub type Decimal256Array = PrimitiveArray<Decimal256Type>;
 
 /// Trait bridging the dynamic-typed nature of Arrow (via [`DataType`]) with the
@@ -256,7 +283,7 @@ impl<T: ArrowPrimitiveType> PrimitiveArray<T> {
         }
     }
 
-    // Returns a new primitive array builder
+    /// Returns a new primitive array builder
     pub fn builder(capacity: usize) -> PrimitiveBuilder<T> {
         PrimitiveBuilder::<T>::with_capacity(capacity)
     }
@@ -749,6 +776,7 @@ impl<'a, T: ArrowPrimitiveType> PrimitiveArray<T> {
 /// the type can be collected to `PrimitiveArray`.
 #[derive(Debug)]
 pub struct NativeAdapter<T: ArrowPrimitiveType> {
+    /// Corresponding Rust native type if available
     pub native: Option<T::Native>,
 }
 

arrow-array/src/builder/boolean_buffer_builder.rs

@@ -19,31 +19,36 @@ use arrow_buffer::{bit_util, Buffer, MutableBuffer};
 use arrow_data::bit_mask;
 use std::ops::Range;
 
+/// A builder for creating a boolean [`Buffer`]
 #[derive(Debug)]
 pub struct BooleanBufferBuilder {
     buffer: MutableBuffer,
     len: usize,
 }
 
 impl BooleanBufferBuilder {
+    /// Creates a new `BooleanBufferBuilder`
     #[inline]
     pub fn new(capacity: usize) -> Self {
         let byte_capacity = bit_util::ceil(capacity, 8);
         let buffer = MutableBuffer::new(byte_capacity);
         Self { buffer, len: 0 }
     }
 
+    /// Creates a new `BooleanBufferBuilder` from [`MutableBuffer`] of `len`
     pub fn new_from_buffer(buffer: MutableBuffer, len: usize) -> Self {
         assert!(len <= buffer.len() * 8);
         Self { buffer, len }
     }
 
     #[inline]
+    /// Returns the length of the buffer
     pub fn len(&self) -> usize {
         self.len
     }
 
     #[inline]
+    /// Sets a bit in the buffer at `index`
     pub fn set_bit(&mut self, index: usize, v: bool) {
         if v {
             bit_util::set_bit(self.buffer.as_mut(), index);
@@ -53,21 +58,25 @@ impl BooleanBufferBuilder {
     }
 
     #[inline]
+    /// Gets a bit in the buffer at `index`
     pub fn get_bit(&self, index: usize) -> bool {
         bit_util::get_bit(self.buffer.as_slice(), index)
     }
 
     #[inline]
+    /// Returns true if empty
     pub fn is_empty(&self) -> bool {
         self.len == 0
     }
 
     #[inline]
+    /// Returns the capacity of the buffer
     pub fn capacity(&self) -> usize {
         self.buffer.capacity() * 8
     }
 
     #[inline]
+    /// Advances the buffer by `additional` bits
     pub fn advance(&mut self, additional: usize) {
         let new_len = self.len + additional;
         let new_len_bytes = bit_util::ceil(new_len, 8);
@@ -100,6 +109,7 @@ impl BooleanBufferBuilder {
     }
 
     #[inline]
+    /// Appends a boolean `v` into the buffer
     pub fn append(&mut self, v: bool) {
         self.advance(1);
         if v {
@@ -108,6 +118,7 @@ impl BooleanBufferBuilder {
     }
 
     #[inline]
+    /// Appends n `additional` bits of value `v` into the buffer
     pub fn append_n(&mut self, additional: usize, v: bool) {
         self.advance(additional);
         if additional > 0 && v {
@@ -119,6 +130,7 @@ impl BooleanBufferBuilder {
     }
 
     #[inline]
+    /// Appends a slice of booleans into the buffer
     pub fn append_slice(&mut self, slice: &[bool]) {
         let additional = slice.len();
         self.advance(additional);
@@ -157,6 +169,7 @@ impl BooleanBufferBuilder {
     }
 
     #[inline]
+    /// Creates a [`Buffer`]
     pub fn finish(&mut self) -> Buffer {
         let buf = std::mem::replace(&mut self.buffer, MutableBuffer::new(0));
         self.len = 0;

arrow-array/src/builder/buffer_builder.rs

@@ -21,47 +21,78 @@ use std::marker::PhantomData;
 
 use crate::types::*;
 
+/// A signed 8-bit integer buffer builder.
 pub type Int8BufferBuilder = BufferBuilder<i8>;
+/// A signed 16-bit integer buffer builder.
 pub type Int16BufferBuilder = BufferBuilder<i16>;
+/// A signed 32-bit integer buffer builder.
 pub type Int32BufferBuilder = BufferBuilder<i32>;
+/// A signed 64-bit integer buffer builder.
 pub type Int64BufferBuilder = BufferBuilder<i64>;
+/// An usigned 8-bit integer buffer builder.
 pub type UInt8BufferBuilder = BufferBuilder<u8>;
+/// An usigned 16-bit integer buffer builder.
 pub type UInt16BufferBuilder = BufferBuilder<u16>;
+/// An usigned 32-bit integer buffer builder.
 pub type UInt32BufferBuilder = BufferBuilder<u32>;
+/// An usigned 64-bit integer buffer builder.
 pub type UInt64BufferBuilder = BufferBuilder<u64>;
+/// A 32-bit floating point buffer builder.
 pub type Float32BufferBuilder = BufferBuilder<f32>;
+/// A 64-bit floating point buffer builder.
 pub type Float64BufferBuilder = BufferBuilder<f64>;
 
+/// A timestamp second array builder.
 pub type TimestampSecondBufferBuilder =
     BufferBuilder<<TimestampSecondType as ArrowPrimitiveType>::Native>;
+/// A timestamp millisecond array builder.
 pub type TimestampMillisecondBufferBuilder =
     BufferBuilder<<TimestampMillisecondType as ArrowPrimitiveType>::Native>;
+/// A timestamp microsecond array builder.
 pub type TimestampMicrosecondBufferBuilder =
     BufferBuilder<<TimestampMicrosecondType as ArrowPrimitiveType>::Native>;
+/// A timestamp nanosecond array builder.
 pub type TimestampNanosecondBufferBuilder =
     BufferBuilder<<TimestampNanosecondType as ArrowPrimitiveType>::Native>;
+
+/// A 32-bit date array builder.
 pub type Date32BufferBuilder = BufferBuilder<<Date32Type as ArrowPrimitiveType>::Native>;
+/// A 64-bit date array builder.
 pub type Date64BufferBuilder = BufferBuilder<<Date64Type as ArrowPrimitiveType>::Native>;
+
+/// A 32-bit elaspsed time in seconds array builder.
 pub type Time32SecondBufferBuilder =
     BufferBuilder<<Time32SecondType as ArrowPrimitiveType>::Native>;
+/// A 32-bit elaspsed time in milliseconds array builder.   
 pub type Time32MillisecondBufferBuilder =
     BufferBuilder<<Time32MillisecondType as ArrowPrimitiveType>::Native>;
+/// A 64-bit elaspsed time in microseconds array builder.
 pub type Time64MicrosecondBufferBuilder =
     BufferBuilder<<Time64MicrosecondType as ArrowPrimitiveType>::Native>;
+/// A 64-bit elaspsed time in nanoseconds array builder.
 pub type Time64NanosecondBufferBuilder =
     BufferBuilder<<Time64NanosecondType as ArrowPrimitiveType>::Native>;
+
+/// A “calendar” interval in months array builder.
 pub type IntervalYearMonthBufferBuilder =
     BufferBuilder<<IntervalYearMonthType as ArrowPrimitiveType>::Native>;
+/// A “calendar” interval in days and milliseconds array builder.
 pub type IntervalDayTimeBufferBuilder =
     BufferBuilder<<IntervalDayTimeType as ArrowPrimitiveType>::Native>;
+/// A “calendar” interval in months, days, and nanoseconds array builder.
 pub type IntervalMonthDayNanoBufferBuilder =
     BufferBuilder<<IntervalMonthDayNanoType as ArrowPrimitiveType>::Native>;
+
+/// An elapsed time in seconds array builder.
 pub type DurationSecondBufferBuilder =
     BufferBuilder<<DurationSecondType as ArrowPrimitiveType>::Native>;
+/// An elapsed time in milliseconds array builder.
 pub type DurationMillisecondBufferBuilder =
     BufferBuilder<<DurationMillisecondType as ArrowPrimitiveType>::Native>;
+/// An elapsed time in microseconds array builder.
 pub type DurationMicrosecondBufferBuilder =
     BufferBuilder<<DurationMicrosecondType as ArrowPrimitiveType>::Native>;
+/// An elapsed time in nanoseconds array builder.
 pub type DurationNanosecondBufferBuilder =
     BufferBuilder<<DurationNanosecondType as ArrowPrimitiveType>::Native>;
 
@@ -124,6 +155,7 @@ impl<T: ArrowNativeType> BufferBuilder<T> {
         }
     }
 
+    /// Creates a new builder from a [`MutableBuffer`]
     pub fn new_from_buffer(buffer: MutableBuffer) -> Self {
         let buffer_len = buffer.len();
         Self {

arrow-array/src/builder/fixed_size_binary_builder.rs

@@ -23,6 +23,18 @@ use arrow_schema::{ArrowError, DataType};
 use std::any::Any;
 use std::sync::Arc;
 
+/// A fixed size binary array builder
+/// ```
+/// use arrow_array::builder::FixedSizeBinaryBuilder;
+///
+/// let mut builder = FixedSizeBinaryBuilder::with_capacity(3, 5);
+/// // [b"hello", null, "arrow"]
+/// builder.append_value(b"hello").unwrap();
+/// builder.append_null();
+/// builder.append_value(b"arrow").unwrap();
+/// // Create the array
+/// let array = builder.finish();
+/// ```
 #[derive(Debug)]
 pub struct FixedSizeBinaryBuilder {
     values_builder: UInt8BufferBuilder,