chore: comment

evaluator/nixjit_eval/src/value/attrset.rs

@@ -1,3 +1,5 @@
+//! Defines the runtime representation of an attribute set (a map).
+
 use core::ops::Deref;
 use std::fmt::Debug;
 use std::rc::Rc;
@@ -7,12 +9,16 @@ use hashbrown::{HashMap, HashSet};
 use itertools::Itertools;
 
 use nixjit_error::{Error, Result};
-use nixjit_value as p;
 use nixjit_value::Symbol;
+use nixjit_value::{self as p, format_symbol};
 
 use super::Value;
 use crate::EvalContext;
 
+/// A wrapper around a `HashMap` representing a Nix attribute set.
+///
+/// It uses `#[repr(transparent)]` to ensure it has the same memory layout
+/// as `HashMap<String, Value>`.
 #[repr(transparent)]
 #[derive(Constructor, PartialEq)]
 pub struct AttrSet {
@@ -56,16 +62,24 @@ impl Deref for AttrSet {
 }
 
 impl AttrSet {
+    /// Creates a new `AttrSet` with a specified initial capacity.
     pub fn with_capacity(cap: usize) -> Self {
         AttrSet {
             data: HashMap::with_capacity(cap),
         }
     }
 
+    /// Inserts an attribute, overwriting any existing attribute with the same name.
     pub fn push_attr_force(&mut self, sym: String, val: Value) {
         self.data.insert(sym, val);
     }
 
+    /// Inserts an attribute.
+    ///
+    /// # Panics
+    ///
+    /// This method currently uses `todo!()` and will panic if the attribute
+    /// already exists, indicating that duplicate attribute handling is not yet implemented.
     pub fn push_attr(&mut self, sym: String, val: Value) {
         if self.data.get(&sym).is_some() {
             todo!()
@@ -73,6 +87,10 @@ impl AttrSet {
         self.data.insert(sym, val);
     }
 
+    /// Performs a deep selection of an attribute from a nested set.
+    ///
+    /// It traverses the attribute path and returns the final value, or an error
+    /// if any intermediate attribute does not exist or is not a set.
     pub fn select(
         &self,
         mut path: impl DoubleEndedIterator<Item = Result<String>>,
@@ -84,7 +102,7 @@ impl AttrSet {
             let Some(Value::AttrSet(attrs)) = data.get(&item) else {
                 return Err(Error::EvalError(format!(
                     "attribute '{}' not found",
-                    Symbol::from(item)
+                    format_symbol(item)
                 )));
             };
             data = attrs.as_inner();
@@ -95,6 +113,7 @@ impl AttrSet {
         })
     }
 
+    /// Checks if an attribute path exists within the set.
     pub fn has_attr(
         &self,
         mut path: impl DoubleEndedIterator<Item = Result<String>>,
@@ -110,24 +129,38 @@ impl AttrSet {
         Ok(data.get(&last?).is_some())
     }
 
+    /// Merges another `AttrSet` into this one, with attributes from `other`
+    /// overwriting existing ones. This corresponds to the `//` operator in Nix.
     pub fn update(&mut self, other: &Self) {
         for (k, v) in other.data.iter() {
             self.push_attr_force(k.clone(), v.clone())
         }
     }
 
+    /// Returns a reference to the inner `HashMap`.
     pub fn as_inner(&self) -> &HashMap<String, Value> {
         &self.data
     }
 
+    /// Converts an `Rc<AttrSet>` to an `Rc<HashMap<String, Value>>` without allocation.
+    ///
+    /// # Safety
+    ///
+    /// This is safe because `AttrSet` is `#[repr(transparent)]`.
     pub fn into_inner(self: Rc<Self>) -> Rc<HashMap<String, Value>> {
         unsafe { core::mem::transmute(self) }
     }
 
+    /// Creates an `AttrSet` from a `HashMap`.
     pub fn from_inner(data: HashMap<String, Value>) -> Self {
         Self { data }
     }
 
+    /// Performs a deep equality comparison between two `AttrSet`s.
+    ///
+    /// It recursively compares the contents of both sets, ensuring that both keys
+    /// and values are identical. The attributes are sorted before comparison to
+    /// ensure a consistent result.
     pub fn eq_impl(&self, other: &Self) -> bool {
         self.data.iter().len() == other.data.iter().len()
             && std::iter::zip(
@@ -137,6 +170,7 @@ impl AttrSet {
             .all(|((k1, v1), (k2, v2))| k1 == k2 && v1.eq_impl(v2))
     }
 
+    /// Converts the `AttrSet` to its public-facing representation.
     pub fn to_public(&self, seen: &mut HashSet<Value>) -> p::Value {
         p::Value::AttrSet(p::AttrSet::new(
             self.data