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

Author: ByteBaker

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/src/error.rs

@@ -19,4 +19,5 @@
 
 pub use arrow_schema::ArrowError;
 
+/// A specialized `Result` type for Arrow operations.
 pub type Result<T> = std::result::Result<T, ArrowError>;

arrow/src/lib.rs

@@ -364,6 +364,7 @@
 
 #![deny(clippy::redundant_clone)]
 #![warn(missing_debug_implementations)]
+#![warn(missing_docs)]
 #![allow(rustdoc::invalid_html_tags)]
 pub use arrow_array::{downcast_dictionary_array, downcast_primitive_array};
 
@@ -389,6 +390,7 @@ pub use arrow_json as json;
 #[cfg(feature = "pyarrow")]
 pub mod pyarrow;
 
+/// Contains the `RecordBatch` type and associated traits
 pub mod record_batch {
     pub use arrow_array::{
         RecordBatch, RecordBatchIterator, RecordBatchOptions, RecordBatchReader, RecordBatchWriter,

arrow/src/tensor.rs

@@ -80,36 +80,67 @@ pub struct Tensor<'a, T: ArrowPrimitiveType> {
     _marker: PhantomData<T>,
 }
 
+/// [Tensor] of type [BooleanType]
 pub type BooleanTensor<'a> = Tensor<'a, BooleanType>;
+/// [Tensor] of type [Int8Type]
 pub type Date32Tensor<'a> = Tensor<'a, Date32Type>;
+/// [Tensor] of type [Int16Type]
 pub type Date64Tensor<'a> = Tensor<'a, Date64Type>;
+/// [Tensor] of type [Decimal128Type]
 pub type Decimal128Tensor<'a> = Tensor<'a, Decimal128Type>;
+/// [Tensor] of type [Decimal256Type]
 pub type Decimal256Tensor<'a> = Tensor<'a, Decimal256Type>;
+/// [Tensor] of type [DurationMicrosecondType]
 pub type DurationMicrosecondTensor<'a> = Tensor<'a, DurationMicrosecondType>;
+/// [Tensor] of type [DurationMillisecondType]
 pub type DurationMillisecondTensor<'a> = Tensor<'a, DurationMillisecondType>;
+/// [Tensor] of type [DurationNanosecondType]
 pub type DurationNanosecondTensor<'a> = Tensor<'a, DurationNanosecondType>;
+/// [Tensor] of type [DurationSecondType]
 pub type DurationSecondTensor<'a> = Tensor<'a, DurationSecondType>;
+/// [Tensor] of type [Float16Type]
 pub type Float16Tensor<'a> = Tensor<'a, Float16Type>;
+/// [Tensor] of type [Float32Type]
 pub type Float32Tensor<'a> = Tensor<'a, Float32Type>;
+/// [Tensor] of type [Float64Type]
 pub type Float64Tensor<'a> = Tensor<'a, Float64Type>;
+/// [Tensor] of type [Int8Type]
 pub type Int8Tensor<'a> = Tensor<'a, Int8Type>;
+/// [Tensor] of type [Int16Type]
 pub type Int16Tensor<'a> = Tensor<'a, Int16Type>;
+/// [Tensor] of type [Int32Type]
 pub type Int32Tensor<'a> = Tensor<'a, Int32Type>;
+/// [Tensor] of type [Int64Type]
 pub type Int64Tensor<'a> = Tensor<'a, Int64Type>;
+/// [Tensor] of type [IntervalDayTimeType]
 pub type IntervalDayTimeTensor<'a> = Tensor<'a, IntervalDayTimeType>;
+/// [Tensor] of type [IntervalMonthDayNanoType]
 pub type IntervalMonthDayNanoTensor<'a> = Tensor<'a, IntervalMonthDayNanoType>;
+/// [Tensor] of type [IntervalYearMonthType]
 pub type IntervalYearMonthTensor<'a> = Tensor<'a, IntervalYearMonthType>;
+/// [Tensor] of type [Time32MillisecondType]
 pub type Time32MillisecondTensor<'a> = Tensor<'a, Time32MillisecondType>;
+/// [Tensor] of type [Time32SecondType]
 pub type Time32SecondTensor<'a> = Tensor<'a, Time32SecondType>;
+/// [Tensor] of type [Time64MicrosecondType]
 pub type Time64MicrosecondTensor<'a> = Tensor<'a, Time64MicrosecondType>;
+/// [Tensor] of type [Time64NanosecondType]
 pub type Time64NanosecondTensor<'a> = Tensor<'a, Time64NanosecondType>;
+/// [Tensor] of type [TimestampMicrosecondType]
 pub type TimestampMicrosecondTensor<'a> = Tensor<'a, TimestampMicrosecondType>;
+/// [Tensor] of type [TimestampMillisecondType]
 pub type TimestampMillisecondTensor<'a> = Tensor<'a, TimestampMillisecondType>;
+/// [Tensor] of type [TimestampNanosecondType]
 pub type TimestampNanosecondTensor<'a> = Tensor<'a, TimestampNanosecondType>;
+/// [Tensor] of type [TimestampSecondType]
 pub type TimestampSecondTensor<'a> = Tensor<'a, TimestampSecondType>;
+/// [Tensor] of type [UInt8Type]
 pub type UInt8Tensor<'a> = Tensor<'a, UInt8Type>;
+/// [Tensor] of type [UInt16Type]
 pub type UInt16Tensor<'a> = Tensor<'a, UInt16Type>;
+/// [Tensor] of type [UInt32Type]
 pub type UInt32Tensor<'a> = Tensor<'a, UInt32Type>;
+/// [Tensor] of type [UInt64Type]
 pub type UInt64Tensor<'a> = Tensor<'a, UInt64Type>;
 
 impl<'a, T: ArrowPrimitiveType> Tensor<'a, T> {

arrow/src/util/bench_util.rs

@@ -50,6 +50,8 @@ where
         .collect()
 }
 
+/// Creates a [`PrimitiveArray`] of a given `size` and `null_density`
+/// filling it with random numbers generated using the provided `seed`.
 pub fn create_primitive_array_with_seed<T>(
     size: usize,
     null_density: f32,
@@ -72,6 +74,8 @@ where
         .collect()
 }
 
+/// Creates a [`PrimitiveArray`] of a given `size` and `null_density`
+/// filling it with random [`IntervalMonthDayNano`] generated using the provided `seed`.
 pub fn create_month_day_nano_array_with_seed(
     size: usize,
     null_density: f32,

arrow/src/util/data_gen.rs

@@ -394,15 +394,18 @@ fn create_random_null_buffer(size: usize, null_density: f32) -> Buffer {
 /// Useful for testing. The range of values are not likely to be representative of the
 /// actual bounds.
 pub trait RandomTemporalValue: ArrowTemporalType {
+    /// Returns the range of values for `impl`'d type
     fn value_range() -> impl SampleRange<Self::Native>;
 
+    /// Generate a random value within the range of the type
     fn gen_range<R: Rng>(rng: &mut R) -> Self::Native
     where
         Self::Native: SampleUniform,
     {
         rng.gen_range(Self::value_range())
     }
 
+    /// Generate a random value of the type
     fn random<R: Rng>(rng: &mut R) -> Self::Native
     where
         Self::Native: SampleUniform,

arrow/src/util/mod.rs

@@ -15,6 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! Utility functions for working with Arrow data
 pub use arrow_buffer::{bit_chunk_iterator, bit_util};
 
 pub use arrow_data::bit_iterator;

arrow/src/util/string_writer.rs

@@ -63,27 +63,24 @@
 //! }
 //! ```
 
+use core::str;
 use std::fmt::Formatter;
 use std::io::{Error, ErrorKind, Result, Write};
 
-#[derive(Debug)]
+/// A writer that allows writing to a `String`
+/// like an `std::io::Write` object.
+#[derive(Debug, Default)]
 pub struct StringWriter {
     data: String,
 }
 
 impl StringWriter {
+    /// Create a new `StringWriter`
     pub fn new() -> Self {
-        StringWriter {
-            data: String::new(),
-        }
+        Self::default()
     }
 }
 
-impl Default for StringWriter {
-    fn default() -> Self {
-        Self::new()
-    }
-}
 impl std::fmt::Display for StringWriter {
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         write!(f, "{}", self.data)
@@ -92,13 +89,13 @@ impl std::fmt::Display for StringWriter {
 
 impl Write for StringWriter {
     fn write(&mut self, buf: &[u8]) -> Result<usize> {
-        let string = match String::from_utf8(buf.to_vec()) {
+        let string = match str::from_utf8(buf) {
             Ok(x) => x,
             Err(e) => {
                 return Err(Error::new(ErrorKind::InvalidData, e));
             }
         };
-        self.data.push_str(&string);
+        self.data.push_str(string);
         Ok(string.len())
     }