Put comments into example scripts.

scripts/array.rhai

@@ -1,4 +1,7 @@
 let x = [1, 2, 3];
-print(x[1]);
+
+print(x[1]);        // prints 2
+
 x[1] = 5;
-print(x[1]);
+
+print(x[1]);        // prints 5

scripts/assignment.rhai

@@ -1,2 +1,2 @@
 let x = 78;
-print(x)
+print(x);

scripts/comments.rhai

@@ -3,8 +3,8 @@
 let /* I am a spy in a variable declaration! */ x = 5;
 
 /* I am a simple
-   multiline comment */
+   multi-line comment */
 
-/* look /* at /* that, /* multiline */ comments */ can be */ nested */
+/* look /* at /* that, /* multi-line */ comments */ can be */ nested */
 
-/* sorrounded by */ x // comments
+/* surrounded by */ x // comments

scripts/for1.rhai

@@ -1,15 +1,17 @@
-let arr = [1,2,3,4]
-for a in arr {
-    for b in [10,20] {
-        print(a)
-        print(b)
-    }
-    if a == 3 {
-        break;
-    }
-}
-//print(a)
+// This script runs for-loops
 
-for i in range(0,5) {
-    print(i)
-}
+let arr = [1,2,3,4];
+
+for a in arr {
+    for b in [10, 20] {
+        print(a + "," + b);
+    }
+
+    if a == 3 { break; }
+}
+//print(a);                 // <- if you uncomment this line, the script will fail to run
+                            //    because 'a' is not defined here
+
+for i in range(0, 5) {      // runs through a range from 1 to 5 exclusive
+    print(i);
+}

scripts/function_decl1.rhai

@@ -1,5 +1,7 @@
+// This script defines a function and calls it
+
 fn bob() {
-    3
+    return 3;
 }
 
-print(bob())
+print(bob());       // should print 3

scripts/function_decl2.rhai

@@ -1,5 +1,12 @@
+// This script defines a function with two parameters
+
+let a = 3;
+
 fn addme(a, b) {
-    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
 }
 
-print(addme(3, 4))
+print(addme(a, 4));     // should print 46
+
+print(a);               // should print 3 - 'a' is never changed

scripts/function_decl3.rhai

@@ -1,5 +1,7 @@
+// This script defines a function with many parameters and calls it
+
 fn f(a, b, c, d, e, f) {
     a - b * c - d * e - f
 }
 
-print(f(100, 5, 2, 9, 6, 32))
+print(f(100, 5, 2, 9, 6, 32));      // should print 4

scripts/if1.rhai

@@ -1,5 +1,14 @@
-let a = true;
-if (a) {
-    let x = 56;
-    print(x);
-}
+let a = 42;
+let b = 123;
+let x = 999;
+
+if a > b {
+    print("a > b");
+} else if a < b {
+    print("a < b");
+
+    let x = 0;          // this 'x' shadows the global 'x'
+    print(x);           // should print 0
+} else {
+    print("a == b");
+}

scripts/loop.rhai

@@ -1,8 +1,12 @@
+// This script runs an infinite loop, ending it with a break statement
+
 let x = 10;
 
 // simulate do..while using loop
 loop {
     print(x);
+
     x = x - 1;
+
 	if x <= 0 { break; }
 }

scripts/op1.rhai

@@ -1 +1 @@
-print(34 + 12)
+print(34 + 12);     // should be 46

scripts/op2.rhai

@@ -1 +1,2 @@
-print(12 + 34 * 5)
+let x = 12 + 34 * 5;
+print(x);               // should be 182

scripts/op3.rhai

@@ -1 +1,2 @@
-print(0 + (12 + 34) * 5)
+let x = (12 + 34) * 5;
+print(x);               // should be 230

scripts/primes.rhai

@@ -1,6 +1,6 @@
-// This is a script to calculate prime numbers.
+// This script uses the Sieve of Eratosthenes to calculate prime numbers.
 
-const MAX_NUMBER_TO_CHECK = 10000;    // 1229 primes
+const MAX_NUMBER_TO_CHECK = 10_000;     // 1229 primes <= 10000
 
 let prime_mask = [];
 prime_mask.pad(MAX_NUMBER_TO_CHECK, true);
@@ -24,4 +24,3 @@ for p in range(2, MAX_NUMBER_TO_CHECK) {
 }
 
 print("Total " + total_primes_found + " primes.");
-

scripts/speed_test.rhai

@@ -1,5 +1,12 @@
-let x = 1000000;
+// This script runs 1 million iterations
+// to test the speed of the scripting engine.
+
+let x = 1_000_000;
+
+print("Ready... Go!");
+
 while x > 0 {
     x = x - 1;
 }
-print(x);
+
+print("Finished.");

scripts/string.rhai

@@ -1,7 +1,17 @@
+// This script tests string operations
+
 print("hello");
-print("this\nis \\ nice");
-print("40 hex is \x40");
-print("fun with unicode: \u2764 and \U0001F603");
-print("foo" + " " + "bar");
-print("foo" < "bar");
-print("foo" >= "bar");
+print("this\nis \\ nice");      // escape sequences
+print("40 hex is \x40");        // hex escape sequence
+print("unicode fun: \u2764");   // Unicode escape sequence
+print("more fun: \U0001F603");  // Unicode escape sequence
+print("foo" + " " + "bar");     // string building using strings
+print("foo" < "bar");           // string comparison
+print("foo" >= "bar");          // string comparison
+print("the answer is " + 42);   // string building using non-string types
+
+let s = "hello, world!";        // string variable
+print("length=" + s.len());     // should be 13
+
+s[s.len()-1] = '?';             // change the string
+print(s);                       // should print 'hello, world?'

scripts/while.rhai

@@ -1,3 +1,5 @@
+// This script runs a while loop
+
 let x = 10;
 
 while x > 0 {