chore: comment

evaluator/nixjit_macros/src/ir.rs

@@ -1,3 +1,13 @@
+//! Implements the `ir!` procedural macro.
+//!
+//! This macro is designed to reduce the boilerplate associated with defining
+//! an Intermediate Representation (IR) that follows a specific pattern. It generates:
+//! 1. An enum representing the different kinds of IR nodes (e.g., `Hir`, `Lir`).
+//! 2. Structs for each of the variants that have fields.
+//! 3. `Ref` and `Mut` versions of the main enum for ergonomic pattern matching on references.
+//! 4. `From` implementations to easily convert from a struct variant (e.g., `BinOp`) to the main enum (`Hir::BinOp`).
+//! 5. A `To[IrName]` trait to provide a convenient `.to_hir()` or `.to_lir()` method on the variant structs.
+
 use convert_case::{Case, Casing};
 use proc_macro::TokenStream;
 use quote::{format_ident, quote};
@@ -8,14 +18,21 @@ use syn::{
     token,
 };
 
+/// Represents one of the variants passed to the `ir!` macro.
 pub enum VariantInput {
+    /// A unit-like variant, e.g., `Arg`.
     Unit(Ident),
+    /// A tuple-like variant with one unnamed field, e.g., `ExprRef(ExprId)`.
     Tuple(Ident, Type),
+    /// A struct-like variant with named fields, e.g., `BinOp { lhs: ExprId, rhs: ExprId, kind: BinOpKind }`.
     Struct(Ident, FieldsNamed),
 }
 
+/// The top-level input for the `ir!` macro.
 pub struct MacroInput {
+    /// The name of the main IR enum to be generated (e.g., `Hir`).
     pub base_name: Ident,
+    /// The list of variants for the enum.
     pub variants: Punctuated<VariantInput, Token![,]>,
 }
 
@@ -24,6 +41,7 @@ impl Parse for VariantInput {
         let name: Ident = input.parse()?;
 
         if input.peek(token::Paren) {
+            // Parse a tuple-like variant: `Variant(Type)`
             let content;
             parenthesized!(content in input);
             let ty: Type = content.parse()?;
@@ -34,10 +52,11 @@ impl Parse for VariantInput {
 
             Ok(VariantInput::Tuple(name, ty))
         } else if input.peek(token::Brace) {
+            // Parse a struct-like variant: `Variant { field: Type, ... }`
             let fields: FieldsNamed = input.parse()?;
-
             Ok(VariantInput::Struct(name, fields))
         } else {
+            // Parse a unit-like variant: `Variant`
             Ok(VariantInput::Unit(name))
         }
     }
@@ -45,6 +64,7 @@ impl Parse for VariantInput {
 
 impl Parse for MacroInput {
     fn parse(input: ParseStream) -> Result<Self> {
+        // The macro input is expected to be: `IrName, Variant1, Variant2, ...`
         let base_name = input.parse()?;
         input.parse::<Token![,]>()?;
         let variants = Punctuated::parse_terminated(input)?;
@@ -56,6 +76,7 @@ impl Parse for MacroInput {
     }
 }
 
+/// The implementation of the `ir!` macro.
 pub fn ir_impl(input: TokenStream) -> TokenStream {
     let parsed_input = syn::parse_macro_input!(input as MacroInput);
 
@@ -126,31 +147,38 @@ pub fn ir_impl(input: TokenStream) -> TokenStream {
         }
     }
 
+    // Assemble the final generated code.
     let expanded = quote! {
+        /// The main IR enum, generated by the `ir!` macro.
         #[derive(Debug, IsVariant, Unwrap, TryUnwrap)]
         pub enum #base_name {
             #( #enum_variants ),*
         }
 
+        // The struct definitions for the enum variants.
         #( #struct_defs )*
 
+        /// An immutable reference version of the IR enum.
         #[derive(Debug, IsVariant, Unwrap, TryUnwrap)]
         pub enum #ref_name<'a> {
             #( #ref_variants ),*
         }
 
+        /// A mutable reference version of the IR enum.
         #[derive(Debug, IsVariant, Unwrap, TryUnwrap)]
         pub enum #mut_name<'a> {
             #( #mut_variants ),*
         }
 
         impl #base_name {
+            /// Converts a `&Ir` into a `IrRef`.
             pub fn as_ref(&self) -> #ref_name<'_> {
                 match self {
                     #( #as_ref_arms ),*
                 }
             }
 
+            /// Converts a `&mut Ir` into a `IrMut`.
             pub fn as_mut(&mut self) -> #mut_name<'_> {
                 match self {
                     #( #as_mut_arms ),*
@@ -158,12 +186,16 @@ pub fn ir_impl(input: TokenStream) -> TokenStream {
             }
         }
 
+        // `From` implementations for converting variant structs into the main enum.
         #( #from_impls )*
 
+        /// A trait for converting a variant struct into the main IR enum.
         pub trait #to_trait_name {
+            /// Performs the conversion.
             fn #to_trait_fn_name(self) -> #base_name;
         }
 
+        // Implement the `ToIr` trait for each variant struct.
         #( #to_trait_impls )*
     };