about summary refs log tree commit diff
diff options
context:
space:
mode:
authorVincent Ambo <mail@tazj.in>2023-01-31T19·30+0300
committertazjin <tazjin@tvl.su>2023-09-08T21·38+0000
commit3cf37c7cb684e450f59d5ea643c5ac05b3647c36 (patch)
treecc4164b8c312bf38113ca830a8fc8f3dbbf59dce
parentec22a80f262e3583cbb0bec63ab67e61d1dc00d3 (diff)
docs(tvix/eval): add documentation strings for some OpCode variants r/6569
Change-Id: I42e610740b3687e1fd897d36694cce425751a8bc
Reviewed-on: https://cl.tvl.fyi/c/depot/+/7975
Tested-by: BuildkiteCI
Autosubmit: tazjin <tazjin@tvl.su>
Reviewed-by: flokli <flokli@flokli.de>
-rw-r--r--tvix/eval/src/opcode.rs39
1 files changed, 37 insertions, 2 deletions
diff --git a/tvix/eval/src/opcode.rs b/tvix/eval/src/opcode.rs
index 04f9ca25556c..a6c59278d286 100644
--- a/tvix/eval/src/opcode.rs
+++ b/tvix/eval/src/opcode.rs
@@ -54,30 +54,65 @@ pub struct Count(pub usize);
 
 /// All variants of this enum carry a bounded amount of data to
 /// ensure that no heap allocations are needed for an Opcode.
+///
+/// In documentation comments, stack positions are referred to by
+/// indices written in `{}` as such, where required:
+///
+/// ```notrust
+///                             --- top of the stack
+///                            /
+///                           v
+///       [ ... | 3 | 2 | 1 | 0 ]
+///                   ^
+///                  /
+/// 2 values deep ---
+/// ```
+///
+/// Unless otherwise specified, operations leave their result at the
+/// top of the stack.
 #[warn(variant_size_differences)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum OpCode {
     /// Push a constant onto the stack.
     OpConstant(ConstantIdx),
 
+    // Unary operators
     /// Discard a value from the stack.
     OpPop,
 
-    // Unary operators
+    /// Invert the boolean at the top of the stack.
     OpInvert,
+
+    // Binary operators
+    /// Invert the sign of the number at the top of the stack.
     OpNegate,
 
-    // Arithmetic binary operators
+    /// Sum up the two numbers at the top of the stack.
     OpAdd,
+
+    /// Subtract the number at {1} from the number at {2}.
     OpSub,
+
+    /// Multiply the two numbers at the top of the stack.
     OpMul,
+
+    /// Divide the two numbers at the top of the stack.
     OpDiv,
 
     // Comparison operators
+    /// Check the two values at the top of the stack for Nix-equality.
     OpEqual,
+
+    /// Check whether the value at {2} is less than {1}.
     OpLess,
+
+    /// Check whether the value at {2} is less than or equal to {1}.
     OpLessOrEq,
+
+    /// Check whether the value at {2} is greater than {1}.
     OpMore,
+
+    /// Check whether the value at {2} is greater than or equal to {1}.
     OpMoreOrEq,
 
     // Logical operators & generic jumps