Refine docs.

doc/src/SUMMARY.md

@@ -127,19 +127,22 @@ The Rhai Scripting Language
    7. [One Engine Instance Per Call](patterns/parallel.md)
    8. [Scriptable Event Handler with State](patterns/events.md)
    9. [Dynamic Constants Provider](patterns/dynamic-const.md)
-9.  [Advanced Topics](advanced.md)
-   10. [Capture Scope for Function Call](language/fn-capture.md)
-   11. [Low-Level API](rust/register-raw.md)
-   12. [Variable Resolver](engine/var.md)
-   13. [Use as DSL](engine/dsl.md)
+9. [Advanced Topics](advanced.md)
+   1. [Capture Scope for Function Call](language/fn-capture.md)
+   2. [Low-Level API](rust/register-raw.md)
+   3. [Variable Resolver](engine/var.md)
+   4. [Use as DSL](engine/dsl.md)
       1. [Disable Keywords and/or Operators](engine/disable.md)
       2. [Custom Operators](engine/custom-op.md)
       3. [Extending with Custom Syntax](engine/custom-syntax.md)
-   14. [Multiple Instantiation](patterns/multiple.md)
-   15. [Functions Metadata](engine/metadata/index.md)
-      4. [Generate Function Signatures](engine/metadata/gen_fn_sig.md)
-      5. [Export Metadata to JSON](engine/metadata/export_to_json.md)
-10. [Appendix](appendix/index.md)
+   5. [Multiple Instantiation](patterns/multiple.md)
+   6. [Functions Metadata](engine/metadata/index.md)
+      1. [Generate Function Signatures](engine/metadata/gen_fn_sig.md)
+      2. [Export Metadata to JSON](engine/metadata/export_to_json.md)
+10. [External Tools](tools/index.md)
+    1. [Online Playground](tools/playground.md)
+    2. [`rhai-doc`](tools/rhai-doc.md)
+11. [Appendix](appendix/index.md)
     1. [Keywords](appendix/keywords.md)
     2. [Operators and Symbols](appendix/operators.md)
     3. [Literals](appendix/literals.md)

doc/src/about/related.md

@@ -15,13 +15,19 @@ Online Resources for Rhai
 
 * [`LIB.RS`](https://lib.rs/crates/rhai) - Rhai library info
 
-* [Online Playground][playground] - Run scripts directly from editor
-
 * [Discord Chat](https://discord.gg/HquqbYFcZ9) - Rhai channel
 
 * [Reddit](https://www.reddit.com/r/Rhai) - Rhai community
 
 
+External Tools
+--------------
+
+* [Online Playground][playground] - Run Rhai scripts directly from an editor in the browser
+
+* [`rhai-doc`] - Rhai script documentation tool
+
+
 Other Cool Projects
 -------------------
 

doc/src/engine/call-fn.md

@@ -41,8 +41,8 @@ let mut scope = Scope::new();
 // If arguments of the wrong types are passed, the Engine will not find the function.
 
 let result: i64 = engine.call_fn(&mut scope, &ast, "hello", ( String::from("abc"), 123_i64 ) )?;
-//                                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-//                                                          put arguments in a tuple
+//          ^^^                                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+//        return type must be specified                          put arguments in a tuple
 
 let result: i64 = engine.call_fn(&mut scope, &ast, "hello", (123_i64,) )?;
 //                                                          ^^^^^^^^^^ tuple of one

doc/src/engine/custom-op.md

@@ -6,7 +6,8 @@ Custom Operators
 For use as a DSL (Domain-Specific Languages), it is sometimes more convenient to augment Rhai with
 customized operators performing specific logic.
 
-`Engine::register_custom_operator` registers a keyword as a custom operator.
+`Engine::register_custom_operator` registers a keyword as a custom operator, giving it a particular
+_precedence_ (which cannot be zero).
 
 
 Example
@@ -52,15 +53,23 @@ into a syntax that uses the corresponding function calls.
 Using `Engine::register_custom_operator` merely enables a convenient shortcut.
 
 
-Must Follow Variable Naming
---------------------------
+Must be a Valid Identifier or Reserved Symbol
+--------------------------------------------
 
 All custom operators must be _identifiers_ that follow the same naming rules as [variables].
 
+Alternatively, they can also be [reserved symbols]({{rootUrl}}/appendix/operators.md#symbols),
+[disabled operators or keywords][disable keywords and operators].
+
 ```rust
 engine.register_custom_operator("foo", 20);     // 'foo' is a valid custom operator
 
-engine.register_custom_operator("=>", 30);      // <- error: '=>' is not a valid custom operator
+engine.register_custom_operator("#", 20);       // the reserved symbol '#' is also
+                                                // a valid custom operator
+
+engine.register_custom_operator("+", 30);       // <- error: '+' is an active operator
+
+engine.register_custom_operator("=>", 30);      // <- error: '=>' is an active symbol
 ```
 
 

doc/src/rust/modules/ast.md

@@ -7,22 +7,24 @@ Create a Module from an AST
 `Module::eval_ast_as_new`
 ------------------------
 
-A _module_ can be created from a single script (or pre-compiled [`AST`]) containing global variables,
+A [module] can be created from a single script (or pre-compiled [`AST`]) containing global variables,
 functions and sub-modules via the `Module::eval_ast_as_new` method.
 
-See the section on [_Exporting Variables, Functions and Sub-Modules_][`export`] for details on how to prepare
-a Rhai script for this purpose as well as to control which functions/variables to export.
+See the section on [_Exporting Variables, Functions and Sub-Modules_][`export`] for details on how to
+prepare a Rhai script for this purpose as well as to control which functions/variables to export.
 
-When given an [`AST`], it is first evaluated, then the following items are exposed as members of the new module:
+When given an [`AST`], it is first evaluated, then the following items are exposed as members of the
+new [module]:
 
 * Global variables - all variables exported via the `export` statement (those not exported remain hidden).
 
 * Functions not specifically marked `private`.
 
-* Global modules that remain in the [`Scope`] at the end of a script run.
+* Global modules that remain in the [`Scope`] at the end of a script run (become sub-modules).
 
-`Module::eval_ast_as_new` encapsulates the entire `AST` into each function call, merging the module namespace
-with the global namespace.  Therefore, functions defined within the same module script can cross-call each other.
+`Module::eval_ast_as_new` encapsulates the entire `AST` into each function call, merging the
+module namespace with the global namespace.  Therefore, functions defined within the same module
+script can cross-call each other.
 
 
 Examples

doc/src/rust/override.md

@@ -3,18 +3,19 @@ Override a Built-in Function
 
 {{#include ../links.md}}
 
-Any similarly-named function defined in a script overrides any built-in or registered
+Any similarly-named function defined in a script _overrides_ any built-in or registered
 native Rust function of the same name and number of parameters.
 
 ```rust
-// Override the built-in function 'to_int'
-fn to_int(num) {
-    print("Ha! Gotcha! " + num);
+// Override the built-in function 'to_float' when called as a method
+fn to_float() {
+    print("Ha! Gotcha! " + this);
+    42.0
 }
 
-let x = (123).to_int();
+let x = 123.to_float();
 
-print(x);               // what happens?
+print(x);       // what happens?
 ```
 
 A registered native Rust function, in turn, overrides any built-in function of the

doc/src/tools/index.md

@@ -0,0 +1,6 @@
+External Tools
+==============
+
+{{#include ../links.md}}
+
+External tools available to work with Rhai.

doc/src/tools/playground.md

@@ -0,0 +1,15 @@
+Online Playground
+=================
+
+{{#include ../links.md}}
+
+
+The Online Playground runs off a [WASM] build of Rhai and allows evaluating
+Rhai scripts directly within a browser editor window.
+
+
+Author : [`@alvinhochun`](https://github.com/alvinhochun)
+
+Repo : [On GitHub](https://github.com/alvinhochun/rhai-playground)
+
+URL : [Link to Online Playground][playground]

doc/src/tools/rhai-doc.md

@@ -0,0 +1,6 @@
+Rhai Script Documentation Tool
+=============================
+
+{{#include ../links.md}}
+
+<< TODO >>