add documentation

Author: YoEight

src/analysis.rs

@@ -52,12 +52,47 @@ pub struct AnalysisOptions {
     pub default_scope: Scope,
     /// Type information for event records being queried.
     pub event_type_info: Type,
-    /// Collections of types that are not defined in the EventQL reference but yet
-    /// allow the user to use.
+    /// Custom types that are not defined in the EventQL reference.
+    ///
+    /// This set allows users to register custom type names that can be used
+    /// in type conversion expressions (e.g., `field AS CustomType`). Custom
+    /// type names are case-insensitive.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use eventql_parser::prelude::AnalysisOptions;
+    ///
+    /// let options = AnalysisOptions::default()
+    ///     .add_custom_type("Foobar");
+    /// ```
     pub custom_types: HashSet<Ascii<String>>,
 }
 
 impl AnalysisOptions {
+    /// Adds a custom type name to the analysis options.
+    ///
+    /// Custom types allow you to use type conversion syntax with types that are
+    /// not part of the standard EventQL type system. The type name is stored
+    /// case-insensitively.
+    ///
+    /// # Arguments
+    ///
+    /// * `value` - The custom type name to register
+    ///
+    /// # Returns
+    ///
+    /// Returns `self` to allow for method chaining.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use eventql_parser::prelude::AnalysisOptions;
+    ///
+    /// let options = AnalysisOptions::default()
+    ///     .add_custom_type("Timestamp")
+    ///     .add_custom_type("UUID");
+    /// ```
     pub fn add_custom_type<'a>(mut self, value: impl Into<Cow<'a, str>>) -> Self {
         match value.into() {
             Cow::Borrowed(t) => self.custom_types.insert(Ascii::new(t.to_owned())),

src/ast.rs

@@ -73,13 +73,32 @@ pub enum Type {
     Subject,
     /// Function type
     App { args: Vec<Type>, result: Box<Type> },
-    /// A date (e.g 2026-01-03)
+    /// Date type (e.g., `2026-01-03`)
+    ///
+    /// Used when a field is explicitly converted to a date using the `AS DATE` syntax.
     Date,
-    /// Time (e.g 13:45:39)
+    /// Time type (e.g., `13:45:39`)
+    ///
+    /// Used when a field is explicitly converted to a time using the `AS TIME` syntax.
     Time,
-    /// A DateTime (e.g 2026-01-01T13:45:39Z).
+    /// DateTime type (e.g., `2026-01-01T13:45:39Z`)
+    ///
+    /// Used when a field is explicitly converted to a datetime using the `AS DATETIME` syntax.
     DateTime,
-    /// A type that is not defined in the EventQL reference
+    /// Custom type not defined in the EventQL reference
+    ///
+    /// Used when a field is converted to a custom type registered in [`AnalysisOptions::custom_types`].
+    /// The string contains the custom type name as it appears in the query.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use eventql_parser::prelude::{parse_query, AnalysisOptions};
+    ///
+    /// let query = parse_query("FROM e IN events PROJECT INTO { ts: e.data.timestamp as CustomTimestamp }").unwrap();
+    /// let options = AnalysisOptions::default().add_custom_type("CustomTimestamp");
+    /// let typed_query = query.run_static_analysis(&options).unwrap();
+    /// ```
     Custom(String),
 }