CR comment

jitexpr/src/ast/infer_types.rs

@@ -174,6 +174,11 @@ pub fn infer_types_with_target(
     Ok(inferred_type_res)
 }
 
+/// Infer the possible types of an UntypedExpr, meant to represent `target_inferred_type`.
+///
+/// As we call it recursively on the different nodes of the expression,
+/// this method should mutate the inferred_types (found in the inferred_type_res map) of each
+/// variable name encounterred, always restricting them.
 pub(crate) fn infer_types_aux<'a>(
     expr: &'a UntypedExpr,
     target_inferred_type: InferredTypeSet,
@@ -219,6 +224,7 @@ pub(crate) fn infer_type_with_variable_types(
     infer_types_aux(expr, target_inferred_type, &mut inferred_types)
 }
 
+/// Populate the inferred_types HashMap with the value types proved by the user.
 fn seed_variable_types<'a>(
     expr: &'a UntypedExpr,
     variable_types: &HashMap<&str, VarType>,
@@ -227,6 +233,8 @@ fn seed_variable_types<'a>(
     match expr {
         UntypedExpr::Literal(_) => {}
         UntypedExpr::Variable(variable_name) => {
+            // If the value is not provided by the user (for instance because we fed values from a
+            // columnar and no column with that column name exists), we treat it has being None.
             let inferred_type = variable_types
                 .get(variable_name.as_ref())
                 .copied()

jitexpr/src/ast/literal.rs

@@ -54,7 +54,7 @@ impl Literal {
         }
     }
 
-    // TODO let's remove it
+    #[cfg(test)]
     pub fn r#type(&self) -> VarType {
         match self {
             Literal::None => VarType::None,

jitexpr/src/ast/mod.rs

@@ -1,13 +1,13 @@
 mod infer_types;
 mod literal;
-mod serialize;
+mod serde;
 mod untyped_expr;
 
 pub use infer_types::{InferredTypeSet, TypeError, infer_types, infer_types_with_target};
 pub(crate) use infer_types::{infer_type_with_variable_types, infer_types_aux};
 pub use literal::Literal;
-pub(crate) use serialize::format_variable_name;
-pub use serialize::{DeserializeError, deserialize, serialize};
+pub(crate) use serde::format_variable_name;
+pub use serde::{DeserializeError, deserialize, serialize};
 pub use untyped_expr::UntypedExpr;
 
 pub use crate::functions::{Function, InvalidFnCall};

jitexpr/src/ast/serde.rs

@@ -1,4 +1,4 @@
-//! Serialization for [`UntypedExpr`] using a small Lisp-like syntax.
+//! De/Serialization for [`UntypedExpr`] using a small Lisp-like syntax.
 //!
 //! Calls are lists whose first item is a recognized uppercase function name.
 //! Elsewhere, atoms name variables unless they match a literal. For example:
@@ -8,18 +8,20 @@
 //! ```
 //!
 //! Numerical literals always carry a type suffix. Parsing rejects non-finite
-//! `f64` literals (NaN, infinities, and overflow). The other literals are
-//! `none`, `true`, `false`, and double-quoted strings. Backticks quote variable
-//! names containing whitespace or syntax characters, or matching literals:
+//! f64 literals (NaN, infinities, and overflow). The other literals are
+//! none, true, false, and double-quoted strings. Backticks quote variable
+//! names containing whitespace or syntax characters, or matching literals.
+//! In most case, backticks quote are unnecessary.
 //!
 //! ```text
-//! (ADD `1u64` 1u64)
+//! (ADD `text` 1u64)
+//! ```
+//! is the same as
+//! ```text
+//! (ADD text 1u64)
 //! ```
 //!
-//! Quoted variables use the same backslash escapes as strings, plus `` \` `` for
-//! a literal backtick. Serialization quotes names only when needed for an
-//! unambiguous round trip. Variable names are not restricted to ASCII or checked
-//! against a schema; field-name validation remains the caller's responsibility.
+//! Quoted variables use escaping to including quotation marks.
 
 use std::fmt;
 use std::sync::Arc;
@@ -121,7 +123,7 @@ fn format_literal(literal: &Literal, formatter: &mut fmt::Formatter) -> fmt::Res
     }
 }
 
-fn format_quoted(value: &str, quote: char, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+fn format_quoted(value: &str, quote: char, formatter: &mut fmt::Formatter) -> fmt::Result {
     write!(formatter, "{quote}")?;
     for character in value.chars() {
         match character {