Added more API docs. (#479)

src/compute/aggregate/mod.rs

@@ -1,3 +1,4 @@
+//! Contains different aggregation functions
 mod sum;
 pub use sum::*;
 

src/compute/aggregate/sum.rs

@@ -16,6 +16,7 @@ use crate::{
 /// Object that can reduce itself to a number. This is used in the context of SIMD to reduce
 /// a MD (e.g. `[f32; 16]`) into a single number (`f32`).
 pub trait Sum<T> {
+    /// Reduces this element to a single value.
     fn simd_sum(self) -> T;
 }
 
@@ -116,6 +117,7 @@ macro_rules! dyn_sum {
     }};
 }
 
+/// Whether [`sum`] is valid for `data_type`
 pub fn can_sum(data_type: &DataType) -> bool {
     use DataType::*;
     matches!(

src/compute/boolean.rs

@@ -1,20 +1,4 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements.  See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership.  The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License.  You may obtain a copy of the License at
-//
-//   http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied.  See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
+//! null-preserving operators such as [`and`], [`or`] and [`not`].
 use crate::array::{Array, BooleanArray};
 use crate::bitmap::{Bitmap, MutableBitmap};
 use crate::datatypes::DataType;

src/compute/boolean_kleene.rs

@@ -1,3 +1,4 @@
+//! Boolean operators of [Kleene logic](https://en.wikipedia.org/wiki/Three-valued_logic#Kleene_and_Priest_logics).
 use crate::datatypes::DataType;
 use crate::error::{ArrowError, Result};
 use crate::{

src/compute/cast/binary_to.rs

@@ -3,13 +3,15 @@ use std::convert::TryFrom;
 use crate::error::{ArrowError, Result};
 use crate::{array::*, buffer::Buffer, datatypes::DataType, types::NativeType};
 
+/// Conversion of binary
 pub fn binary_to_large_binary(from: &BinaryArray<i32>, to_data_type: DataType) -> BinaryArray<i64> {
     let values = from.values().clone();
     let offsets = from.offsets().iter().map(|x| *x as i64);
     let offsets = Buffer::from_trusted_len_iter(offsets);
     BinaryArray::<i64>::from_data(to_data_type, offsets, values, from.validity().cloned())
 }
 
+/// Conversion of binary
 pub fn binary_large_to_binary(
     from: &BinaryArray<i64>,
     to_data_type: DataType,

src/compute/cast/mod.rs

@@ -1,19 +1,4 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements.  See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership.  The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License.  You may obtain a copy of the License at
-//
-//   http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied.  See the License for the
-// specific language governing permissions and limitations
-// under the License.
+//! Defines different casting operators such as [`cast`] or [`primitive_to_binary`].
 
 use crate::{
     array::*,

src/compute/cast/primitive_to.rs

@@ -181,30 +181,37 @@ const fn time_unit_multiple(unit: TimeUnit) -> i64 {
     }
 }
 
+/// Conversion of dates
 pub fn date32_to_date64(from: &PrimitiveArray<i32>) -> PrimitiveArray<i64> {
     unary(from, |x| x as i64 * MILLISECONDS_IN_DAY, DataType::Date64)
 }
 
+/// Conversion of dates
 pub fn date64_to_date32(from: &PrimitiveArray<i64>) -> PrimitiveArray<i32> {
     unary(from, |x| (x / MILLISECONDS_IN_DAY) as i32, DataType::Date32)
 }
 
+/// Conversion of times
 pub fn time32s_to_time32ms(from: &PrimitiveArray<i32>) -> PrimitiveArray<i32> {
     unary(from, |x| x * 1000, DataType::Time32(TimeUnit::Millisecond))
 }
 
+/// Conversion of times
 pub fn time32ms_to_time32s(from: &PrimitiveArray<i32>) -> PrimitiveArray<i32> {
     unary(from, |x| x / 1000, DataType::Time32(TimeUnit::Second))
 }
 
+/// Conversion of times
 pub fn time64us_to_time64ns(from: &PrimitiveArray<i64>) -> PrimitiveArray<i64> {
     unary(from, |x| x * 1000, DataType::Time64(TimeUnit::Nanosecond))
 }
 
+/// Conversion of times
 pub fn time64ns_to_time64us(from: &PrimitiveArray<i64>) -> PrimitiveArray<i64> {
     unary(from, |x| x / 1000, DataType::Time64(TimeUnit::Microsecond))
 }
 
+/// Conversion of timestamp
 pub fn timestamp_to_date64(from: &PrimitiveArray<i64>, from_unit: TimeUnit) -> PrimitiveArray<i64> {
     let from_size = time_unit_multiple(from_unit);
     let to_size = MILLISECONDS;
@@ -221,11 +228,13 @@ pub fn timestamp_to_date64(from: &PrimitiveArray<i64>, from_unit: TimeUnit) -> P
     }
 }
 
+/// Conversion of timestamp
 pub fn timestamp_to_date32(from: &PrimitiveArray<i64>, from_unit: TimeUnit) -> PrimitiveArray<i32> {
     let from_size = time_unit_multiple(from_unit) * SECONDS_IN_DAY;
     unary(from, |x| (x / from_size) as i32, DataType::Date32)
 }
 
+/// Conversion of time
 pub fn time32_to_time64(
     from: &PrimitiveArray<i32>,
     from_unit: TimeUnit,
@@ -237,6 +246,7 @@ pub fn time32_to_time64(
     unary(from, |x| (x as i64 * divisor), DataType::Time64(to_unit))
 }
 
+/// Conversion of time
 pub fn time64_to_time32(
     from: &PrimitiveArray<i64>,
     from_unit: TimeUnit,
@@ -252,6 +262,7 @@ pub fn time64_to_time32(
     )
 }
 
+/// Conversion of timestamp
 pub fn timestamp_to_timestamp(
     from: &PrimitiveArray<i64>,
     from_unit: TimeUnit,

src/compute/cast/utf8_to.rs

@@ -120,6 +120,7 @@ pub fn utf8_to_timestamp_ns<O: Offset>(
     utf8_to_timestamp_ns_(from, RFC3339, timezone)
 }
 
+/// Conversion of utf8
 pub fn utf8_to_large_utf8(from: &Utf8Array<i32>) -> Utf8Array<i64> {
     let data_type = Utf8Array::<i64>::default_data_type();
     let values = from.values().clone();
@@ -130,6 +131,7 @@ pub fn utf8_to_large_utf8(from: &Utf8Array<i32>) -> Utf8Array<i64> {
     }
 }
 
+/// Conversion of utf8
 pub fn utf8_large_to_utf8(from: &Utf8Array<i64>) -> Result<Utf8Array<i32>> {
     let data_type = Utf8Array::<i32>::default_data_type();
     let values = from.values().clone();

src/compute/comparison/mod.rs

@@ -103,11 +103,17 @@ pub use utf8::compare_scalar as utf8_compare_scalar;
 /// Comparison operators, such as `>` ([`Operator::Gt`])
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum Operator {
+    /// Less than
     Lt,
+    /// Less than or equal to
     LtEq,
+    /// Greater than
     Gt,
+    /// Greater than or equal to
     GtEq,
+    /// Equal
     Eq,
+    /// Not equal
     Neq,
 }
 

src/compute/comparison/simd/mod.rs

@@ -2,17 +2,27 @@ use crate::types::NativeType;
 
 /// [`NativeType`] that supports a representation of 8 lanes
 pub trait Simd8: NativeType {
+    /// The 8 lane representation of `Self`
     type Simd: Simd8Lanes<Self>;
 }
 
+/// Trait declaring an 8-lane multi-data.
 pub trait Simd8Lanes<T>: Copy {
+    /// loads a complete chunk
     fn from_chunk(v: &[T]) -> Self;
+    /// loads an incomplete chunk, filling the remaining items with `remaining`.
     fn from_incomplete_chunk(v: &[T], remaining: T) -> Self;
+    /// Equal
     fn eq(self, other: Self) -> u8;
+    /// Not equal
     fn neq(self, other: Self) -> u8;
+    /// Less than or equal to
     fn lt_eq(self, other: Self) -> u8;
+    /// Less than
     fn lt(self, other: Self) -> u8;
+    /// Greater than
     fn gt(self, other: Self) -> u8;
+    /// Greater than or equal to
     fn gt_eq(self, other: Self) -> u8;
 }
 

src/compute/contains.rs

@@ -1,19 +1,4 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements.  See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership.  The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License.  You may obtain a copy of the License at
-//
-//   http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied.  See the License for the
-// specific language governing permissions and limitations
-// under the License.
+//! Declares the [`contains`] operator
 
 use crate::types::NativeType;
 use crate::{
@@ -141,6 +126,7 @@ macro_rules! primitive {
     }};
 }
 
+/// Returns whether each element in `values` is in each element from `list`
 pub fn contains(list: &dyn Array, values: &dyn Array) -> Result<BooleanArray> {
     let list_data_type = list.data_type();
     let values_data_type = values.data_type();

src/compute/filter.rs

@@ -1,20 +1,4 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements.  See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership.  The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License.  You may obtain a copy of the License at
-//
-//   http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied.  See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
+//! Contains operators to filter arrays such as [`filter`].
 use crate::array::growable::{make_growable, Growable};
 use crate::bitmap::{utils::SlicesIterator, Bitmap, MutableBitmap};
 use crate::record_batch::RecordBatch;

src/compute/hash.rs

@@ -1,3 +1,4 @@
+//! Contains the [`hash`] and typed (e.g. [`hash_primitive`]) operators.
 use ahash::{CallHasher, RandomState};
 use multiversion::multiversion;
 use std::hash::Hash;
@@ -18,18 +19,18 @@ use crate::{
 
 use super::arity::unary;
 
-/// Element-wise hash of a [`PrimitiveArray`]. Validity is preserved.
 #[multiversion]
 #[clone(target = "x86_64+aes+sse3+ssse3+avx+avx2")]
+/// Element-wise hash of a [`PrimitiveArray`]. Validity is preserved.
 pub fn hash_primitive<T: NativeType + Hash>(array: &PrimitiveArray<T>) -> PrimitiveArray<u64> {
     let state = new_state!();
 
     unary(array, |x| T::get_hash(&x, &state), DataType::UInt64)
 }
 
-/// Element-wise hash of a [`BooleanArray`]. Validity is preserved.
 #[multiversion]
 #[clone(target = "x86_64+aes+sse3+ssse3+avx+avx2")]
+/// Element-wise hash of a [`BooleanArray`]. Validity is preserved.
 pub fn hash_boolean(array: &BooleanArray) -> PrimitiveArray<u64> {
     let state = new_state!();
 

src/compute/if_then_else.rs

@@ -1,3 +1,4 @@
+//! Contains the operator [`if_then_else`].
 use crate::array::growable;
 use crate::error::{ArrowError, Result};
 use crate::{array::*, bitmap::utils::SlicesIterator};

src/compute/like.rs

@@ -1,3 +1,4 @@
+//! Contains "like" operators such as [`like_utf8`] and [`like_utf8_scalar`].
 use std::collections::HashMap;
 
 use regex::bytes::Regex as BytesRegex;
@@ -83,6 +84,12 @@ pub fn like_utf8<O: Offset>(lhs: &Utf8Array<O>, rhs: &Utf8Array<O>) -> Result<Bo
     a_like_utf8(lhs, rhs, |x| x)
 }
 
+/// Returns `lhs NOT LIKE rhs` operation on two [`Utf8Array`].
+///
+/// There are two wildcards supported:
+///
+/// * `%` - The percent sign represents zero, one, or multiple characters
+/// * `_` - The underscore represents a single character
 pub fn nlike_utf8<O: Offset>(lhs: &Utf8Array<O>, rhs: &Utf8Array<O>) -> Result<BooleanArray> {
     a_like_utf8(lhs, rhs, |x| !x)
 }
@@ -146,6 +153,12 @@ pub fn like_utf8_scalar<O: Offset>(lhs: &Utf8Array<O>, rhs: &str) -> Result<Bool
     a_like_utf8_scalar(lhs, rhs, |x| x)
 }
 
+/// Returns `lhs NOT LIKE rhs` operation.
+///
+/// There are two wildcards supported:
+///
+/// * `%` - The percent sign represents zero, one, or multiple characters
+/// * `_` - The underscore represents a single character
 pub fn nlike_utf8_scalar<O: Offset>(lhs: &Utf8Array<O>, rhs: &str) -> Result<BooleanArray> {
     a_like_utf8_scalar(lhs, rhs, |x| !x)
 }
@@ -221,6 +234,13 @@ pub fn like_binary<O: Offset>(lhs: &BinaryArray<O>, rhs: &BinaryArray<O>) -> Res
     a_like_binary(lhs, rhs, |x| x)
 }
 
+/// Returns `lhs NOT LIKE rhs` operation on two [`BinaryArray`]s.
+///
+/// There are two wildcards supported:
+///
+/// * `%` - The percent sign represents zero, one, or multiple characters
+/// * `_` - The underscore represents a single character
+///
 pub fn nlike_binary<O: Offset>(lhs: &BinaryArray<O>, rhs: &BinaryArray<O>) -> Result<BooleanArray> {
     a_like_binary(lhs, rhs, |x| !x)
 }
@@ -290,6 +310,13 @@ pub fn like_binary_scalar<O: Offset>(lhs: &BinaryArray<O>, rhs: &[u8]) -> Result
     a_like_binary_scalar(lhs, rhs, |x| x)
 }
 
+/// Returns `lhs NOT LIKE rhs` operation on two [`BinaryArray`]s.
+///
+/// There are two wildcards supported:
+///
+/// * `%` - The percent sign represents zero, one, or multiple characters
+/// * `_` - The underscore represents a single character
+///
 pub fn nlike_binary_scalar<O: Offset>(lhs: &BinaryArray<O>, rhs: &[u8]) -> Result<BooleanArray> {
     a_like_binary_scalar(lhs, rhs, |x| !x)
 }

src/compute/limit.rs

@@ -1,23 +1,8 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements.  See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership.  The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License.  You may obtain a copy of the License at
-//
-//   http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied.  See the License for the
-// specific language governing permissions and limitations
-// under the License.
+//! Contains the operator [`limit`].
 
 use crate::array::Array;
 
-/// Returns the array, taking only the number of elements specified
+/// Returns the [`Array`] limited by `num_elements`.
 ///
 /// Limit performs a zero-copy slice of the array, and is a convenience method on slice
 /// where:

src/compute/merge_sort/mod.rs

@@ -233,8 +233,8 @@ fn recursive_merge_sort(slices: &[&[MergeSlice]], comparator: &Comparator) -> Ve
     merge_sort_slices(lhs.iter(), rhs.iter(), comparator).collect::<Vec<_>>()
 }
 
-// An iterator adapter that merge-sorts two iterators of `MergeSlice` into a single `MergeSlice`
-// such that the resulting `MergeSlice`s are ordered according to `comparator`.
+/// An iterator adapter that merge-sorts two iterators of `MergeSlice` into a single `MergeSlice`
+/// such that the resulting `MergeSlice`s are ordered according to `comparator`.
 pub struct MergeSortSlices<'a, L, R>
 where
     L: Iterator<Item = &'a MergeSlice>,

src/compute/nullif.rs

@@ -1,3 +1,4 @@
+//! Contains the operator [`nullif`].
 use crate::array::PrimitiveArray;
 use crate::bitmap::Bitmap;
 use crate::compute::arithmetics::basic::check_same_type;