Update docs regarding modules.

doc/src/rust/modules/imp-resolver.md

@@ -0,0 +1,56 @@
+Implement a Custom Module Resolver
+=================================
+
+{{#include ../../links.md}}
+
+For many applications in which Rhai is embedded, it is necessary to customize the way that modules
+are resolved.  For instance, modules may need to be loaded from script texts stored in a database,
+not in the file system.
+
+A module resolver must implement the trait [`rhai::ModuleResolver`][traits],
+which contains only one function: `resolve`.
+
+When Rhai prepares to load a module, `ModuleResolver::resolve` is called with the name
+of the _module path_ (i.e. the path specified in the [`import`] statement). Upon success, it should
+return a [`Module`]; if the module cannot be load, return `EvalAltResult::ErrorModuleNotFound`.
+
+Example
+-------
+
+```rust
+use rhai::{ModuleResolver, Module, Engine, EvalAltResult};
+
+// Define a custom module resolver.
+struct MyModuleResolver {}
+
+// Implement the 'ModuleResolver' trait.
+impl ModuleResolver for MyModuleResolver {
+    // Only required function.
+    fn resolve(
+        &self,
+        engine: &Engine,    // reference to the current 'Engine'
+        path: &str,         // the module path
+        pos: Position,      // location of the 'import' statement
+    ) -> Result<Module, Box<EvalAltResult>> {
+        // Check module path.
+        if is_valid_module_path(path) {
+            // Load the custom module.
+            let module: Module = load_secret_module(path);
+            Ok(module)
+        } else {
+            Err(Box::new(EvalAltResult::ErrorModuleNotFound(path.into(), pos)))
+        }
+    }
+}
+
+let mut engine = Engine::new();
+
+// Set the custom module resolver into the 'Engine'.
+engine.set_module_resolver(Some(MyModuleResolver {}));
+
+engine.consume(r#"
+    import "hello" as foo;  // this 'import' statement will call
+                            // 'MyModuleResolver::resolve' with "hello" as path
+    foo:bar();
+"#)?;
+```

doc/src/rust/modules/index.md

@@ -0,0 +1,45 @@
+Create a Module from Rust
+========================
+
+{{#include ../../links.md}}
+
+Manually creating a [`Module`] is possible via the `Module` API.
+
+For the complete `Module` API, refer to the [documentation](https://docs.rs/rhai/{{version}}/rhai/struct.Module.html) online.
+
+
+Make the Module Available to the Engine
+--------------------------------------
+
+In order to _use_ a custom module, there must be a [module resolver].
+
+The easiest way is to use, for example, the [`StaticModuleResolver`][module resolver] to hold such
+a custom module.
+
+```rust
+use rhai::{Engine, Scope, Module, i64};
+use rhai::module_resolvers::StaticModuleResolver;
+
+let mut engine = Engine::new();
+let mut scope = Scope::new();
+
+let mut module = Module::new();             // new module
+module.set_var("answer", 41_i64);           // variable 'answer' under module
+module.set_fn_1("inc", |x: i64| Ok(x+1));   // use the 'set_fn_XXX' API to add functions
+
+// Create the module resolver
+let mut resolver = StaticModuleResolver::new();
+
+// Add the module into the module resolver under the name 'question'
+// They module can then be accessed via: 'import "question" as q;'
+resolver.insert("question", module);
+
+// Set the module resolver into the 'Engine'
+engine.set_module_resolver(Some(resolver));
+
+// Use module-qualified variables
+engine.eval::<i64>(&scope, r#"import "question" as q; q::answer + 1"#)? == 42;
+
+// Call module-qualified functions
+engine.eval::<i64>(&scope, r#"import "question" as q; q::inc(q::answer)"#)? == 42;
+```

doc/src/rust/modules/resolvers.md

@@ -0,0 +1,38 @@
+Module Resolvers
+================
+
+{{#include ../../links.md}}
+
+When encountering an [`import`] statement, Rhai attempts to _resolve_ the module based on the path string.
+
+_Module Resolvers_ are service types that implement the [`ModuleResolver`][traits] trait.
+
+
+Built-In Module Resolvers
+------------------------
+
+There are a number of standard resolvers built into Rhai, the default being the `FileModuleResolver`
+which simply loads a script file based on the path (with `.rhai` extension attached) and execute it to form a module.
+
+Built-in module resolvers are grouped under the `rhai::module_resolvers` module namespace.
+
+| Module Resolver             | Description                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FileModuleResolver`        | The default module resolution service, not available under [`no_std`] or [WASM] builds. Loads a script file (based off the current directory) with `.rhai` extension.<br/>The base directory can be changed via the `FileModuleResolver::new_with_path()` constructor function.<br/>`FileModuleResolver::create_module()` loads a script file and returns a module. |
+| `StaticModuleResolver`      | Loads modules that are statically added. This can be used under [`no_std`].                                                                                                                                                                                                                                                                                         |
+| `ModuleResolversCollection` | A collection of module resolvers. Modules will be resolved from each resolver in sequential order.<br/>This is useful when multiple types of modules are needed simultaneously.                                                                                                                                                                                     |
+
+
+Set into `Engine`
+-----------------
+
+An [`Engine`]'s module resolver is set via a call to `Engine::set_module_resolver`:
+
+```rust
+// Use the 'StaticModuleResolver'
+let resolver = rhai::module_resolvers::StaticModuleResolver::new();
+engine.set_module_resolver(Some(resolver));
+
+// Effectively disable 'import' statements by setting module resolver to 'None'
+engine.set_module_resolver(None);
+```