Refine docs.

doc/src/SUMMARY.md

@@ -128,18 +128,21 @@ The Rhai Scripting Language
    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)
+   1. [Capture Scope for Function Call](language/fn-capture.md)
-   11. [Low-Level API](rust/register-raw.md)
+   2. [Low-Level API](rust/register-raw.md)
-   12. [Variable Resolver](engine/var.md)
+   3. [Variable Resolver](engine/var.md)
-   13. [Use as DSL](engine/dsl.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)
+   5. [Multiple Instantiation](patterns/multiple.md)
-   15. [Functions Metadata](engine/metadata/index.md)
+   6. [Functions Metadata](engine/metadata/index.md)
-      4. [Generate Function Signatures](engine/metadata/gen_fn_sig.md)
+      1. [Generate Function Signatures](engine/metadata/gen_fn_sig.md)
-      5. [Export Metadata to JSON](engine/metadata/export_to_json.md)
+      2. [Export Metadata to JSON](engine/metadata/export_to_json.md)
-10. [Appendix](appendix/index.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
+See the section on [_Exporting Variables, Functions and Sub-Modules_][`export`] for details on how to
-a Rhai script for this purpose as well as to control which functions/variables to export.
+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
+`Module::eval_ast_as_new` encapsulates the entire `AST` into each function call, merging the
-with the global namespace.  Therefore, functions defined within the same module script can cross-call each other.
+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,16 +3,17 @@ 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'
+// Override the built-in function 'to_float' when called as a method
-fn to_int(num) {
+fn to_float() {
-    print("Ha! Gotcha! " + num);
+    print("Ha! Gotcha! " + this);
+    42.0
 }
 
-let x = (123).to_int();
+let x = 123.to_float();
 
 print(x);       // what happens?
 ```

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

examples/arrays_and_structs.rs

@@ -1,4 +1,4 @@
-use rhai::{Engine, RegisterFn, INT};
+use rhai::{Engine, EvalAltResult, RegisterFn, INT};
 
 #[derive(Debug, Clone)]
 struct TestStruct {

examples/rhai-repl.rs

@@ -43,7 +43,7 @@ fn print_help() {
     println!("quit, exit => quit");
     println!("scope      => print all variables in the scope");
     println!("functions  => print all functions defined");
-    println!("ast        => print the last AST");
+    println!("ast        => print the last AST (optimized)");
     println!("astu       => print the last raw, un-optimized AST");
     println!(r"end a line with '\' to continue to the next line.");
     println!();

src/ast.rs

@@ -736,7 +736,7 @@ impl Stmt {
             _ => false,
         }
     }
-    /// Get the [position][`Position`] of this statement.
+    /// Get the [position][Position] of this statement.
     pub fn position(&self) -> Position {
         match self {
             Self::Noop(pos)
@@ -765,7 +765,7 @@ impl Stmt {
             Self::Share(x) => x.pos,
         }
     }
-    /// Override the [position][`Position`] of this statement.
+    /// Override the [position][Position] of this statement.
     pub fn set_position(&mut self, new_pos: Position) -> &mut Self {
         match self {
             Self::Noop(pos)
@@ -973,7 +973,7 @@ pub enum Expr {
     Property(Box<(ImmutableString, ImmutableString, Ident)>),
     /// { [statement][Stmt] }
     Stmt(Box<StaticVec<Stmt>>, Position),
-    /// Wrapped [expression][`Expr`] - should not be optimized away.
+    /// Wrapped [expression][Expr] - should not be optimized away.
     Expr(Box<Expr>),
     /// func `(` expr `,` ... `)`
     FnCall(Box<FnCallExpr>, Position),
@@ -1052,7 +1052,7 @@ impl Expr {
             _ => None,
         }
     }
-    /// Get the [position][`Position`] of the expression.
+    /// Get the [position][Position] of the expression.
     pub fn position(&self) -> Position {
         match self {
             Self::Expr(x) => x.position(),
@@ -1082,7 +1082,7 @@ impl Expr {
             Self::Custom(_, pos) => *pos,
         }
     }
-    /// Override the [position][`Position`] of the expression.
+    /// Override the [position][Position] of the expression.
     pub fn set_position(&mut self, new_pos: Position) -> &mut Self {
         match self {
             Self::Expr(x) => {

src/engine.rs

@@ -19,8 +19,7 @@ use crate::stdlib::{
     fmt, format,
     hash::{Hash, Hasher},
     iter::{empty, once, FromIterator},
-    num::NonZeroU64,
+    num::{NonZeroU64, NonZeroU8, NonZeroUsize},
-    num::NonZeroUsize,
     ops::DerefMut,
     string::{String, ToString},
 };
@@ -637,7 +636,7 @@ pub struct Engine {
     /// A hashset containing symbols to disable.
     pub(crate) disabled_symbols: HashSet<String>,
     /// A hashmap containing custom keywords and precedence to recognize.
-    pub(crate) custom_keywords: HashMap<String, Option<u8>>,
+    pub(crate) custom_keywords: HashMap<String, Option<NonZeroU8>>,
     /// Custom syntax.
     pub(crate) custom_syntax: HashMap<ImmutableString, CustomSyntax>,
     /// Callback closure for resolving variable access.
@@ -989,7 +988,7 @@ impl Engine {
         new_val: Option<(Dynamic, Position)>,
     ) -> Result<(Dynamic, bool), Box<EvalAltResult>> {
         if chain_type == ChainType::None {
-            panic!();
+            unreachable!();
         }
 
         let is_ref = target.is_ref();

src/engine_api.rs

@@ -723,21 +723,22 @@ impl Engine {
         self.register_indexer_get(getter)
             .register_indexer_set(setter)
     }
-    /// Register a shared [`Module`][crate::Module] into the global namespace of [`Engine`].
+    /// Register a shared [`Module`] into the global namespace of [`Engine`].
     ///
-    /// All functions and type iterators are automatically available to scripts without namespace qualifications.
+    /// All functions and type iterators are automatically available to scripts without namespace
+    /// qualifications.
     ///
     /// Sub-modules and variables are **ignored**.
     ///
-    /// When searching for functions, modules loaded later are preferred.
+    /// When searching for functions, modules loaded later are preferred. In other words, loaded
-    /// In other words, loaded modules are searched in reverse order.
+    /// modules are searched in reverse order.
     #[inline(always)]
     pub fn register_global_module(&mut self, module: Shared<Module>) -> &mut Self {
         // Insert the module into the front
         self.global_modules.insert(0, module);
         self
     }
-    /// Register a shared [`Module`][crate::Module] into the global namespace of [`Engine`].
+    /// Register a shared [`Module`] into the global namespace of [`Engine`].
     ///
     /// ## Deprecated
     ///
@@ -747,9 +748,11 @@ impl Engine {
     pub fn load_package(&mut self, module: impl Into<Shared<Module>>) -> &mut Self {
         self.register_global_module(module.into())
     }
-    /// Register a shared [`Module`][crate::Module] as a static module namespace with the [`Engine`].
+    /// Register a shared [`Module`] as a static module namespace with the
+    /// [`Engine`].
     ///
-    /// Functions marked `FnNamespace::Global` and type iterators are exposed to scripts without namespace qualifications.
+    /// Functions marked [`FnNamespace::Global`] and type iterators are exposed to scripts without
+    /// namespace qualifications.
     ///
     /// # Example
     ///
@@ -825,7 +828,7 @@ impl Engine {
         self
     }
 
-    /// Register a shared [`Module`][crate::Module] as a static module namespace with the [`Engine`].
+    /// Register a shared [`Module`] as a static module namespace with the [`Engine`].
     ///
     /// ## Deprecated
     ///
@@ -1719,7 +1722,7 @@ impl Engine {
     /// With this method, it is no longer necessary to recompile a large script.
     /// The script [`AST`] can be compiled just once. Before evaluation,
     /// constants are passed into the [`Engine`] via an external scope
-    /// (i.e. with [`scope.push_constant(...)`][crate::Scope::push_constant]).
+    /// (i.e. with [`Scope::push_constant`]).
     /// Then, the [`AST`] is cloned and the copy re-optimized before running.
     #[cfg(not(feature = "no_optimize"))]
     #[inline]

src/module/mod.rs

@@ -356,7 +356,7 @@ impl Module {
         self.get_var(name).and_then(Dynamic::try_cast::<T>)
     }
 
-    /// Get a module variable as a [`Dynamic`][crate::Dynamic].
+    /// Get a module variable as a [`Dynamic`].
     ///
     /// # Example
     ///
@@ -466,10 +466,18 @@ impl Module {
     }
 
     /// Get a mutable reference to the underlying [`HashMap`] of sub-modules.
+    ///
+    /// ## Warning
+    ///
+    /// By taking a mutable reference, it is assumed that some sub-modules will be modified.
+    /// Thus the module is automatically set to be non-indexed.
     #[inline(always)]
     pub(crate) fn sub_modules_mut(&mut self) -> &mut HashMap<ImmutableString, Shared<Module>> {
         // We must assume that the user has changed the sub-modules
         // (otherwise why take a mutable reference?)
+        self.all_functions.clear();
+        self.all_variables.clear();
+        self.all_type_iterators.clear();
         self.indexed = false;
 
         &mut self.modules
@@ -652,7 +660,7 @@ impl Module {
     }
 
     /// Set a Rust function taking a reference to the scripting [`Engine`][crate::Engine],
-    /// the current set of functions, plus a list of mutable [`Dynamic`][crate::Dynamic] references
+    /// the current set of functions, plus a list of mutable [`Dynamic`] references
     /// into the module, returning a hash key.
     ///
     /// Use this to register a built-in function which must reference settings on the scripting
@@ -667,7 +675,7 @@ impl Module {
     ///
     /// A list of [`TypeId`]'s is taken as the argument types.
     ///
-    /// Arguments are simply passed in as a mutable array of [`&mut Dynamic`][crate::Dynamic],
+    /// Arguments are simply passed in as a mutable array of [`&mut Dynamic`],
     /// which is guaranteed to contain enough arguments of the correct types.
     ///
     /// The function is assumed to be a _method_, meaning that the first argument should not be consumed.

src/optimize.rs

@@ -152,7 +152,7 @@ fn call_fn_with_constant_arguments(
         .map(|(v, _)| v)
 }
 
-/// Optimize a block of [statements][crate::ast::Stmt].
+/// Optimize a block of [statements][Stmt].
 fn optimize_stmt_block(
     mut statements: Vec<Stmt>,
     pos: Position,
@@ -277,7 +277,7 @@ fn optimize_stmt_block(
     }
 }
 
-/// Optimize a [statement][crate::ast::Stmt].
+/// Optimize a [statement][Stmt].
 fn optimize_stmt(stmt: &mut Stmt, state: &mut State, preserve_result: bool) {
     match stmt {
         // expr op= expr
@@ -473,7 +473,7 @@ fn optimize_stmt(stmt: &mut Stmt, state: &mut State, preserve_result: bool) {
     }
 }
 
-/// Optimize an [expression][crate::ast::Expr].
+/// Optimize an [expression][Expr].
 fn optimize_expr(expr: &mut Expr, state: &mut State) {
     // These keywords are handled specially
     const DONT_EVAL_KEYWORDS: &[&str] = &[
@@ -737,7 +737,7 @@ fn optimize_expr(expr: &mut Expr, state: &mut State) {
     }
 }
 
-/// Optimize a block of [statements][crate::ast::Stmt] at top level.
+/// Optimize a block of [statements][Stmt] at top level.
 fn optimize_top_level(
     mut statements: Vec<Stmt>,
     engine: &Engine,