docs(tvix/eval): upvalues.rs: define "upvalue", comment with_stack

This commit adds a comment for the benefit of non-Lua-users
explaining what an upvalue is.  It also adds a comment explaining
what `with_stack` does, including a brief reminder of nix's
slightly-unusual-but-well-justified handling of this construct.

Signed-off-by: Adam Joseph <adam@westernsemico.com>
Change-Id: If6d0e133292451af906e1c728e34010f99be8c7c
Reviewed-on: https://cl.tvl.fyi/c/depot/+/7007
Reviewed-by: j4m3s <james.landrein@gmail.com>
Reviewed-by: tazjin <tazjin@tvl.su>
Tested-by: BuildkiteCI

tvix/eval/src/upvalues.rs

@@ -2,6 +2,10 @@
 //! relevant to both thunks (delayed computations for lazy-evaluation)
 //! as well as closures (lambdas that capture variables from the
 //! surrounding scope).
+//!
+//! The upvalues of a scope are whatever data are needed at runtime
+//! in order to resolve each free variable in the scope to a value.
+//! "Upvalue" is a term taken from Lua.
 
 use std::{
     cell::{Ref, RefMut},
@@ -10,26 +14,43 @@ use std::{
 
 use crate::{opcode::UpvalueIdx, Value};
 
-/// Structure for carrying upvalues inside of thunks & closures. The
+/// Structure for carrying upvalues of an UpvalueCarrier.  The
-/// implementation of this struct encapsulates the logic for capturing
+/// implementation of this struct encapsulates the logic for
-/// and accessing upvalues.
+/// capturing and accessing upvalues.
+///
+/// Nix's `with` cannot be used to shadow an enclosing binding --
+/// like Rust's `use xyz::*` construct, but unlike Javascript's
+/// `with (xyz)`.  This means that Nix has two kinds of identifiers,
+/// which can be distinguished at compile time:
+///
+/// - Static identifiers, which are bound in some enclosing scope by
+///   `let`, `name:` or `{name}:`
+/// - Dynamic identifiers, which are not bound in any enclosing
+///   scope
 #[derive(Clone, Debug, PartialEq)]
 pub struct Upvalues {
-    upvalues: Vec<Value>,
+    /// The upvalues of static identifiers.  Each static identifier
+    /// is assigned an integer identifier at compile time, which is
+    /// an index into this Vec.
+    static_upvalues: Vec<Value>,
+
+    /// The upvalues of dynamic identifiers, if any exist.  This
+    /// consists of the value passed to each enclosing `with val;`,
+    /// from outermost to innermost.
     with_stack: Option<Vec<Value>>,
 }
 
 impl Upvalues {
     pub fn with_capacity(count: usize) -> Self {
         Upvalues {
-            upvalues: Vec::with_capacity(count),
+            static_upvalues: Vec::with_capacity(count),
             with_stack: None,
         }
     }
 
     /// Push an upvalue at the end of the upvalue list.
     pub fn push(&mut self, value: Value) {
-        self.upvalues.push(value);
+        self.static_upvalues.push(value);
     }
 
     /// Set the captured with stack.
@@ -53,7 +74,7 @@ impl Index<UpvalueIdx> for Upvalues {
     type Output = Value;
 
     fn index(&self, index: UpvalueIdx) -> &Self::Output {
-        &self.upvalues[index.0]
+        &self.static_upvalues[index.0]
     }
 }
 
@@ -69,13 +90,13 @@ pub trait UpvalueCarrier {
 
     /// Read an upvalue at the given index.
     fn upvalue(&self, idx: UpvalueIdx) -> Ref<'_, Value> {
-        Ref::map(self.upvalues(), |v| &v.upvalues[idx.0])
+        Ref::map(self.upvalues(), |v| &v.static_upvalues[idx.0])
     }
 
     /// Resolve deferred upvalues from the provided stack slice,
     /// mutating them in the internal upvalue slots.
     fn resolve_deferred_upvalues(&self, stack: &[Value]) {
-        for upvalue in self.upvalues_mut().upvalues.iter_mut() {
+        for upvalue in self.upvalues_mut().static_upvalues.iter_mut() {
             if let Value::DeferredUpvalue(idx) = upvalue {
                 *upvalue = stack[idx.0].clone();
             }