From 45acb65f4feb93b50cbe3540be4f4cc93ad77022 Mon Sep 17 00:00:00 2001
From: Stephen Chung <schungx@live.com>
Date: Sun, 24 Jul 2022 23:03:35 +0800
Subject: [PATCH] Use //! for script docs.

---
 examples/event_handler_js/script.rhai   | 2 +-
 examples/event_handler_main/script.rhai | 2 +-
 examples/event_handler_map/script.rhai  | 2 +-
 scripts/assignment.rhai                 | 2 +-
 scripts/doc-comments.rhai               | 2 ++
 scripts/fibonacci.rhai                  | 4 ++--
 scripts/for1.rhai                       | 2 +-
 scripts/for2.rhai                       | 2 +-
 scripts/for3.rhai                       | 2 +-
 scripts/function_decl1.rhai             | 2 +-
 scripts/function_decl2.rhai             | 2 +-
 scripts/function_decl3.rhai             | 3 +--
 scripts/function_decl4.rhai             | 2 +-
 scripts/if1.rhai                        | 2 +-
 scripts/if2.rhai                        | 2 +-
 scripts/loop.rhai                       | 2 +-
 scripts/mat_mul.rhai                    | 2 +-
 scripts/module.rhai                     | 2 +-
 scripts/oop.rhai                        | 2 +-
 scripts/op1.rhai                        | 2 +-
 scripts/op2.rhai                        | 2 +-
 scripts/op3.rhai                        | 2 +-
 scripts/primes.rhai                     | 2 +-
 scripts/speed_test.rhai                 | 2 +-
 scripts/string.rhai                     | 2 +-
 scripts/strings_map.rhai                | 2 +-
 scripts/switch.rhai                     | 2 +-
 scripts/while.rhai                      | 2 +-
 28 files changed, 30 insertions(+), 29 deletions(-)

diff --git a/examples/event_handler_js/script.rhai b/examples/event_handler_js/script.rhai
index 7c488515..0667575f 100644
--- a/examples/event_handler_js/script.rhai
+++ b/examples/event_handler_js/script.rhai
@@ -1,4 +1,4 @@
-// Implementation of the Event Handler With State Pattern - JS Style
+//! Implementation of the Event Handler With State Pattern - JS Style
 
 /// Initialize user-provided state.
 fn init() {
diff --git a/examples/event_handler_main/script.rhai b/examples/event_handler_main/script.rhai
index 641c2372..a2097e12 100644
--- a/examples/event_handler_main/script.rhai
+++ b/examples/event_handler_main/script.rhai
@@ -1,4 +1,4 @@
-// Implementation of the Event Handler With State Pattern - Main Style
+//! Implementation of the Event Handler With State Pattern - Main Style
 
 /// Initialize user-provided state (shadows system-provided state, if any).
 fn init() {
diff --git a/examples/event_handler_map/script.rhai b/examples/event_handler_map/script.rhai
index 988ca170..59c55f79 100644
--- a/examples/event_handler_map/script.rhai
+++ b/examples/event_handler_map/script.rhai
@@ -1,4 +1,4 @@
-// Implementation of the Event Handler With State Pattern - Map Style
+//! Implementation of the Event Handler With State Pattern - Map Style
 
 /// Initialize user-provided state.
 /// State is stored inside an object map bound to 'state'.
diff --git a/scripts/assignment.rhai b/scripts/assignment.rhai
index 2d713b43..68802a75 100644
--- a/scripts/assignment.rhai
+++ b/scripts/assignment.rhai
@@ -1,4 +1,4 @@
-// This script contains a single assignment statement.
+//! This script contains a single assignment statement.
 
 let x = 78;
 
diff --git a/scripts/doc-comments.rhai b/scripts/doc-comments.rhai
index 6717039f..f2a56ffe 100644
--- a/scripts/doc-comments.rhai
+++ b/scripts/doc-comments.rhai
@@ -1,3 +1,5 @@
+//! This script illustrates how to put doc-comments on functions.
+
 /// The function `foo`, which prints `hello, world!` and a magic number,
 /// accepts three parameters.
 ///
diff --git a/scripts/fibonacci.rhai b/scripts/fibonacci.rhai
index 97c93d08..92015718 100644
--- a/scripts/fibonacci.rhai
+++ b/scripts/fibonacci.rhai
@@ -1,5 +1,5 @@
-// This script calculates the n-th Fibonacci number using a really dumb algorithm
-// to test the speed of the scripting engine.
+//! This script calculates the n-th Fibonacci number using a really dumb algorithm
+//! to test the speed of the scripting engine.
 
 const TARGET = 28;
 const REPEAT = 5;
diff --git a/scripts/for1.rhai b/scripts/for1.rhai
index fe022762..6d4062e8 100644
--- a/scripts/for1.rhai
+++ b/scripts/for1.rhai
@@ -1,4 +1,4 @@
-// This script runs for-loops.
+//! This script runs for-loops.
 
 let arr = [1, true, 123.456, "hello", 3, 42];
 
diff --git a/scripts/for2.rhai b/scripts/for2.rhai
index 478f53c9..010a3a00 100644
--- a/scripts/for2.rhai
+++ b/scripts/for2.rhai
@@ -1,4 +1,4 @@
-// This script runs for-loops
+//! This script runs for-loops
 
 const MAX = 1_000_000;
 
diff --git a/scripts/for3.rhai b/scripts/for3.rhai
index d370a388..eac49194 100644
--- a/scripts/for3.rhai
+++ b/scripts/for3.rhai
@@ -1,4 +1,4 @@
-// This script runs for-loops with closures.
+//! This script runs for-loops with closures.
 
 const MAX = 100;
 const CHECK = ((MAX - 1) ** 2) * MAX;
diff --git a/scripts/function_decl1.rhai b/scripts/function_decl1.rhai
index 8c237760..d358b4b3 100644
--- a/scripts/function_decl1.rhai
+++ b/scripts/function_decl1.rhai
@@ -1,4 +1,4 @@
-// This script defines a function and calls it.
+//! This script defines a function and calls it.
 
 fn call_me() {
     return 3;
diff --git a/scripts/function_decl2.rhai b/scripts/function_decl2.rhai
index 3640537f..7ce09e3a 100644
--- a/scripts/function_decl2.rhai
+++ b/scripts/function_decl2.rhai
@@ -1,4 +1,4 @@
-// This script defines a function with two parameters and local variables.
+//! This script defines a function with two parameters and local variables.
 
 let a = 3;
 
diff --git a/scripts/function_decl3.rhai b/scripts/function_decl3.rhai
index 2cc9c6d9..9ce0b508 100644
--- a/scripts/function_decl3.rhai
+++ b/scripts/function_decl3.rhai
@@ -1,5 +1,4 @@
-// This script defines a function with many parameters.
-// 
+//! This script defines a function with many parameters.
 
 const KEY = 38;
 
diff --git a/scripts/function_decl4.rhai b/scripts/function_decl4.rhai
index e5bc9271..07ae2bef 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 ed74c227..92830b3f 100644
--- a/scripts/if1.rhai
+++ b/scripts/if1.rhai
@@ -1,4 +1,4 @@
-// This script runs if statements.
+//! This script runs if statements.
 
 let a = 42;
 let b = 123;
diff --git a/scripts/if2.rhai b/scripts/if2.rhai
index 202fac89..15e855ba 100644
--- a/scripts/if2.rhai
+++ b/scripts/if2.rhai
@@ -1,4 +1,4 @@
-// This script runs an if expression.
+//! This script runs an if expression.
 
 let a = 42;
 let b = 123;
diff --git a/scripts/loop.rhai b/scripts/loop.rhai
index 0cfab44d..8f843c22 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 40283aa7..9830a66f 100644
--- a/scripts/mat_mul.rhai
+++ b/scripts/mat_mul.rhai
@@ -1,4 +1,4 @@
-// This script simulates multi-dimensional matrix calculations.
+//! This script simulates multi-dimensional matrix calculations.
 
 const SIZE = 50;
 
diff --git a/scripts/module.rhai b/scripts/module.rhai
index 29a6704d..fc92ec19 100644
--- a/scripts/module.rhai
+++ b/scripts/module.rhai
@@ -1,4 +1,4 @@
-// This script imports an external script as a module.
+//! This script imports an external script as a module.
 
 import "loop" as x;
 
diff --git a/scripts/oop.rhai b/scripts/oop.rhai
index 8caf6d87..2c2ecd3d 100644
--- a/scripts/oop.rhai
+++ b/scripts/oop.rhai
@@ -1,4 +1,4 @@
-// This script simulates object-oriented programming (OOP) techniques using closures.
+//! This script simulates object-oriented programming (OOP) techniques using closures.
 
 // External variable that will be captured.
 let last_value = ();
diff --git a/scripts/op1.rhai b/scripts/op1.rhai
index 27333f9a..daf13f49 100644
--- a/scripts/op1.rhai
+++ b/scripts/op1.rhai
@@ -1,4 +1,4 @@
-// This script runs a single expression.
+//! This script runs a single expression.
 
 print("The result should be 46:");
 
diff --git a/scripts/op2.rhai b/scripts/op2.rhai
index 37481557..94163a8b 100644
--- a/scripts/op2.rhai
+++ b/scripts/op2.rhai
@@ -1,4 +1,4 @@
-// This script runs a complex expression.
+//! This script runs a complex expression.
 
 print("The result should be 182:");
 
diff --git a/scripts/op3.rhai b/scripts/op3.rhai
index 30f57dcc..dc1bd997 100644
--- a/scripts/op3.rhai
+++ b/scripts/op3.rhai
@@ -1,4 +1,4 @@
-// This script runs a complex expression.
+//! This script runs a complex expression.
 
 print("The result should be 230:");
 
diff --git a/scripts/primes.rhai b/scripts/primes.rhai
index a827de5f..81db2b2c 100644
--- a/scripts/primes.rhai
+++ b/scripts/primes.rhai
@@ -1,4 +1,4 @@
-// This script uses the Sieve of Eratosthenes to calculate prime numbers.
+//! This script uses the Sieve of Eratosthenes to calculate prime numbers.
 
 let now = timestamp();
 
diff --git a/scripts/speed_test.rhai b/scripts/speed_test.rhai
index 219ddb71..a5207dcb 100644
--- a/scripts/speed_test.rhai
+++ b/scripts/speed_test.rhai
@@ -1,4 +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 12d9a75e..66f51834 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 0acaf361..88ae45df 100644
--- a/scripts/strings_map.rhai
+++ b/scripts/strings_map.rhai
@@ -1,4 +1,4 @@
-// This script tests object maps and strings.
+//! This script tests object maps and strings.
 
 print("Ready... Go!");
 
diff --git a/scripts/switch.rhai b/scripts/switch.rhai
index 77292630..8e2bb6e1 100644
--- a/scripts/switch.rhai
+++ b/scripts/switch.rhai
@@ -1,4 +1,4 @@
-// This script runs a switch statement in a for-loop.
+//! This script runs a switch statement in a for-loop.
 
 let arr = [42, 123.456, "hello", true, "hey", 'x', 999, 1, 2, 3, 4];
 
diff --git a/scripts/while.rhai b/scripts/while.rhai
index 0dd575c1..21c0681d 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;