From b63b4cb3af921019c11d3e01a023ff1e0a2e85ad Mon Sep 17 00:00:00 2001
From: Stephen Chung <schungx@live.com>
Date: Thu, 20 Jan 2022 12:06:36 +0800
Subject: [PATCH] Format example scripts better.

---
 scripts/assignment.rhai     |  4 ++--
 scripts/doc-comments.rhai   | 13 ++++++++++---
 scripts/for1.rhai           |  3 ++-
 scripts/for2.rhai           |  4 ++++
 scripts/for3.rhai           |  4 ++++
 scripts/function_decl1.rhai |  8 ++++----
 scripts/function_decl2.rhai | 10 +++++-----
 scripts/function_decl3.rhai |  6 ++++--
 scripts/function_decl4.rhai |  2 +-
 scripts/if1.rhai            |  4 +++-
 scripts/if2.rhai            |  4 +++-
 scripts/loop.rhai           |  2 +-
 scripts/mat_mul.rhai        | 12 +++++++-----
 scripts/module.rhai         |  2 ++
 scripts/op1.rhai            |  2 ++
 scripts/op2.rhai            |  2 ++
 scripts/op3.rhai            |  2 ++
 scripts/speed_test.rhai     |  3 +--
 scripts/string.rhai         |  2 +-
 scripts/strings_map.rhai    |  2 ++
 scripts/switch.rhai         |  9 +++++++++
 scripts/while.rhai          |  2 +-
 22 files changed, 72 insertions(+), 30 deletions(-)

diff --git a/scripts/assignment.rhai b/scripts/assignment.rhai
index 93a03c45..2d713b43 100644
--- a/scripts/assignment.rhai
+++ b/scripts/assignment.rhai
@@ -1,5 +1,5 @@
-print("x should be 78:");
+// This script contains a single assignment statement.
 
 let x = 78;
 
-print(x);
+print(`x should be 78: ${x}`);
diff --git a/scripts/doc-comments.rhai b/scripts/doc-comments.rhai
index 9245065d..6717039f 100644
--- a/scripts/doc-comments.rhai
+++ b/scripts/doc-comments.rhai
@@ -3,9 +3,9 @@
 ///
 /// # Parameters
 ///
-/// `x` - `i64`  
-/// `y` - `string`  
-/// `z` - `bool`
+/// * `x` - `i64`
+/// * `y` - `string`
+/// * `z` - `bool`
 ///
 /// # Notes
 ///
@@ -13,6 +13,13 @@
 ///
 /// An example is the `rhai-doc` app.
 ///
+/// # Example
+///
+/// ```rhai
+/// let x = foo(42, "hello", true);
+///
+/// print(x);     // prints 47
+/// ```
 fn foo(x, y, z) {
    print(`hello, world! ${if z { x + y.len() } else { x } }`);
 }
diff --git a/scripts/for1.rhai b/scripts/for1.rhai
index 4818b202..fe022762 100644
--- a/scripts/for1.rhai
+++ b/scripts/for1.rhai
@@ -1,7 +1,8 @@
-// This script runs for-loops
+// This script runs for-loops.
 
 let arr = [1, true, 123.456, "hello", 3, 42];
 
+// Loop over array with counter
 for (a, i) in arr {
     for (b, j) in ['x', 42, (), 123, 99, 0.5] {
         if b > 100 { continue; }
diff --git a/scripts/for2.rhai b/scripts/for2.rhai
index 5ded413a..478f53c9 100644
--- a/scripts/for2.rhai
+++ b/scripts/for2.rhai
@@ -1,3 +1,5 @@
+// This script runs for-loops
+
 const MAX = 1_000_000;
 
 print(`Iterating an array with ${MAX} items...`);
@@ -8,6 +10,7 @@ let now = timestamp();
 
 let list = [];
 
+// Loop over range
 for i in 0..MAX {
     list.push(i);
 }
@@ -16,6 +19,7 @@ print(`Time = ${now.elapsed} seconds...`);
 
 let sum = 0;
 
+// Loop over array
 for i in list {
     sum += i;
 }
diff --git a/scripts/for3.rhai b/scripts/for3.rhai
index de799684..d370a388 100644
--- a/scripts/for3.rhai
+++ b/scripts/for3.rhai
@@ -1,3 +1,5 @@
+// This script runs for-loops with closures.
+
 const MAX = 100;
 const CHECK = ((MAX - 1) ** 2) * MAX;
 
@@ -9,6 +11,7 @@ print(`Creating ${MAX} closures...`);
 
 let list = [];
 
+// Loop over range
 for i in 0..MAX {
     list.push(|| i ** 2);
 }
@@ -18,6 +21,7 @@ print(`Summing ${MAX} closures...`);
 
 let sum = 0;
 
+// Loop over array
 for f in list {
     sum += f.call();
 }
diff --git a/scripts/function_decl1.rhai b/scripts/function_decl1.rhai
index 2e6a8958..8c237760 100644
--- a/scripts/function_decl1.rhai
+++ b/scripts/function_decl1.rhai
@@ -1,9 +1,9 @@
-// This script defines a function and calls it
+// This script defines a function and calls it.
 
-fn bob() {
+fn call_me() {
     return 3;
 }
 
-let result = bob();
+let result = call_me();
 
-print(`bob() should be 3: ${result}`);
+print(`call_me() should be 3: ${result}`);
diff --git a/scripts/function_decl2.rhai b/scripts/function_decl2.rhai
index 99507209..3640537f 100644
--- a/scripts/function_decl2.rhai
+++ b/scripts/function_decl2.rhai
@@ -1,14 +1,14 @@
-// This script defines a function with two parameters
+// This script defines a function with two parameters and local variables.
 
 let a = 3;
 
-fn addme(a, b) {
+fn add(a, b) {
     a = 42;             // notice that 'a' is passed by value
     a + b;              // notice that the last value is returned even if terminated by a semicolon
 }
 
-let result = addme(a, 4);
+let result = add(a, 4);
 
-print(`addme(a, 4) should be 46: ${result}`);
+print(`add(a, 4) should be 46: ${result}`);
 
-print(`a should still be 3: ${a}`);     // should print 3 - 'a' is never changed
+print(`a should still be 3: ${a}`);     // prints 3: 'a' is never changed
diff --git a/scripts/function_decl3.rhai b/scripts/function_decl3.rhai
index c1c84631..2cc9c6d9 100644
--- a/scripts/function_decl3.rhai
+++ b/scripts/function_decl3.rhai
@@ -1,9 +1,11 @@
-// This script defines a function with many parameters and calls it
+// This script defines a function with many parameters.
+// 
 
 const KEY = 38;
 
 fn f(a, b, c, d, e, f) {
-    a - b * c - d * e - f + global::KEY
+    let x = global::KEY;        // <- access global module
+    a - b * c - d * e - f + x
 }
 
 let result = f(100, 5, 2, 9, 6, 32);
diff --git a/scripts/function_decl4.rhai b/scripts/function_decl4.rhai
index a09ed3fc..e5bc9271 100644
--- a/scripts/function_decl4.rhai
+++ b/scripts/function_decl4.rhai
@@ -1,4 +1,4 @@
-// This script defines a function that acts as a method
+// This script defines a function that acts as a method.
 
 // Use 'this' to refer to the object of a method call
 fn action(x, y) {
diff --git a/scripts/if1.rhai b/scripts/if1.rhai
index 4e264d64..ed74c227 100644
--- a/scripts/if1.rhai
+++ b/scripts/if1.rhai
@@ -1,3 +1,5 @@
+// This script runs if statements.
+
 let a = 42;
 let b = 123;
 let x = 999;
@@ -7,7 +9,7 @@ if a > b {
 } else if a < b {
     print("a < b, x should be 0");
 
-    let x = 0;          // this 'x' shadows the global 'x'
+    let x = 0;          // <- this 'x' shadows the global 'x'
     print(x);           // should print 0
 } else {
     print("Oops! a == b");
diff --git a/scripts/if2.rhai b/scripts/if2.rhai
index a42bb337..202fac89 100644
--- a/scripts/if2.rhai
+++ b/scripts/if2.rhai
@@ -1,7 +1,9 @@
+// This script runs an if expression.
+
 let a = 42;
 let b = 123;
 
-let x = if a <= b {         // if-expression
+let x = if a <= b {         // <- if-expression
     b - a
 } else {
     a - b
diff --git a/scripts/loop.rhai b/scripts/loop.rhai
index 707152c4..0cfab44d 100644
--- a/scripts/loop.rhai
+++ b/scripts/loop.rhai
@@ -1,4 +1,4 @@
-// This script runs an infinite loop, ending it with a break statement
+// This script runs an infinite loop, ending it with a break statement.
 
 let x = 10;
 
diff --git a/scripts/mat_mul.rhai b/scripts/mat_mul.rhai
index 35b1df70..40283aa7 100644
--- a/scripts/mat_mul.rhai
+++ b/scripts/mat_mul.rhai
@@ -1,12 +1,14 @@
+// This script simulates multi-dimensional matrix calculations.
+
 const SIZE = 50;
 
 fn new_mat(x, y) {
     let row = [];
     row.pad(y, 0.0);
-    
+
     let matrix = [];
     matrix.pad(x, row);
-    
+
     matrix
 }
 
@@ -20,13 +22,13 @@ fn mat_gen() {
             m[i][j] = tmp * (i - j) * (i + j);
         }
     }
-    
+
     m
 }
 
 fn mat_mul(a, b) {
     let b2 = new_mat(a[0].len, b[0].len);
-    
+
     for i in 0..a[0].len {
         for j in 0..b[0].len {
             b2[j][i] = b[i][j];
@@ -38,7 +40,7 @@ fn mat_mul(a, b) {
     for i in 0..c.len {
         for j in 0..c[i].len {
             c[i][j] = 0.0;
-            
+
             for z in 0..a[i].len {
                 c[i][j] += a[i][z] * b2[j][z];
             }
diff --git a/scripts/module.rhai b/scripts/module.rhai
index f92fb162..29a6704d 100644
--- a/scripts/module.rhai
+++ b/scripts/module.rhai
@@ -1,3 +1,5 @@
+// This script imports an external script as a module.
+
 import "loop" as x;
 
 print(`Module test! foo = ${x::foo}`);
diff --git a/scripts/op1.rhai b/scripts/op1.rhai
index bedfa563..27333f9a 100644
--- a/scripts/op1.rhai
+++ b/scripts/op1.rhai
@@ -1,3 +1,5 @@
+// This script runs a single expression.
+
 print("The result should be 46:");
 
 print(34 + 12);
diff --git a/scripts/op2.rhai b/scripts/op2.rhai
index 471e8ee4..37481557 100644
--- a/scripts/op2.rhai
+++ b/scripts/op2.rhai
@@ -1,3 +1,5 @@
+// This script runs a complex expression.
+
 print("The result should be 182:");
 
 let x = 12 + 34 * 5;
diff --git a/scripts/op3.rhai b/scripts/op3.rhai
index 73cec23b..30f57dcc 100644
--- a/scripts/op3.rhai
+++ b/scripts/op3.rhai
@@ -1,3 +1,5 @@
+// This script runs a complex expression.
+
 print("The result should be 230:");
 
 let x = (12 + 34) * 5;
diff --git a/scripts/speed_test.rhai b/scripts/speed_test.rhai
index d07dadf3..219ddb71 100644
--- a/scripts/speed_test.rhai
+++ b/scripts/speed_test.rhai
@@ -1,5 +1,4 @@
-// This script runs 1 million iterations
-// to test the speed of the scripting engine.
+// This script runs 1 million iterations to test the speed of the scripting engine.
 
 let now = timestamp();
 let x = 1_000_000;
diff --git a/scripts/string.rhai b/scripts/string.rhai
index 21ea022b..12d9a75e 100644
--- a/scripts/string.rhai
+++ b/scripts/string.rhai
@@ -1,4 +1,4 @@
-// This script tests string operations
+// This script tests string operations.
 
 print("hello");
 print("this\nis \\ nice");      // escape sequences
diff --git a/scripts/strings_map.rhai b/scripts/strings_map.rhai
index ec528ecf..0acaf361 100644
--- a/scripts/strings_map.rhai
+++ b/scripts/strings_map.rhai
@@ -1,3 +1,5 @@
+// This script tests object maps and strings.
+
 print("Ready... Go!");
 
 let now = timestamp();
diff --git a/scripts/switch.rhai b/scripts/switch.rhai
index 971ff989..77292630 100644
--- a/scripts/switch.rhai
+++ b/scripts/switch.rhai
@@ -1,13 +1,22 @@
+// This script runs a switch statement in a for-loop.
+
 let arr = [42, 123.456, "hello", true, "hey", 'x', 999, 1, 2, 3, 4];
 
 for item in arr {
     switch item {
+        // Match single integer
         42 => print("The Answer!"),
+        // Match single floating-point number
         123.456 => print(`Floating point... ${item}`),
+        // Match single string
         "hello" => print(`${item} world!`),
+        // Match another integer
         999 => print(`Got 999: ${item}`),
+        // Match range with condition
         0..100 if item % 2 == 0 => print(`A small even number: ${item}`),
+        // Match another range
         0..100 => print(`A small odd number: ${item}`),
+        // Default case
         _ => print(`Something else: <${item}> is ${type_of(item)}`)
     }
 }
diff --git a/scripts/while.rhai b/scripts/while.rhai
index e17493b2..0dd575c1 100644
--- a/scripts/while.rhai
+++ b/scripts/while.rhai
@@ -1,4 +1,4 @@
-// This script runs a while loop
+// This script runs a while loop.
 
 let x = 10;