Edit documentation.

doc/src/engine/optimize/index.md

@@ -0,0 +1,109 @@
+Script Optimization
+===================
+
+{{#include ../../links.md}}
+
+Rhai includes an _optimizer_ that tries to optimize a script after parsing.
+This can reduce resource utilization and increase execution speed.
+
+Script optimization can be turned off via the [`no_optimize`] feature.
+
+
+Dead Code Removal
+----------------
+
+For example, in the following:
+
+```rust
+{
+    let x = 999;            // NOT eliminated: variable may be used later on (perhaps even an 'eval')
+    123;                    // eliminated: no effect
+    "hello";                // eliminated: no effect
+    [1, 2, x, x*2, 5];      // eliminated: no effect
+    foo(42);                // NOT eliminated: the function 'foo' may have side-effects
+    666                     // NOT eliminated: this is the return value of the block,
+                            // and the block is the last one so this is the return value of the whole script
+}
+```
+
+Rhai attempts to eliminate _dead code_ (i.e. code that does nothing, for example an expression by itself as a statement,
+which is allowed in Rhai).
+
+The above script optimizes to:
+
+```rust
+{
+    let x = 999;
+    foo(42);
+    666
+}
+```
+
+
+Constants Propagation
+--------------------
+
+Constants propagation is used to remove dead code:
+
+```rust
+const ABC = true;
+if ABC || some_work() { print("done!"); }   // 'ABC' is constant so it is replaced by 'true'...
+if true || some_work() { print("done!"); }  // since '||' short-circuits, 'some_work' is never called
+if true { print("done!"); }                 // <- the line above is equivalent to this
+print("done!");                             // <- the line above is further simplified to this
+                                            //    because the condition is always true
+```
+
+These are quite effective for template-based machine-generated scripts where certain constant values
+are spliced into the script text in order to turn on/off certain sections.
+
+For fixed script texts, the constant values can be provided in a user-defined [`Scope`] object
+to the [`Engine`] for use in compilation and evaluation.
+
+
+Watch Out for Function Calls
+---------------------------
+
+Beware, however, that most operators are actually function calls, and those functions can be overridden,
+so they are not optimized away:
+
+```rust
+const DECISION = 1;
+
+if DECISION == 1 {          // NOT optimized away because you can define
+    :                       // your own '==' function to override the built-in default!
+    :
+} else if DECISION == 2 {   // same here, NOT optimized away
+    :
+} else if DECISION == 3 {   // same here, NOT optimized away
+    :
+} else {
+    :
+}
+```
+
+because no operator functions will be run (in order not to trigger side-effects) during the optimization process
+(unless the optimization level is set to [`OptimizationLevel::Full`]).
+
+So, instead, do this:
+
+```rust
+const DECISION_1 = true;
+const DECISION_2 = false;
+const DECISION_3 = false;
+
+if DECISION_1 {
+    :                       // this branch is kept and promoted to the parent level
+} else if DECISION_2 {
+    :                       // this branch is eliminated
+} else if DECISION_3 {
+    :                       // this branch is eliminated
+} else {
+    :                       // this branch is eliminated
+}
+```
+
+In general, boolean constants are most effective for the optimizer to automatically prune
+large `if`-`else` branches because they do not depend on operators.
+
+Alternatively, turn the optimizer to [`OptimizationLevel::Full`].

doc/src/engine/optimize/optimize-levels.md

@@ -3,10 +3,7 @@ Optimization Levels
 
 {{#include ../../links.md}}
 
-Set Optimization Level
----------------------
-
-There are actually three levels of optimizations: `None`, `Simple` and `Full`.
+There are three levels of optimization: `None`, `Simple` and `Full`.
 
 * `None` is obvious - no optimization on the AST is performed.
 
@@ -16,6 +13,10 @@ There are actually three levels of optimizations: `None`, `Simple` and `Full`.
 * `Full` is _much_ more aggressive, _including_ running functions on constant arguments to determine their result.
   One benefit to this is that many more optimization opportunities arise, especially with regards to comparison operators.
 
+
+Set Optimization Level
+---------------------
+
 An [`Engine`]'s optimization level is set via a call to `Engine::set_optimization_level`:
 
 ```rust

doc/src/engine/optimize/reoptimize.md

@@ -3,15 +3,38 @@ Re-Optimize an AST
 
 {{#include ../../links.md}}
 
-If it is ever needed to _re_-optimize an `AST`, use the `optimize_ast` method:
+Sometimes it is more efficient to store one single, large script with delimited code blocks guarded by
+constant variables.  This script is compiled once to an `AST`.
+
+Then, depending on the execution environment, constants are passed into the [`Engine`] and the `AST`
+is _re_-optimized based on those constants via the `Engine::optimize_ast` method,
+effectively pruning out unused code sections.
+
+The final, optimized `AST` is then used for evaluations.
 
 ```rust
-// Compile script to AST
-let ast = engine.compile("40 + 2")?;
+// Compile master script to AST
+let master_ast = engine.compile(
+r"
+    if SCENARIO_1 {
+        do_work();
+    } else if SCENARIO_2 {
+        do_something();
+    } else if SCENARIO_3 {
+        do_something_else();
+    } else {
+        do_nothing();
+    }
+")?;
 
-// Create a new 'Scope' - put constants in it to aid optimization if using 'OptimizationLevel::Full'
-let scope = Scope::new();
+// Create a new 'Scope' - put constants in it to aid optimization
+let mut scope = Scope::new();
+scope.push_constant("SCENARIO_1", true);
+scope.push_constant("SCENARIO_2", false);
+scope.push_constant("SCENARIO_3", false);
 
 // Re-optimize the AST
-let ast = engine.optimize_ast(&scope, &ast, OptimizationLevel::Full);
+let new_ast = engine.optimize_ast(&scope, master_ast.clone(), OptimizationLevel::Simple);
+
+// 'new_ast' is essentially: 'do_work()'
 ```