random documentation improvements

Veridise · Jul 30, 2024 · a36d83a · a36d83a
1 parent ccaa1c1
commit a36d83a
Show file tree

Hide file tree

Showing 4 changed files with 19 additions and 6 deletions.
diff --git a/circom/tests/controlflow/early_return_loop_with_unknown_if.circom b/circom/tests/controlflow/early_return_loop_with_unknown_if.circom
@@ -2,6 +2,7 @@ pragma circom 2.0.3;
 // REQUIRES: circom
 // RUN: rm -rf %t && mkdir %t && %circom --llvm -o %t %s | sed -n 's/.*Written successfully:.* \(.*\)/\1/p' | xargs cat | FileCheck %s --enable-var-scope
 
+// %0 (i.e. arena) = [ a[0], a[1], b[0], b[1], i ]
 function long_gt(a, b) {
     for (var i = 1; i >= 0; i--) {
         if (a[i] > b[i]) {
@@ -14,17 +15,22 @@ function long_gt(a, b) {
     return 0;
 }
 
+// %0 (i.e. arena) = [ in[0], in[1], out[0], out[1] ]
 function long_scalar_mult(in) {
     var out[2] = in;
     return out;
 }
 
+// %0 (i.e. arena) = [ in[0], in[1], norm[0], norm[1], out[0], RETURN(long_gt) ]
 function long_div2(in){
     var norm[2] = long_scalar_mult(in);
     var out[1] = [long_gt(norm, norm)];
     return out;
 }
 
+// %0 (i.e. signal arena) = [ in[0], in[1] ]
+// %lvars = [ out[0] ]
+// %subcmps = []
 template Test() {
     signal input in[2];
 	var out[1] = long_div2(in);

diff --git a/circom/tests/loops/inner_conditional_3.circom b/circom/tests/loops/inner_conditional_3.circom
@@ -2,14 +2,18 @@ pragma circom 2.0.0;
 // REQUIRES: circom
 // RUN: rm -rf %t && mkdir %t && %circom --llvm -o %t %s | sed -n 's/.*Written successfully:.* \(.*\)/\1/p' | xargs cat | FileCheck %s --enable-var-scope
 
-// if condition is NOT known
+// Test: BranchBucket with unknown condition
+//
+// %0 (i.e. signal arena) = [ out, in ]
+// %lvars =  [ N, acc, i ]
+// %subcmps = []
 template InnerConditional3(N) {
     signal output out;
     signal input in;
 
     var acc = 0;
     for (var i = 1; i <= N; i++) {
-        if (in == 0) {
+        if (in == 0) { // unknown condition
             acc += i;
         } else {
             acc -= i;

diff --git a/circuit_passes/src/bucket_interpreter/mod.rs b/circuit_passes/src/bucket_interpreter/mod.rs
@@ -121,8 +121,8 @@ macro_rules! compute_or_execute_part_2 {
     };
 }
 
-/// Generate private "execute_with_loc_*" function for the given bucket type
-/// and public "execute_*" wrapper that simply converts the return to Result.
+/// Generate private `execute_with_loc_*` function for the given bucket type
+/// and public `execute_*` wrapper that simply converts the return to Result.
 macro_rules! gen_execute_wrapers {
     ($(#[$($attrss:meta)*])* $bucket_ty: ty) => {
         paste! {
@@ -147,8 +147,8 @@ macro_rules! gen_execute_wrapers {
     };
 }
 
-/// Generate private "compute_with_loc_*" function for the given bucket type
-/// and public "compute_*" wrapper that simply converts the return to Result.
+/// Generate private `compute_with_loc_*` function for the given bucket type
+/// and public `compute_*` wrapper that simply converts the return to Result.
 macro_rules! gen_compute_wrapers {
     ($(#[$($attrss:meta)*])* $bucket_ty: ty) => {
         paste! {

diff --git a/circuit_passes/src/passes/unreachable_code_removal.rs b/circuit_passes/src/passes/unreachable_code_removal.rs
@@ -109,6 +109,9 @@ impl CircuitTransformationPass for UnreachableRemovalPass<'_> {
             template,
             InterpreterFlags {
                 visit_unknown_condition_branches: true,
+                // Set `propagate_only_known_returns` so the BucketInterpreter will visit
+                //  all code that ~might~ be reachable and only skip that which occurs after
+                //  a return statement that is ~guaranteed~ to be reached during execution.
                 propagate_only_known_returns: true,
                 ..Default::default()
             },