chore: comment

evaluator/nixjit_ir/src/lib.rs

@@ -17,21 +17,36 @@ use hashbrown::{HashMap, HashSet};
 use nixjit_value::Const as PubConst;
 
 /// A type-safe wrapper for an index into an expression table.
+///
+/// Using a newtype wrapper like this prevents accidentally mixing up different kinds of indices.
 #[repr(transparent)]
 #[derive(Debug, PartialEq, Eq, Hash)]
 pub struct ExprId(usize);
 
 impl ExprId {
+    /// Creates a clone of the `ExprId`.
+    ///
+    /// # Safety
+    /// This is a shallow copy of the index. The caller must ensure that the lifetime
+    /// and validity of the expression being referenced are handled correctly.
     #[inline(always)]
     pub unsafe fn clone(&self) -> Self {
         Self(self.0)
     }
 
+    /// Returns the raw `usize` index.
+    ///
+    /// # Safety
+    /// The caller is responsible for using this index correctly and not causing out-of-bounds access.
     #[inline(always)]
     pub unsafe fn raw(self) -> usize {
         self.0
     }
 
+    /// Creates an `ExprId` from a raw `usize` index.
+    ///
+    /// # Safety
+    /// The caller must ensure that the provided index is valid for the expression table.
     #[inline(always)]
     pub unsafe fn from(id: usize) -> Self {
         Self(id)
@@ -44,11 +59,19 @@ impl ExprId {
 pub struct PrimOpId(usize);
 
 impl PrimOpId {
+    /// Returns the raw `usize` index.
+    ///
+    /// # Safety
+    /// The caller is responsible for using this index correctly.
     #[inline(always)]
     pub unsafe fn raw(self) -> usize {
         self.0
     }
 
+    /// Creates a `PrimOpId` from a raw `usize` index.
+    ///
+    /// # Safety
+    /// The caller must ensure that the provided index is valid.
     #[inline(always)]
     pub unsafe fn from(id: usize) -> Self {
         Self(id)
@@ -61,11 +84,19 @@ impl PrimOpId {
 pub struct ArgIdx(usize);
 
 impl ArgIdx {
+    /// Returns the raw `usize` index.
+    ///
+    /// # Safety
+    /// The caller is responsible for using this index correctly.
     #[inline(always)]
     pub unsafe fn raw(self) -> usize {
         self.0
     }
 
+    /// Creates an `ArgIdx` from a raw `usize` index.
+    ///
+    /// # Safety
+    /// The caller must ensure that the provided index is valid.
     #[inline(always)]
     pub unsafe fn from(idx: usize) -> Self {
         Self(idx)
@@ -87,8 +118,10 @@ pub struct AttrSet {
 #[derive(Debug, TryUnwrap)]
 pub enum Attr {
     /// A dynamic attribute key, which is an expression that must evaluate to a string.
+    /// Example: `attrs.${key}`
     Dynamic(ExprId),
     /// A static attribute key.
+    /// Example: `attrs.key`
     Str(String),
 }
 
@@ -220,13 +253,20 @@ pub struct If {
 pub struct Func {
     /// The body of the function
     pub body: ExprId,
+    /// The parameter specification for the function.
     pub param: Param,
 }
 
+/// Describes the parameters of a function.
 #[derive(Debug)]
 pub struct Param {
+    /// The name of the argument if it's a simple identifier (e.g., `x: ...`).
+    /// Also used for the alias in a pattern (e.g., `args @ { ... }`).
     pub ident: Option<String>,
+    /// The set of required parameter names for a pattern-matching function.
     pub required: Option<Vec<String>>,
+    /// The set of all allowed parameter names for a non-ellipsis pattern-matching function.
+    /// If `None`, any attribute is allowed (ellipsis `...` is present).
     pub allowed: Option<HashSet<String>>,
 }