Add license and some documentation

arrow-json/src/raw/converter.rs

@@ -1,3 +1,22 @@
+// 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 trait to convert data while decoding json and make them conform to the Schema
+
 use crate::raw::tape::{Tape, TapeElement};
 use crate::raw::tape_error;
 use arrow_array::ArrowPrimitiveType;
@@ -7,6 +26,7 @@ use num::NumCast;
 use std::borrow::Cow;
 
 pub trait TapeConverter: Send {
+    /// Converts this tape entry to bool
     fn to_bool(
         &self,
         tape: &Tape<'_, Self>,
@@ -15,6 +35,7 @@ pub trait TapeConverter: Send {
     where
         Self: Sized;
 
+    /// Converts this tape entry to primitive number
     fn to_primitive<P>(
         &self,
         tape: &Tape<'_, Self>,
@@ -26,6 +47,7 @@ pub trait TapeConverter: Send {
         P: ArrowPrimitiveType + Parser,
         P::Native: NumCast;
 
+    /// Converts this tape entry to string
     fn to_string<'a>(
         &self,
         tape: &'a Tape<'_, Self>,
@@ -35,6 +57,7 @@ pub trait TapeConverter: Send {
         Self: Sized;
 }
 
+/// A Strict version of the TapeConverter, which is useful when the json entry must match the schema
 #[derive(Copy, Clone, Default, Debug)]
 pub struct StrictTapeConverter;
 
@@ -101,6 +124,12 @@ impl TapeConverter for StrictTapeConverter {
     }
 }
 
+/// A Loose version of the TapeConverter, which is useful when the json entry doesn't match the schema.
+/// It will try its best to convert the data:
+/// - Any number can be converted into strings or bools. For string it will just read as is, but for bool it will be false when equals zero, true otherwise.
+/// - A bool can be converted into string or number. For string it will just read as is, but for number it will consider 1 for true and 0 for false.
+/// - A string can be converted into number like the Strict version, but it can be converted to bool if it's "true" or "1" it will be considered true, otherwise it will be considered false.
+/// - Lists and Structs can be converted into strings, and their json representation will be used.
 #[derive(Copy, Clone, Default, Debug)]
 pub struct LooseTapeConverter;