Added more docs.

src/array/boolean/from.rs

@@ -4,6 +4,13 @@ use crate::trusted_len::TrustedLen;
 
 use super::{BooleanArray, MutableBooleanArray};
 
+impl<P: AsRef<[Option<bool>]>> From<P> for BooleanArray {
+    /// Creates a new [`BooleanArray`] out of a slice of Optional `bool`.
+    fn from(slice: P) -> Self {
+        MutableBooleanArray::from(slice).into()
+    }
+}
+
 impl BooleanArray {
     /// Creates a new [`BooleanArray`] from an [`TrustedLen`] of `bool`.
     #[inline]

src/array/boolean/iterator.rs

@@ -14,7 +14,7 @@ impl<'a> IntoIterator for &'a BooleanArray {
 }
 
 impl<'a> BooleanArray {
-    /// constructs a new iterator
+    /// Returns an iterator over the optional values of this [`BooleanArray`].
     #[inline]
     pub fn iter(&'a self) -> ZipValidity<'a, bool, BitmapIter<'a>> {
         zip_validity(
@@ -23,7 +23,7 @@ impl<'a> BooleanArray {
         )
     }
 
-    /// Returns an iterator of `bool`
+    /// Returns an iterator over the values of this [`BooleanArray`]
     #[inline]
     pub fn values_iter(&'a self) -> BitmapIter<'a> {
         self.values().iter()
@@ -41,7 +41,7 @@ impl<'a> IntoIterator for &'a MutableBooleanArray {
 }
 
 impl<'a> MutableBooleanArray {
-    /// Returns an iterator over `Option<bool>`
+    /// Returns an iterator over the optional values of this [`MutableBooleanArray`].
     #[inline]
     pub fn iter(&'a self) -> ZipValidity<'a, bool, BitmapIter<'a>> {
         zip_validity(
@@ -50,7 +50,7 @@ impl<'a> MutableBooleanArray {
         )
     }
 
-    /// Returns an iterator of `bool`
+    /// Returns an iterator over the values of this [`MutableBooleanArray`]
     #[inline]
     pub fn values_iter(&'a self) -> BitmapIter<'a> {
         self.values().iter()

src/array/boolean/mod.rs

@@ -10,8 +10,8 @@ mod mutable;
 pub use iterator::*;
 pub use mutable::*;
 
-/// A [`BooleanArray`] is arrow's equivalent to an immutable `Vec<Option<bool>>`, i.e.
-/// The size of this struct is `O(1)` as all data is stored behind an `Arc`, and
+/// The Arrow's equivalent to an immutable `Vec<Option<bool>>`, but with `1/16` of its size.
+/// Cloning and slicing this struct is `O(1)`.
 #[derive(Debug, Clone)]
 pub struct BooleanArray {
     values: Bitmap,
@@ -51,7 +51,7 @@ impl BooleanArray {
 
     /// Returns a slice of this [`BooleanArray`].
     /// # Implementation
-    /// This operation is `O(1)` as it amounts to essentially increase two ref counts.
+    /// This operation is `O(1)` as it amounts to increase two ref counts.
     /// # Panic
     /// This function panics iff `offset + length >= self.len()`.
     #[inline]
@@ -64,22 +64,23 @@ impl BooleanArray {
         }
     }
 
-    /// Returns the element at index `i` as bool
+    /// Returns the value at index `i`
+    /// # Panic
+    /// This function panics iff `i >= self.len()`.
     #[inline]
     pub fn value(&self, i: usize) -> bool {
         self.values.get_bit(i)
     }
 
     /// Returns the element at index `i` as bool
-    ///
     /// # Safety
     /// Caller must be sure that `i < self.len()`
     #[inline]
     pub unsafe fn value_unchecked(&self, i: usize) -> bool {
         self.values.get_bit_unchecked(i)
     }
 
-    /// Returns the values bitmap of this [`BooleanArray`].
+    /// Returns the values of this [`BooleanArray`].
     #[inline]
     pub fn values(&self) -> &Bitmap {
         &self.values
@@ -118,10 +119,3 @@ impl std::fmt::Display for BooleanArray {
         display_fmt(self.iter(), "BooleanArray", f, false)
     }
 }
-
-impl<P: AsRef<[Option<bool>]>> From<P> for BooleanArray {
-    /// Creates a new [`BooleanArray`] out of a slice of Optional `bool`.
-    fn from(slice: P) -> Self {
-        MutableBooleanArray::from(slice).into()
-    }
-}

src/array/boolean/mutable.rs

@@ -12,7 +12,8 @@ use crate::{
 
 use super::BooleanArray;
 
-/// The mutable version of [`BooleanArray`]. See [`MutableArray`] for more details.
+/// The Arrow's equivalent to `Vec<Option<bool>>`, but with `1/16` of its size.
+/// Converting a [`MutableBooleanArray`] into a [`BooleanArray`] is `O(1)`.
 #[derive(Debug)]
 pub struct MutableBooleanArray {
     values: MutableBitmap,

src/array/primitive/mod.rs

@@ -20,6 +20,15 @@ pub use mutable::*;
 /// an array designed for highly performant operations on optionally nullable slots,
 /// backed by a physical type of a physical byte-width, such as `i32` or `f64`.
 /// The size of this struct is `O(1)` as all data is stored behind an [`std::sync::Arc`].
+/// # Example
+/// ```
+/// use arrow2::array::PrimitiveArray;
+/// # fn main() {
+/// let array = Utf8Array::<i32>::from([Some(1), None, Some(2)]);
+/// assert_eq!(array.value(0), 1);
+/// assert_eq!(array.values().as_slice(), &[1, 0, 2]);
+/// # }
+/// ```
 #[derive(Debug, Clone)]
 pub struct PrimitiveArray<T: NativeType> {
     data_type: DataType,

src/array/primitive/mutable.rs

@@ -12,7 +12,8 @@ use crate::{
 
 use super::PrimitiveArray;
 
-/// The mutable version of [`PrimitiveArray`]. See [`MutableArray`] for more details.
+/// The Arrow's equivalent to `Vec<Option<T>>` where `T` is byte-size (e.g. `i32`).
+/// Converting a [`MutablePrimitiveArray`] into a [`PrimitiveArray`] is `O(1)`.
 #[derive(Debug)]
 pub struct MutablePrimitiveArray<T: NativeType> {
     data_type: DataType,

src/array/utf8/mod.rs

@@ -13,17 +13,16 @@ mod mutable;
 pub use iterator::*;
 pub use mutable::*;
 
-/// A [`Utf8Array`] is arrow's equivalent of `Vec<Option<String>>`, i.e.
-/// an array designed for highly performant operations on optionally nullable strings.
-/// The size of this struct is `O(1)` as all data is stored behind an `Arc`.
+/// A [`Utf8Array`] is arrow's equivalent of an immutable `Vec<Option<String>>`.
+/// Cloning and slicing this struct is `O(1)`.
 /// # Example
 /// ```
-/// use std::iter::FromIterator;
 /// use arrow2::array::Utf8Array;
 /// # fn main() {
-/// let data = vec![Some("hello"), None, Some("hello2")];
-/// let array = Utf8Array::<i32>::from_iter(data);
-/// assert_eq!(array.value(0), "hello");
+/// let array = Utf8Array::<i32>::from([Some("hi"), None, Some("there")]);
+/// assert_eq!(array.value(0), "hi");
+/// assert_eq!(array.values(), b"hithere");
+/// assert_eq!(array.offsets().as_slice(), &[0, 2, 2, 2 + 5]);
 /// # }
 /// ```
 #[derive(Debug, Clone)]