Added more docs.

src/alloc/mod.rs

@@ -32,7 +32,7 @@ mod alignment;
 pub use alignment::ALIGNMENT;
 
 // If this number is not zero after all objects have been `drop`, there is a memory leak
-pub static mut ALLOCATIONS: AtomicIsize = AtomicIsize::new(0);
+static mut ALLOCATIONS: AtomicIsize = AtomicIsize::new(0);
 
 /// Returns the total number of bytes allocated to buffers by the allocator.
 pub fn total_allocated_bytes() -> isize {

src/array/binary/from.rs

@@ -10,11 +10,12 @@ use crate::{
 use super::{BinaryArray, MutableBinaryArray};
 
 impl<O: Offset> BinaryArray<O> {
+    /// Creates a new [`BinaryArray`] from slices of `&[u8]`.
     pub fn from_slice<T: AsRef<[u8]>, P: AsRef<[T]>>(slice: P) -> Self {
         Self::from_iter(slice.as_ref().iter().map(Some))
     }
 
-    /// Creates a new [`BinaryArray`] from a slice of `&[u8]`.
+    /// Creates a new [`BinaryArray`] from a slice of optional `&[u8]`.
     // Note: this can't be `impl From` because Rust does not allow double `AsRef` on it.
     pub fn from<T: AsRef<[u8]>, P: AsRef<[Option<T>]>>(slice: P) -> Self {
         Self::from_trusted_len_iter(slice.as_ref().iter().map(|x| x.as_ref()))

src/array/binary/mutable.rs

@@ -10,7 +10,10 @@ use crate::{
 
 use super::BinaryArray;
 
-/// The mutable version of [`BinaryArray`].
+/// The Arrow's equivalent to `Vec<Option<Vec<u8>>>`.
+/// Converting a [`MutableBinaryArray`] into a [`BinaryArray`] is `O(1)`.
+/// # Implementation
+/// This struct does not allocate a validity until one is required (i.e. push a null to it).
 #[derive(Debug)]
 pub struct MutableBinaryArray<O: Offset> {
     offsets: MutableBuffer<O>,
@@ -35,10 +38,16 @@ impl<O: Offset> Default for MutableBinaryArray<O> {
 }
 
 impl<O: Offset> MutableBinaryArray<O> {
+    /// Creates a new empty [`MutableBinaryArray`].
+    /// # Implementation
+    /// This allocates a [`MutableBuffer`] of one element
     pub fn new() -> Self {
         Self::with_capacity(0)
     }
 
+    /// Creates a new [`MutableBinaryArray`] with capacity for `capacity` values.
+    /// # Implementation
+    /// This does not allocate the validity.
     pub fn with_capacity(capacity: usize) -> Self {
         let mut offsets = MutableBuffer::<O>::with_capacity(capacity + 1);
         offsets.push(O::default());
@@ -49,6 +58,7 @@ impl<O: Offset> MutableBinaryArray<O> {
         }
     }
 
+    /// Reserves `additional` slots.
     pub fn reserve(&mut self, additional: usize) {
         self.offsets.reserve(additional);
         if let Some(x) = self.validity.as_mut() {

src/array/boolean/mutable.rs

@@ -13,6 +13,8 @@ use super::BooleanArray;
 
 /// The Arrow's equivalent to `Vec<Option<bool>>`, but with `1/16` of its size.
 /// Converting a [`MutableBooleanArray`] into a [`BooleanArray`] is `O(1)`.
+/// # Implementation
+/// This struct does not allocate a validity until one is required (i.e. push a null to it).
 #[derive(Debug)]
 pub struct MutableBooleanArray {
     values: MutableBitmap,
@@ -39,28 +41,33 @@ impl Default for MutableBooleanArray {
 }
 
 impl MutableBooleanArray {
+    /// Creates an new empty [`MutableBooleanArray`].
     pub fn new() -> Self {
         Self::with_capacity(0)
     }
 
+    /// Creates an new [`MutableBooleanArray`] with a capacity of values.
     pub fn with_capacity(capacity: usize) -> Self {
         Self {
             values: MutableBitmap::with_capacity(capacity),
             validity: None,
         }
     }
 
+    /// Reserves `additional` slots.
     pub fn reserve(&mut self, additional: usize) {
         self.values.reserve(additional);
         if let Some(x) = self.validity.as_mut() {
             x.reserve(additional)
         }
     }
 
+    /// Canonical method to create a new [`MutableBooleanArray`].
     pub fn from_data(values: MutableBitmap, validity: Option<MutableBitmap>) -> Self {
         Self { values, validity }
     }
 
+    /// Pushes a new entry to [`MutableBooleanArray`].
     pub fn push(&mut self, value: Option<bool>) {
         match value {
             Some(value) => {

src/array/dictionary/mutable.rs

@@ -43,6 +43,7 @@ impl<K: DictionaryKey, M: MutableArray> From<M> for MutableDictionaryArray<K, M>
 }
 
 impl<K: DictionaryKey, M: MutableArray + Default> MutableDictionaryArray<K, M> {
+    /// Creates an empty [`MutableDictionaryArray`].
     pub fn new() -> Self {
         let values = M::default();
         Self {
@@ -83,18 +84,22 @@ impl<K: DictionaryKey, M: MutableArray> MutableDictionaryArray<K, M> {
         }
     }
 
+    /// pushes a null value
     pub fn push_null(&mut self) {
         self.keys.push(None)
     }
 
+    /// returns a mutable reference to the inner values.
     pub fn mut_values(&mut self) -> &mut M {
         &mut self.values
     }
 
+    /// returns a reference to the inner values.
     pub fn values(&self) -> &M {
         &self.values
     }
 
+    /// converts itself into `Arc<dyn Array>`
     pub fn into_arc(self) -> Arc<dyn Array> {
         let a: DictionaryArray<K> = self.into();
         Arc::new(a)

src/array/ffi.rs

@@ -23,6 +23,7 @@ pub unsafe trait ToFfi {
 /// Trait describing how a struct imports into itself from the
 /// [C data interface](https://arrow.apache.org/docs/format/CDataInterface.html) (FFI).
 pub unsafe trait FromFfi<T: ffi::ArrowArrayRef>: Sized {
+    /// Convert itself from FFI.
     fn try_from_ffi(array: T) -> Result<Self>;
 }
 

src/array/fixed_size_binary/mod.rs

@@ -6,6 +6,8 @@ mod iterator;
 mod mutable;
 pub use mutable::*;
 
+/// The Arrow's equivalent to an immutable `Vec<Option<[u8; size]>>`.
+/// Cloning and slicing this struct is `O(1)`.
 #[derive(Debug, Clone)]
 pub struct FixedSizeBinaryArray {
     size: i32, // this is redundant with `data_type`, but useful to not have to deconstruct the data_type.
@@ -16,12 +18,12 @@ pub struct FixedSizeBinaryArray {
 }
 
 impl FixedSizeBinaryArray {
-    #[inline]
+    /// Returns a new empty [`FixedSizeBinaryArray`].
     pub fn new_empty(data_type: DataType) -> Self {
         Self::from_data(data_type, Buffer::new(), None)
     }
 
-    #[inline]
+    /// Returns a new null [`FixedSizeBinaryArray`].
     pub fn new_null(data_type: DataType, length: usize) -> Self {
         Self::from_data(
             data_type,
@@ -30,7 +32,7 @@ impl FixedSizeBinaryArray {
         )
     }
 
-    #[inline]
+    /// Returns a new [`FixedSizeBinaryArray`].
     pub fn from_data(data_type: DataType, values: Buffer<u8>, validity: Option<Bitmap>) -> Self {
         let size = *Self::get_size(&data_type);
 
@@ -45,7 +47,9 @@ impl FixedSizeBinaryArray {
         }
     }
 
-    #[inline]
+    /// Returns a slice of this [`FixedSizeBinaryArray`].
+    /// # Implementation
+    /// This operation is `O(1)` as it amounts to increase 3 ref counts.
     pub fn slice(&self, offset: usize, length: usize) -> Self {
         let validity = self.validity.clone().map(|x| x.slice(offset, length));
         let values = self
@@ -61,11 +65,14 @@ impl FixedSizeBinaryArray {
         }
     }
 
-    #[inline]
+    /// Returns the values allocated on this [`FixedSizeBinaryArray`].
     pub fn values(&self) -> &Buffer<u8> {
         &self.values
     }
 
+    /// Returns value at position `i`.
+    /// # Panic
+    /// Panics iff `i >= self.len()`.
     #[inline]
     pub fn value(&self, i: usize) -> &[u8] {
         &self.values()[i * self.size as usize..(i + 1) * self.size as usize]
@@ -82,7 +89,7 @@ impl FixedSizeBinaryArray {
         )
     }
 
-    #[inline]
+    /// Returns the size
     pub fn size(&self) -> usize {
         self.size as usize
     }
@@ -145,13 +152,15 @@ unsafe impl ToFfi for FixedSizeBinaryArray {
 }
 
 impl FixedSizeBinaryArray {
+    /// Creates a [`FixedSizeBinaryArray`] from an fallible iterator of optional `[u8]`.
     pub fn try_from_iter<P: AsRef<[u8]>, I: IntoIterator<Item = Option<P>>>(
         iter: I,
         size: usize,
     ) -> Result<Self> {
         MutableFixedSizeBinaryArray::try_from_iter(iter, size).map(|x| x.into())
     }
 
+    /// Creates a [`FixedSizeBinaryArray`] from an iterator of optional `[u8]`.
     pub fn from_iter<P: AsRef<[u8]>, I: IntoIterator<Item = Option<P>>>(
         iter: I,
         size: usize,

src/array/fixed_size_binary/mutable.rs

@@ -10,7 +10,10 @@ use crate::{
 
 use super::{FixedSizeBinaryArray, FixedSizeBinaryValues};
 
-/// Mutable version of [`FixedSizeBinaryArray`].
+/// The Arrow's equivalent to a mutable `Vec<Option<[u8; size]>>`.
+/// Converting a [`MutableFixedSizeBinaryArray`] into a [`FixedSizeBinaryArray`] is `O(1)`.
+/// # Implementation
+/// This struct does not allocate a validity until one is required (i.e. push a null to it).
 #[derive(Debug)]
 pub struct MutableFixedSizeBinaryArray {
     data_type: DataType,
@@ -30,6 +33,7 @@ impl From<MutableFixedSizeBinaryArray> for FixedSizeBinaryArray {
 }
 
 impl MutableFixedSizeBinaryArray {
+    /// Canonical method to create a new [`MutableFixedSizeBinaryArray`].
     pub fn from_data(
         size: usize,
         values: MutableBuffer<u8>,
@@ -55,10 +59,12 @@ impl MutableFixedSizeBinaryArray {
         }
     }
 
+    /// Creates a new empty [`MutableFixedSizeBinaryArray`].
     pub fn new(size: usize) -> Self {
         Self::with_capacity(size, 0)
     }
 
+    /// Creates a new [`MutableFixedSizeBinaryArray`] with capacity for `capacity` entries.
     pub fn with_capacity(size: usize, capacity: usize) -> Self {
         Self::from_data(
             size,
@@ -67,6 +73,9 @@ impl MutableFixedSizeBinaryArray {
         )
     }
 
+    /// tries to push a new entry to [`MutableFixedSizeBinaryArray`].
+    /// # Error
+    /// Errors iff the size of `value` is not equal to its own size.
     #[inline]
     pub fn try_push<P: AsRef<[u8]>>(&mut self, value: Option<P>) -> Result<()> {
         match value {
@@ -95,11 +104,17 @@ impl MutableFixedSizeBinaryArray {
         Ok(())
     }
 
+    /// pushes a new entry to [`MutableFixedSizeBinaryArray`].
+    /// # Panics
+    /// Panics iff the size of `value` is not equal to its own size.
     #[inline]
     pub fn push<P: AsRef<[u8]>>(&mut self, value: Option<P>) {
         self.try_push(value).unwrap()
     }
 
+    /// Creates a new [`MutableFixedSizeBinaryArray`] from an iterator of values.
+    /// # Errors
+    /// Errors iff the size of any of the `value` is not equal to its own size.
     pub fn try_from_iter<P: AsRef<[u8]>, I: IntoIterator<Item = Option<P>>>(
         iter: I,
         size: usize,

src/array/fixed_size_list/mod.rs

@@ -12,6 +12,8 @@ pub use iterator::*;
 mod mutable;
 pub use mutable::*;
 
+/// The Arrow's equivalent to an immutable `Vec<Option<[T; size]>>` where `T` is an Arrow type.
+/// Cloning and slicing this struct is `O(1)`.
 #[derive(Debug, Clone)]
 pub struct FixedSizeListArray {
     size: i32, // this is redundant with `data_type`, but useful to not have to deconstruct the data_type.
@@ -22,16 +24,19 @@ pub struct FixedSizeListArray {
 }
 
 impl FixedSizeListArray {
+    /// Returns a new empty [`FixedSizeListArray`].
     pub fn new_empty(data_type: DataType) -> Self {
         let values = new_empty_array(Self::get_child_and_size(&data_type).0.clone()).into();
         Self::from_data(data_type, values, None)
     }
 
+    /// Returns a new null [`FixedSizeListArray`].
     pub fn new_null(data_type: DataType, length: usize) -> Self {
         let values = new_null_array(Self::get_child_and_size(&data_type).0.clone(), length).into();
         Self::from_data(data_type, values, Some(Bitmap::new_zeroed(length)))
     }
 
+    /// Returns a [`FixedSizeListArray`].
     pub fn from_data(
         data_type: DataType,
         values: Arc<dyn Array>,
@@ -50,6 +55,9 @@ impl FixedSizeListArray {
         }
     }
 
+    /// Returns a slice of this [`FixedSizeListArray`].
+    /// # Implementation
+    /// This operation is `O(1)`.
     pub fn slice(&self, offset: usize, length: usize) -> Self {
         let validity = self.validity.clone().map(|x| x.slice(offset, length));
         let values = self
@@ -66,11 +74,12 @@ impl FixedSizeListArray {
         }
     }
 
-    #[inline]
+    /// Returns the inner array.
     pub fn values(&self) -> &Arc<dyn Array> {
         &self.values
     }
 
+    /// Returns the `Vec<T>` at position `i`.
     #[inline]
     pub fn value(&self, i: usize) -> Box<dyn Array> {
         self.values
@@ -87,6 +96,7 @@ impl FixedSizeListArray {
         }
     }
 
+    /// Returns a [`DataType`] consistent with this Array.
     #[inline]
     pub fn default_datatype(data_type: DataType, size: usize) -> DataType {
         let field = Box::new(Field::new("item", data_type, true));

src/array/list/iterator.rs

@@ -4,7 +4,7 @@ use crate::{array::Offset, trusted_len::TrustedLen};
 
 use super::ListArray;
 
-/// Iterator of values of an `ListArray`.
+/// Iterator of values of an [`ListArray`].
 pub struct ListValuesIter<'a, A: IterableListArray> {
     array: &'a A,
     index: usize,

src/array/mod.rs

@@ -26,6 +26,7 @@ use crate::{
 /// A trait representing an immutable Arrow array. Arrow arrays are trait objects
 /// that are infalibly downcasted to concrete types according to the [`Array::data_type`].
 pub trait Array: std::fmt::Debug + Send + Sync {
+    /// Convert to trait object.
     fn as_any(&self) -> &dyn Any;
 
     /// The length of the [`Array`]. Every array has a length corresponding to the number of
@@ -404,6 +405,7 @@ pub use self::ffi::ToFfi;
 /// A trait describing the ability of a struct to create itself from a iterator.
 /// This is similar to [`Extend`], but accepted the creation to error.
 pub trait TryExtend<A> {
+    /// Fallible version of [`Extend::extend`].
     fn try_extend<I: IntoIterator<Item = A>>(&mut self, iter: I) -> Result<()>;
 }
 
@@ -468,10 +470,14 @@ pub trait IterableListArray: Array {
 /// 2. `offsets[i] >= offsets[i-1] for all i`
 /// 3. `offsets[i] < values.len() for all i`
 pub unsafe trait GenericBinaryArray<O: Offset>: Array {
+    /// The values of the array
     fn values(&self) -> &[u8];
+    /// The offsets of the array
     fn offsets(&self) -> &[O];
 }
 
 // backward compatibility
 use std::sync::Arc;
+
+/// A type def of [`Array`].
 pub type ArrayRef = Arc<dyn Array>;