Move script optimization into separate section.

doc/src/SUMMARY.md

@@ -45,7 +45,12 @@ The Rhai Scripting Language
       1. [Built-in Packages](rust/packages/builtin.md)
       2. [Load a Plugin Module as a Package](rust/packages/plugin.md)
       3. [Manually Create a Custom Package](rust/packages/create.md)
-   10. [Plugins](plugins/index.md)
+   10. [Modules](rust/modules/index.md)
+       1. [Create from Rust](rust/modules/create.md)
+       2. [Create from AST](rust/modules/ast.md)
+       3. [Module Resolvers](rust/modules/resolvers.md)
+          1. [Custom Implementation](rust/modules/imp-resolver.md)
+   11. [Plugins](plugins/index.md)
        1. [Export a Rust Module](plugins/module.md)
        2. [Export a Rust Function](plugins/function.md)
 5. [Rhai Language Reference](language/index.md)
@@ -89,10 +94,6 @@ The Rhai Scripting Language
    17. [Modules](language/modules/index.md)
        1. [Export Variables, Functions and Sub-Modules](language/modules/export.md)
        2. [Import Modules](language/modules/import.md)
-       3. [Create from Rust](rust/modules/create.md)
-       4. [Create from AST](rust/modules/ast.md)
-       5. [Module Resolvers](rust/modules/resolvers.md)
-          1. [Custom Implementation](rust/modules/imp-resolver.md)
    18. [Eval Statement](language/eval.md)
 6. [Safety and Protection](safety/index.md)
    1. [Checked Arithmetic](safety/checked.md)
@@ -105,29 +106,29 @@ The Rhai Scripting Language
    7. [Maximum Number of Modules](safety/max-modules.md)
    8. [Maximum Call Stack Depth](safety/max-call-stack.md)
    9. [Maximum Statement Depth](safety/max-stmt-depth.md)
-7. [Usage Patterns](patterns/index.md)
+7. [Script Optimization](engine/optimize/index.md)
+   1. [Optimization Levels](engine/optimize/optimize-levels.md)
+   2. [Re-Optimize an AST](engine/optimize/reoptimize.md)
+   3. [Eager Function Evaluation](engine/optimize/eager.md)
+   4. [Side-Effect Considerations](engine/optimize/side-effects.md)
+   5. [Volatility Considerations](engine/optimize/volatility.md)
+   6. [Subtle Semantic Changes](engine/optimize/semantics.md)
+8. [Usage Patterns](patterns/index.md)
    1. [Object-Oriented Programming (OOP)](patterns/oop.md)
    2. [Loadable Configuration](patterns/config.md)
    3. [Control Layer](patterns/control.md)
    4. [Singleton Command](patterns/singleton.md)
    5. [One Engine Instance Per Call](patterns/parallel.md)
    6. [Scriptable Event Handler with State](patterns/events.md)
-8. [Advanced Topics](advanced.md)
+9. [Advanced Topics](advanced.md)
    1. [Capture Scope for Function Call](language/fn-capture.md)
-   2. [Script Optimization](engine/optimize/index.md)
+   2. [Low-Level API](rust/register-raw.md)
-      1. [Optimization Levels](engine/optimize/optimize-levels.md)
+   3. [Use as DSL](engine/dsl.md)
-      2. [Re-Optimize an AST](engine/optimize/reoptimize.md)
-      3. [Eager Function Evaluation](engine/optimize/eager.md)
-      4. [Side-Effect Considerations](engine/optimize/side-effects.md)
-      5. [Volatility Considerations](engine/optimize/volatility.md)
-      6. [Subtle Semantic Changes](engine/optimize/semantics.md)
-   3. [Low-Level API](rust/register-raw.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)
-   5. [Multiple Instantiation](patterns/multiple.md)
+   4. [Multiple Instantiation](patterns/multiple.md)
-9. [Appendix](appendix/index.md)
+10. [Appendix](appendix/index.md)
-   1. [Keywords](appendix/keywords.md)
+    1. [Keywords](appendix/keywords.md)
-   2. [Operators and Symbols](appendix/operators.md)
+    2. [Operators and Symbols](appendix/operators.md)
-   3. [Literals](appendix/literals.md)
+    3. [Literals](appendix/literals.md)

doc/src/advanced.md

@@ -11,8 +11,6 @@ This section covers advanced features such as:
 
 * [`serde`] integration.
 
-* [Script optimization].
-
 * Low-level [function registration API]({{rootUrl}}/rust/register-raw.md)
 
 * [Domain-Specific Languages][DSL].

doc/src/language/modules/export.md

@@ -4,6 +4,16 @@ Export Variables, Functions and Sub-Modules in Module
 {{#include ../../links.md}}
 
 
+The easiest way to expose a package of functions as a self-contained [module] is to do it via a Rhai script itself.
+
+See the section on [_Creating a Module from AST_]({{rootUrl}}/rust/modules/ast.md) for more details.
+
+The script text is evaluated, variables are then selectively exposed via the [`export`] statement.
+Functions defined by the script are automatically exported.
+
+Modules loaded within this module at the global level become _sub-modules_ and are also automatically exported.
+
+
 Export Global Variables
 ----------------------
 

doc/src/language/modules/import.md

@@ -4,6 +4,12 @@ Import a Module
 {{#include ../../links.md}}
 
 
+Before a module can be used (via an `import` statement) in a script, there must be a [module resolver]
+registered into the [`Engine`], the default being the `FileModuleResolver`.
+
+See the section on [_Module Resolvers_][module resolver] for more details.
+
+
 `import` Statement
 -----------------
 

doc/src/language/modules/index.md

@@ -6,13 +6,9 @@ Modules
 Rhai allows organizing code (functions, both Rust-based or script-based, and variables) into _modules_.
 Modules can be disabled via the [`no_module`] feature.
 
-A module is of the type `Module` and encapsulates a Rhai script together with the functions defined
+A module is of the type `Module` and holds a collection of functions, variables, iterators and sub-modules.
-by that script.
+It may be created entirely from Rust functions, or it may encapsulate a Rhai script together with the functions
+and variables defined by that script.
 
-The script text is run, variables are then selectively exposed via the [`export`] statement.
+Other scripts can then load this module and use the functions and variables exported
-Functions defined by the script are automatically exported.
-
-Modules loaded within this module at the global level become _sub-modules_ and are also automatically exported.
-
-Other scripts can then load this module and use the variables and functions exported
 as if they were defined inside the same script.

doc/src/links.md

@@ -102,9 +102,9 @@
 [anonymous functions]: {{rootUrl}}/language/fn-anon.md
 [operator overloading]: {{rootUrl}}/rust/operators.md
 
-[`Module`]: {{rootUrl}}/language/modules/index.md
+[`Module`]: {{rootUrl}}/rust/modules/index.md
-[module]: {{rootUrl}}/language/modules/index.md
+[module]: {{rootUrl}}/rust/modules/index.md
-[modules]: {{rootUrl}}/language/modules/index.md
+[modules]: {{rootUrl}}/rust/modules/index.md
 [module resolver]: {{rootUrl}}/rust/modules/resolvers.md
 [`export`]: {{rootUrl}}/language/modules/export.md
 [`import`]: {{rootUrl}}/language/modules/import.md

doc/src/rust/modules/ast.md

@@ -10,9 +10,12 @@ Create a Module from an AST
 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.
+
 When given an [`AST`], it is first evaluated, then the following items are exposed as members of the new module:
 
-* Global variables - essentially all variables that remain in the [`Scope`] at the end of a script run - that are exported. Variables not exported (via the `export` statement) remain hidden.
+* Global variables - all variables exported via the `export` statement (those not exported remain hidden).
 
 * Functions not specifically marked `private`.
 

doc/src/rust/modules/index.md

@@ -0,0 +1,14 @@
+Modules
+=======
+
+{{#include ../../links.md}}
+
+Rhai allows organizing code (functions, both Rust-based or script-based, and variables) into _modules_.
+Modules can be disabled via the [`no_module`] feature.
+
+A module is of the type `Module` and holds a collection of functions, variables, iterators and sub-modules.
+It may be created entirely from Rust functions, or it may encapsulate a Rhai script together with the functions
+and variables defined by that script.
+
+Other scripts can then load this module and use the functions and variables exported
+as if they were defined inside the same script.

doc/src/rust/modules/resolvers.md

@@ -5,6 +5,8 @@ Module Resolvers
 
 When encountering an [`import`] statement, Rhai attempts to _resolve_ the module based on the path string.
 
+See the section on [_Importing Modules_][`import`] for more details.
+
 _Module Resolvers_ are service types that implement the [`ModuleResolver`][traits] trait.