Enforce missing docs (#52)

arrow2_convert/src/deserialize.rs

@@ -1,4 +1,4 @@
-// Implementations of derive traits for arrow2 built-in types
+//! Implementation and traits for deserializing from Arrow.
 
 use arrow2::array::*;
 use chrono::{NaiveDate, NaiveDateTime};
@@ -11,6 +11,7 @@ where
     Self::ArrayType: ArrowArray,
     for<'a> &'a Self::ArrayType: IntoIterator,
 {
+    /// The `arrow2::Array` type corresponding to this field
     type ArrayType;
 
     /// Deserialize this field from arrow
@@ -19,12 +20,13 @@ where
     ) -> Option<<Self as ArrowField>::Type>;
 
     #[inline]
-    // For internal use only
-    //
-    // This is an ugly hack to allow generating a blanket Option<T> deserialize.
-    // Ideally we would be able to capture the optional field of the iterator via
-    // something like for<'a> &'a T::ArrayType: IntoIterator<Item=Option<E>>,
-    // However, the E parameter seems to confuse the borrow checker if it's a reference.
+    #[doc(hidden)]
+    /// For internal use only
+    ///
+    /// This is an ugly hack to allow generating a blanket Option<T> deserialize.
+    /// Ideally we would be able to capture the optional field of the iterator via
+    /// something like for<'a> &'a T::ArrayType: IntoIterator<Item=Option<E>>,
+    /// However, the E parameter seems to confuse the borrow checker if it's a reference.
     fn arrow_deserialize_internal(
         v: <&Self::ArrayType as IntoIterator>::Item,
     ) -> <Self as ArrowField>::Type {
@@ -267,7 +269,11 @@ where
     Element: ArrowField,
     Collection: FromIterator<Element>,
 {
+    /// Convert from a `arrow2::Array` to any collection that implements the `FromIterator` trait
     fn try_into_collection(self) -> arrow2::error::Result<Collection>;
+
+    /// Same as `try_into_collection` except can coerce the conversion to a specific Arrow type. This is
+    /// useful when the same rust type maps to one or more Arrow types for example `LargeString`.
     fn try_into_collection_as_type<ArrowType>(self) -> arrow2::error::Result<Collection>
     where
         ArrowType: ArrowDeserialize + ArrowField<Type = Element> + 'static,
@@ -286,6 +292,7 @@ where
         .map(<Field as ArrowDeserialize>::arrow_deserialize_internal)
 }
 
+/// Returns a typed iterator to a target type from an `arrow2::Array`
 pub fn arrow_array_deserialize_iterator_as_type<'a, Element, ArrowType>(
     arr: &'a dyn arrow2::array::Array,
 ) -> arrow2::error::Result<impl Iterator<Item = Element> + 'a>

arrow2_convert/src/field.rs

@@ -1,3 +1,5 @@
+//! Implementation and traits for mapping rust types to Arrow types
+
 use arrow2::datatypes::{DataType, Field};
 use chrono::{NaiveDate, NaiveDateTime};
 
@@ -107,6 +109,7 @@ impl_numeric_type_full!(i64, Int64);
 impl_numeric_type_full!(f32, Float32);
 impl_numeric_type_full!(f64, Float64);
 
+/// Maps a rust i128 to an Arrow Decimal where precision and scale are required.
 pub struct I128<const PRECISION: usize, const SCALE: usize> {}
 
 impl<const PRECISION: usize, const SCALE: usize> ArrowField for I128<PRECISION, SCALE> {
@@ -127,6 +130,7 @@ impl ArrowField for String {
     }
 }
 
+/// Represents the `LargeUtf8` Arrow type
 pub struct LargeString {}
 
 impl ArrowField for LargeString {
@@ -174,6 +178,7 @@ impl ArrowField for Vec<u8> {
     }
 }
 
+/// Represents the `LargeString` Arrow type.
 pub struct LargeBinary {}
 
 impl ArrowField for LargeBinary {
@@ -185,6 +190,7 @@ impl ArrowField for LargeBinary {
     }
 }
 
+/// Represents the `FixedSizeBinary` Arrow type.
 pub struct FixedSizeBinary<const SIZE: usize> {}
 
 impl<const SIZE: usize> ArrowField for FixedSizeBinary<SIZE> {
@@ -209,6 +215,7 @@ where
     }
 }
 
+/// Represents the `LargeList` Arrow type.
 pub struct LargeVec<T> {
     d: std::marker::PhantomData<T>,
 }
@@ -225,6 +232,7 @@ where
     }
 }
 
+/// Represents the `FixedSizeList` Arrow type.
 pub struct FixedSizeVec<T, const SIZE: usize> {
     d: std::marker::PhantomData<T>,
 }

arrow2_convert/src/lib.rs

@@ -1,12 +1,14 @@
+#![doc = include_str!("../README.md")]
+#![deny(missing_docs)]
 #![forbid(unsafe_code)]
 
-// The proc macro is implemented in derive_internal, and re-exported by this
-// crate. This is because a single crate can not define both a proc macro and a
-// macro_rules macro.
 pub mod deserialize;
 pub mod field;
 pub mod serialize;
 
+// The proc macro is implemented in derive_internal, and re-exported by this
+// crate. This is because a single crate can not define both a proc macro and a
+// macro_rules macro.
 #[cfg(feature = "arrow2_convert_derive")]
 #[doc(hidden)]
 pub use arrow2_convert_derive::ArrowField;

arrow2_convert/src/serialize.rs

@@ -1,3 +1,5 @@
+//! Implementation and traits for serializing to Arrow.
+
 use arrow2::array::*;
 use arrow2::chunk::Chunk;
 use chrono::{NaiveDate, NaiveDateTime};
@@ -429,7 +431,11 @@ where
     Self: IntoIterator<Item = &'a Element>,
     Element: 'static,
 {
+    /// Convert from any iterable collection into an `arrow2::Array`
     fn try_into_arrow(self) -> arrow2::error::Result<ArrowArray>;
+
+    /// Convert from any iterable collection into an `arrow2::Array` by coercing the conversion to a specific Arrow type.
+    /// This is useful when the same rust type maps to one or more Arrow types for example `LargeString`.
     fn try_into_arrow_as_type<ArrowType>(self) -> arrow2::error::Result<ArrowArray>
     where
         ArrowType: ArrowSerialize + ArrowField<Type = Element> + 'static;