Add documentation

datafusion/common/src/types/logical.rs

@@ -40,9 +40,37 @@ pub enum TypeParameter<'a> {
     Number(i128),
 }
 
-/// A reference counted [`LogicalType`]
+/// A reference counted [`LogicalType`].
 pub type LogicalTypeRef = Arc<dyn LogicalType>;
 
+/// Representation of a logical type with its signature and its native backing
+/// type.
+///
+/// The logical type is meant to be used during the DataFusion logical planning
+/// phase in order to reason about logical types without worrying about their
+/// underlying physical implementation.
+///
+/// ### Extension types
+///
+/// [`LogicalType`] is a trait in order to allow the possibility of declaring
+/// extension types:
+///
+/// ```
+/// struct JSON {}
+///
+/// impl LogicalType for JSON {
+///     fn native(&self) -> &NativeType {
+///         &NativeType::Utf8
+///     }
+///
+///    fn signature(&self) -> TypeSignature<'_> {
+///        TypeSignature::Extension {
+///            name: "JSON",
+///            parameters: &[],
+///        }
+///    }
+/// }
+/// ```
 pub trait LogicalType: Sync + Send {
     fn native(&self) -> &NativeType;
     fn signature(&self) -> TypeSignature<'_>;

datafusion/common/src/types/native.rs

@@ -15,32 +15,69 @@
 // specific language governing permissions and limitations
 // under the License.
 
-use std::sync::Arc;
+use std::{ops::Deref, sync::Arc};
 
 use arrow_schema::{DataType, Field, Fields, IntervalUnit, TimeUnit, UnionFields};
 
 use super::{LogicalType, TypeSignature};
 
+/// A record of a native type, its name and its nullability.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct NativeField {
     name: String,
     native_type: NativeType,
     nullable: bool,
 }
 
+impl NativeField {
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    pub fn native_type(&self) -> &NativeType {
+        &self.native_type
+    }
+
+    pub fn nullable(&self) -> bool {
+        self.nullable
+    }
+}
+
+/// A reference counted [`NativeField`].
 pub type NativeFieldRef = Arc<NativeField>;
 
+/// A cheaply cloneable, owned collection of [`NativeFieldRef`].
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct NativeFields(Arc<[NativeFieldRef]>);
 
+impl Deref for NativeFields {
+    type Target = [NativeFieldRef];
+
+    fn deref(&self) -> &Self::Target {
+        self.0.as_ref()
+    }
+}
+
+/// A cheaply cloneable, owned collection of [`NativeFieldRef`] and their
+/// corresponding type ids.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct NativeUnionFields(Arc<[(i8, NativeFieldRef)]>);
 
+impl Deref for NativeUnionFields {
+    type Target = [(i8, NativeFieldRef)];
+
+    fn deref(&self) -> &Self::Target {
+        self.0.as_ref()
+    }
+}
+
+/// Representation of a type that DataFusion can handle natively. It is a subset
+/// of the physical variants in Arrow's native [`DataType`].
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub enum NativeType {
     /// Null type
     Null,
-    /// A boolean datatype representing the values `true` and `false`.
+    /// A boolean type representing the values `true` and `false`.
     Boolean,
     /// A signed 8-bit integer.
     Int8,
@@ -162,9 +199,9 @@ pub enum NativeType {
     List(NativeFieldRef),
     /// A list of some logical data type with fixed length.
     FixedSizeList(NativeFieldRef, i32),
-    /// A nested datatype that contains a number of sub-fields.
+    /// A nested type that contains a number of sub-fields.
     Struct(NativeFields),
-    /// A nested datatype that can represent slots of differing types.
+    /// A nested type that can represent slots of differing types.
     Union(NativeUnionFields),
     /// Decimal value with precision and scale
     ///