docs(tvix/eval): add comments for Opcode::DataXXX opcodes r/5245

Signed-off-by: Adam Joseph <adam@westernsemico.com>
Change-Id: I8c72405880a9342eb502d92c1e0087f5bb17e03c
Reviewed-on: https://cl.tvl.fyi/c/depot/+/7087
Tested-by: BuildkiteCI
Reviewed-by: tazjin <tazjin@tvl.su>

1 files changed, 8 insertions, 2 deletions

diff --git a/tvix/eval/src/opcode.rs b/tvix/eval/src/opcode.rs
index b7367cd815ea..9c7ccb8d19d0 100644
--- a/tvix/eval/src/opcode.rs
+++ b/tvix/eval/src/opcode.rs
@@ -156,8 +156,8 @@ pub enum OpCode {
     OpThunkSuspended(ConstantIdx),
     OpForce,
 
-    /// Finalise initialisation of the upvalues of the value in the
-    /// given stack index after the scope is fully bound.
+    /// Finalise initialisation of the upvalues of the value in the given stack
+    /// index (which must be a Value::Thunk) after the scope is fully bound.
     OpFinalise(StackIdx),
 
     // [`OpClosure`], [`OpThunkSuspended`], and [`OpThunkClosure`] have a
@@ -171,8 +171,14 @@ pub enum OpCode {
     // instruction pointer.
     //
     // It is illegal for a `Data*` opcode to appear anywhere else.
+    /// Populate a static upvalue by copying from the stack immediately.
     DataLocalIdx(StackIdx),
+    /// Populate a static upvalue of a thunk by copying it the stack, but do
+    /// when the thunk is finalised (by OpFinalise) rather than immediately.
     DataDeferredLocal(StackIdx),
+    /// Populate a static upvalue by copying it from the upvalues of an
+    /// enclosing scope.
     DataUpvalueIdx(UpvalueIdx),
+    /// Populate dynamic upvalues by saving a copy of the with-stack.
     DataCaptureWith,
 }