chore: add docs, part of #37 (apache#6424)

* chore: add docs, part of #37
- add pragma `#![warn(missing_docs)]` to `arrow`, `arrow-arith`, `arrow-avro`
- add docs to the same to remove lint warnings

* chore: add docs, part of #37
- add pragma `#![warn(missing_docs)]` to `arrow-buffer`, `arrow-cast`, `arrow-csv`
- add docs to the same to remove lint warnings

* chore: update docs, resolve PR comments

Author: ByteBaker

arrow-arith/src/bitwise.rs

@@ -15,6 +15,8 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! Module contains bitwise operations on arrays
+
 use crate::arity::{binary, unary};
 use arrow_array::*;
 use arrow_buffer::ArrowNativeType;

arrow-arith/src/lib.rs

@@ -17,6 +17,7 @@
 
 //! Arrow arithmetic and aggregation kernels
 
+#![warn(missing_docs)]
 pub mod aggregate;
 #[doc(hidden)] // Kernels to be removed in a future release
 pub mod arithmetic;

arrow-array/src/ffi_stream.rs

@@ -83,17 +83,18 @@ const ENOSYS: i32 = 78;
 /// This was created by bindgen
 #[repr(C)]
 #[derive(Debug)]
-#[allow(missing_docs)]
+#[allow(non_camel_case_types)]
 pub struct FFI_ArrowArrayStream {
-    pub get_schema: Option<
-        unsafe extern "C" fn(arg1: *mut FFI_ArrowArrayStream, out: *mut FFI_ArrowSchema) -> c_int,
-    >,
-    pub get_next: Option<
-        unsafe extern "C" fn(arg1: *mut FFI_ArrowArrayStream, out: *mut FFI_ArrowArray) -> c_int,
-    >,
-    pub get_last_error:
-        Option<unsafe extern "C" fn(arg1: *mut FFI_ArrowArrayStream) -> *const c_char>,
-    pub release: Option<unsafe extern "C" fn(arg1: *mut FFI_ArrowArrayStream)>,
+    /// C function to get schema from the stream
+    pub get_schema:
+        Option<unsafe extern "C" fn(arg1: *mut Self, out: *mut FFI_ArrowSchema) -> c_int>,
+    /// C function to get next array from the stream
+    pub get_next: Option<unsafe extern "C" fn(arg1: *mut Self, out: *mut FFI_ArrowArray) -> c_int>,
+    /// C function to get the error from last operation on the stream
+    pub get_last_error: Option<unsafe extern "C" fn(arg1: *mut Self) -> *const c_char>,
+    /// C function to release the stream
+    pub release: Option<unsafe extern "C" fn(arg1: *mut Self)>,
+    /// Private data used by the stream
     pub private_data: *mut c_void,
 }
 

arrow-avro/src/lib.rs

@@ -20,6 +20,7 @@
 //! [Apache Arrow]: https://arrow.apache.org
 //! [Apache Avro]: https://avro.apache.org/
 
+#![warn(missing_docs)]
 #![allow(unused)] // Temporary
 
 pub mod reader;

arrow-buffer/src/bigint/mod.rs

@@ -216,6 +216,7 @@ impl i256 {
         }
     }
 
+    /// Create an `i256` value from a 128-bit value.
     pub const fn from_i128(v: i128) -> Self {
         Self::from_parts(v as u128, v >> 127)
     }

arrow-buffer/src/builder/null.rs

@@ -159,6 +159,7 @@ impl NullBufferBuilder {
         }
     }
 
+    /// Return a mutable reference to the inner bitmap slice.
     pub fn as_slice_mut(&mut self) -> Option<&mut [u8]> {
         self.bitmap_builder.as_mut().map(|b| b.as_slice_mut())
     }
@@ -173,14 +174,12 @@ impl NullBufferBuilder {
 }
 
 impl NullBufferBuilder {
+    /// Return the number of bits in the buffer.
     pub fn len(&self) -> usize {
-        if let Some(b) = &self.bitmap_builder {
-            b.len()
-        } else {
-            self.len
-        }
+        self.bitmap_builder.as_ref().map_or(self.len, |b| b.len())
     }
 
+    /// Check if the builder is empty.
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }

arrow-buffer/src/builder/offset.rs

@@ -19,13 +19,13 @@ use std::ops::Deref;
 
 use crate::{ArrowNativeType, OffsetBuffer};
 
+/// Builder of [`OffsetBuffer`]
 #[derive(Debug)]
 pub struct OffsetBufferBuilder<O: ArrowNativeType> {
     offsets: Vec<O>,
     last_offset: usize,
 }
 
-/// Builder of [`OffsetBuffer`]
 impl<O: ArrowNativeType> OffsetBufferBuilder<O> {
     /// Create a new builder with space for `capacity + 1` offsets
     pub fn new(capacity: usize) -> Self {

arrow-buffer/src/interval.rs

@@ -68,8 +68,11 @@ use std::ops::Neg;
 #[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
 #[repr(C)]
 pub struct IntervalMonthDayNano {
+    /// Number of months
     pub months: i32,
+    /// Number of days
     pub days: i32,
+    /// Number of nanoseconds
     pub nanoseconds: i64,
 }
 
@@ -345,7 +348,9 @@ derive_arith!(
 #[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd)]
 #[repr(C)]
 pub struct IntervalDayTime {
+    /// Number of days
     pub days: i32,
+    /// Number of milliseconds
     pub milliseconds: i32,
 }
 

arrow-buffer/src/lib.rs

@@ -19,6 +19,7 @@
 
 // used by [`buffer::mutable::dangling_ptr`]
 #![cfg_attr(miri, feature(strict_provenance))]
+#![warn(missing_docs)]
 
 pub mod alloc;
 pub mod buffer;

arrow-buffer/src/util/bit_chunk_iterator.rs

@@ -131,26 +131,32 @@ impl<'a> UnalignedBitChunk<'a> {
         }
     }
 
+    /// Returns the number of leading padding bits
     pub fn lead_padding(&self) -> usize {
         self.lead_padding
     }
 
+    /// Returns the number of trailing padding bits
     pub fn trailing_padding(&self) -> usize {
         self.trailing_padding
     }
 
+    /// Returns the prefix, if any
     pub fn prefix(&self) -> Option<u64> {
         self.prefix
     }
 
+    /// Returns the suffix, if any
     pub fn suffix(&self) -> Option<u64> {
         self.suffix
     }
 
+    /// Returns reference to the chunks
     pub fn chunks(&self) -> &'a [u64] {
         self.chunks
     }
 
+    /// Returns an iterator over the chunks
     pub fn iter(&self) -> UnalignedBitChunkIterator<'a> {
         self.prefix
             .into_iter()
@@ -164,6 +170,7 @@ impl<'a> UnalignedBitChunk<'a> {
     }
 }
 
+/// Iterator over an [`UnalignedBitChunk`]
 pub type UnalignedBitChunkIterator<'a> = std::iter::Chain<
     std::iter::Chain<std::option::IntoIter<u64>, std::iter::Cloned<std::slice::Iter<'a, u64>>>,
     std::option::IntoIter<u64>,
@@ -212,6 +219,7 @@ pub struct BitChunks<'a> {
 }
 
 impl<'a> BitChunks<'a> {
+    /// Create a new [`BitChunks`] from a byte array, and an offset and length in bits
     pub fn new(buffer: &'a [u8], offset: usize, len: usize) -> Self {
         assert!(ceil(offset + len, 8) <= buffer.len() * 8);
 
@@ -232,6 +240,7 @@ impl<'a> BitChunks<'a> {
     }
 }
 
+/// Iterator over chunks of 64 bits represented as an u64
 #[derive(Debug)]
 pub struct BitChunkIterator<'a> {
     buffer: &'a [u8],