Revise docs.

doc/src/engine/custom-syntax.md

@@ -4,7 +4,7 @@ Extend Rhai with Custom Syntax
 {{#include ../links.md}}
 
 
-For the ultimate advantageous, there is a built-in facility to _extend_ the Rhai language
+For the ultimate adventurous, there is a built-in facility to _extend_ the Rhai language
 with custom-defined _syntax_.
 
 But before going off to define the next weird statement type, heed this warning:
@@ -28,7 +28,7 @@ Where This Might Be Useful
 
 * Where a custom syntax _significantly_ simplifies the code and _significantly_ enhances understanding of the code's intent.
 
-* Where certain logic cannot be easily encapsulated inside a function.  This is usually the case where _closures_ are required, because Rhai does not have closures.
+* Where certain logic cannot be easily encapsulated inside a function.
 
 * Where you just want to confuse your user and make their lives miserable, because you can.
 
@@ -154,10 +154,10 @@ let result = engine.eval_expression_tree(context, scope, expr)?;
 
 New variables maybe declared (usually with a variable name that is passed in via `$ident$).
 
-It can simply be pushed into the [`scope`].
+It can simply be pushed into the [`Scope`].
 
 However, beware that all new variables must be declared _prior_ to evaluating any expression tree.
-In other words, any `scope.push(...)` calls must come _before_ any `engine::eval_expression_tree(...)` calls.
+In other words, any `Scope::push` calls must come _before_ any `Engine::eval_expression_tree` calls.
 
 ```rust
 let var_name = inputs[0].get_variable_name().unwrap().to_string();

doc/src/engine/func.md

@@ -11,9 +11,9 @@ Creating them is accomplished via the `Func` trait which contains `create_from_s
 (as well as its companion method `create_from_ast`):
 
 ```rust
-use rhai::{Engine, Func};                       // use 'Func' for 'create_from_script'
+use rhai::{Engine, Func};                   // use 'Func' for 'create_from_script'
 
-let engine = Engine::new();                     // create a new 'Engine' just for this
+let engine = Engine::new();                 // create a new 'Engine' just for this
 
 let script = "fn calc(x, y) { x + y.len < 42 }";
 
@@ -25,14 +25,14 @@ let script = "fn calc(x, y) { x + y.len < 42 }";
 let func = Func::<(i64, String), bool>::create_from_script(
 //                ^^^^^^^^^^^^^ function parameter types in tuple
 
-                engine,                         // the 'Engine' is consumed into the closure
-                script,                         // the script, notice number of parameters must match
-                "calc"                          // the entry-point function name
+                engine,                     // the 'Engine' is consumed into the closure
+                script,                     // the script, notice number of parameters must match
+                "calc"                      // the entry-point function name
 )?;
 
-func(123, "hello".to_string())? == false;       // call the closure
+func(123, "hello".to_string())? == false;   // call the closure
 
-schedule_callback(func);                        // pass it as a callback to another function
+schedule_callback(func);                    // pass it as a callback to another function
 
 // Although there is nothing you can't do by manually writing out the closure yourself...
 let engine = Engine::new();

doc/src/engine/optimize/semantics.md

@@ -8,13 +8,13 @@ Some optimizations can alter subtle semantics of the script.
 For example:
 
 ```rust
-if true {                   // condition always true
-    123.456;                // eliminated
-    hello;                  // eliminated, EVEN THOUGH the variable doesn't exist!
-    foo(42)                 // promoted up-level
+if true {           // condition always true
+    123.456;        // eliminated
+    hello;          // eliminated, EVEN THOUGH the variable doesn't exist!
+    foo(42)         // promoted up-level
 }
 
-foo(42)                     // <- the above optimizes to this
+foo(42)             // <- the above optimizes to this
 ```
 
 If the original script were evaluated instead, it would have been an error - the variable `hello` does not exist,

doc/src/engine/raw.md

@@ -1,4 +1,3 @@
-
 Raw `Engine`
 ===========
 

doc/src/engine/scope.md

@@ -31,19 +31,20 @@ let mut scope = Scope::new();
 scope
     .push("y", 42_i64)
     .push("z", 999_i64)
+    .push_constant("MY_NUMBER", 123_i64)            // constants can also be added
     .set_value("s", "hello, world!".to_string());   //'set_value' adds a variable when one doesn't exist
-                                                    // remember to use 'String', not '&str'
+                                                    //   remember to use 'String', not '&str'
 
 // First invocation
 engine.eval_with_scope::<()>(&mut scope, r"
-    let x = 4 + 5 - y + z + s.len;
+    let x = 4 + 5 - y + z + MY_NUMBER + s.len;
     y = 1;
 ")?;
 
 // Second invocation using the same state
 let result = engine.eval_with_scope::<i64>(&mut scope, "x")?;
 
-println!("result: {}", result);                     // prints 979
+println!("result: {}", result);                     // prints 1102
 
 // Variable y is changed in the script - read it with 'get_value'
 assert_eq!(scope.get_value::<i64>("y").expect("variable y should exist"), 1);