From 81666f8232c95d6532e0acbad787def5d58bf1da Mon Sep 17 00:00:00 2001
From: chriseth <chris@ethereum.org>
Date: Tue, 23 Nov 2021 10:42:18 +0100
Subject: [PATCH] Enhance documentation.

---
 libyul/optimiser/UnusedStoreBase.h                           | 5 +++++
 test/libyul/yulOptimizerTests/unusedAssignEliminator/for.yul | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/for_branch.yul  | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/for_break.yul   | 2 +-
 .../unusedAssignEliminator/for_continue.yul                  | 2 +-
 .../unusedAssignEliminator/for_continue_2.yul                | 2 +-
 .../unusedAssignEliminator/for_continue_3.yul                | 2 +-
 .../for_decl_inside_break_continue.yul                       | 2 +-
 .../unusedAssignEliminator/for_deep_noremove.yul             | 2 +-
 .../unusedAssignEliminator/for_deep_simple.yul               | 2 +-
 .../unusedAssignEliminator/for_multi_break.yul               | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/for_nested.yul  | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/for_rerun.yul   | 2 +-
 .../for_stmnts_after_break_continue.yul                      | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/function.yul    | 2 +-
 test/libyul/yulOptimizerTests/unusedAssignEliminator/if.yul  | 2 +-
 .../unusedAssignEliminator/if_overwrite_all_branches.yul     | 2 +-
 .../unusedAssignEliminator/if_used_in_one_branch.yul         | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/leave.yul       | 2 +-
 .../unusedAssignEliminator/multi_assign.yul                  | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/multivar.yul    | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/non_movable.yul | 2 +-
 .../unusedAssignEliminator/remove_break.yul                  | 2 +-
 .../unusedAssignEliminator/remove_continue.yul               | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/scopes.yul      | 2 +-
 .../yulOptimizerTests/unusedAssignEliminator/simple.yul      | 2 +-
 .../unusedAssignEliminator/switch_overwrite_in_all.yul       | 2 +-
 .../unusedAssignEliminator/switch_overwrite_in_one.yul       | 2 +-
 .../switch_overwrite_use_combination.yul                     | 2 +-
 .../unusedAssignEliminator/switch_unused.yul                 | 2 +-
 30 files changed, 34 insertions(+), 29 deletions(-)

diff --git a/libyul/optimiser/UnusedStoreBase.h b/libyul/optimiser/UnusedStoreBase.h
index a65af4e45a2b..3bd4e429766b 100644
--- a/libyul/optimiser/UnusedStoreBase.h
+++ b/libyul/optimiser/UnusedStoreBase.h
@@ -36,6 +36,11 @@ struct Dialect;
 /**
  * Base class for both UnusedAssignEliminator and UnusedStoreEliminator.
  *
+ * The class tracks the state of abstract "stores" (assignments or mstore/sstore
+ * statements) across the control-flow. It is the job of the derived class to create
+ * the stores and track references, but the base class adjusts their "used state" at
+ * control-flow splits and joins.
+ *
  * Prerequisite: Disambiguator, ForLoopInitRewriter.
  */
 class UnusedStoreBase: public ASTWalker
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for.yul
index 314963368082..89de8920cd25 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for.yul
@@ -8,7 +8,7 @@
     }
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let a := 2
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_branch.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_branch.yul
index 120b43ce81a5..8700c8d28b04 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_branch.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_branch.yul
@@ -14,7 +14,7 @@
     mstore(x, 0)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_break.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_break.yul
index 1b795ad8c73a..db55bf7588c1 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_break.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_break.yul
@@ -13,7 +13,7 @@
     mstore(x, 0x42)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue.yul
index 0ee9c551da7a..d3cfb0d84b0b 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue.yul
@@ -16,7 +16,7 @@
     x := 3
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue_2.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue_2.yul
index ee747ae5d040..2d5bae46e2ac 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue_2.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue_2.yul
@@ -13,7 +13,7 @@
     mstore(x, 0x42)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue_3.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue_3.yul
index b70f35d2bc27..d9980d376dae 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue_3.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_continue_3.yul
@@ -12,7 +12,7 @@
     }
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_decl_inside_break_continue.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_decl_inside_break_continue.yul
index f54b21af8b0b..94b100e2a9e9 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_decl_inside_break_continue.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_decl_inside_break_continue.yul
@@ -19,7 +19,7 @@
     mstore(x, 0x42)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x := 1
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_deep_noremove.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_deep_noremove.yul
index 5edd71d58b38..02a735f9e50f 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_deep_noremove.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_deep_noremove.yul
@@ -26,7 +26,7 @@
     x := 13
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x := 1
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_deep_simple.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_deep_simple.yul
index 5b086bab8a4d..039d856d96d0 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_deep_simple.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_deep_simple.yul
@@ -19,7 +19,7 @@
     }
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     for { } 1 { }
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_multi_break.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_multi_break.yul
index ce084b1ce168..3b18dcc8dcdc 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_multi_break.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_multi_break.yul
@@ -35,7 +35,7 @@
     mstore(x, 0x42)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x := 1
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_nested.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_nested.yul
index a83f536668dc..101101b92320 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_nested.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_nested.yul
@@ -32,7 +32,7 @@
     mstore(x, 0x42)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x := 1
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_rerun.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_rerun.yul
index 5d1e60738568..08cf63a52d65 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_rerun.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_rerun.yul
@@ -11,7 +11,7 @@
     x := 3
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_stmnts_after_break_continue.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_stmnts_after_break_continue.yul
index 5e88df9689ca..1a92d3b8413c 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_stmnts_after_break_continue.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/for_stmnts_after_break_continue.yul
@@ -23,7 +23,7 @@
     mstore(x, 0x42)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x := 1
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/function.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/function.yul
index 2a20ca8b69bb..044a5f418f85 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/function.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/function.yul
@@ -12,7 +12,7 @@
     r := 2
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let r
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/if.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/if.yul
index 2fab04a36fba..7c65680ae6a3 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/if.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/if.yul
@@ -10,7 +10,7 @@
     mstore(0, d)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let c
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/if_overwrite_all_branches.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/if_overwrite_all_branches.yul
index 7585f848a2b2..860050e59dd3 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/if_overwrite_all_branches.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/if_overwrite_all_branches.yul
@@ -11,7 +11,7 @@
     mstore(0, d)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let c
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/if_used_in_one_branch.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/if_used_in_one_branch.yul
index 637a32c02a2e..90643f174cae 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/if_used_in_one_branch.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/if_used_in_one_branch.yul
@@ -11,7 +11,7 @@
     mstore(0, d)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let c
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/leave.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/leave.yul
index 1caee198a10d..82bf493470c8 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/leave.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/leave.yul
@@ -21,7 +21,7 @@
     }
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     function f(a, b) -> x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/multi_assign.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/multi_assign.yul
index f0845680f40c..d4b35e7ee1f0 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/multi_assign.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/multi_assign.yul
@@ -9,7 +9,7 @@
     y := 4
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     function f() -> a, b
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/multivar.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/multivar.yul
index 2b13ba3c36b8..d4dda8f902fa 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/multivar.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/multivar.yul
@@ -6,7 +6,7 @@
     a := b
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let a := 2
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/non_movable.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/non_movable.yul
index 343c672dea0c..e131b3549e16 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/non_movable.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/non_movable.yul
@@ -4,7 +4,7 @@
     a := mload(0)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let a
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/remove_break.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/remove_break.yul
index 035f66d3851e..76a536c2f371 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/remove_break.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/remove_break.yul
@@ -12,7 +12,7 @@
     }
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let i := 0
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/remove_continue.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/remove_continue.yul
index c4f3b3e43ff3..27083a73c285 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/remove_continue.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/remove_continue.yul
@@ -13,7 +13,7 @@
 }
 
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let i := 0
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/scopes.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/scopes.yul
index d3c6cb4a6da0..bc2d4d80f6ff 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/scopes.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/scopes.yul
@@ -7,7 +7,7 @@
     }
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let a
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/simple.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/simple.yul
index 12b9ae6b7140..326ce29dcd45 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/simple.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/simple.yul
@@ -4,6 +4,6 @@
     a := 2
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // { let a }
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_in_all.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_in_all.yul
index a39cdedd7029..a6b77f897361 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_in_all.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_in_all.yul
@@ -8,7 +8,7 @@
     mstore(x, 0)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_in_one.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_in_one.yul
index 271bb4864c7a..9b0a23cd883f 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_in_one.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_in_one.yul
@@ -7,7 +7,7 @@
     mstore(x, 0)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_use_combination.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_use_combination.yul
index 8d38dcc161d4..611123db367b 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_use_combination.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_overwrite_use_combination.yul
@@ -8,7 +8,7 @@
     mstore(x, 0)
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x
diff --git a/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_unused.yul b/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_unused.yul
index 94de51b8893d..c15c8899192d 100644
--- a/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_unused.yul
+++ b/test/libyul/yulOptimizerTests/unusedAssignEliminator/switch_unused.yul
@@ -6,7 +6,7 @@
     case 0 { mstore(0, 1) }
 }
 // ----
-// step: redundantAssignEliminator
+// step: unusedAssignEliminator
 //
 // {
 //     let x