Format example scripts better.

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}`);

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 } }`);
 }

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; }

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;
 }

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();
 }

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}`);

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

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);

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) {

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");

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

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;
 

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];
             }

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}`);

scripts/op1.rhai

@@ -1,3 +1,5 @@
+// This script runs a single expression.
+
 print("The result should be 46:");
 
 print(34 + 12);

scripts/op2.rhai

@@ -1,3 +1,5 @@
+// This script runs a complex expression.
+
 print("The result should be 182:");
 
 let x = 12 + 34 * 5;

scripts/op3.rhai

@@ -1,3 +1,5 @@
+// This script runs a complex expression.
+
 print("The result should be 230:");
 
 let x = (12 + 34) * 5;

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;

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

scripts/strings_map.rhai

@@ -1,3 +1,5 @@
+// This script tests object maps and strings.
+
 print("Ready... Go!");
 
 let now = timestamp();

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)}`)
     }
 }

scripts/while.rhai

@@ -1,4 +1,4 @@
-// This script runs a while loop
+// This script runs a while loop.
 
 let x = 10;