From 2d734687232973126a1200eeeaea81295d684324 Mon Sep 17 00:00:00 2001
From: Stephen Chung <Stephen.Chung@intexact.com>
Date: Mon, 23 Nov 2020 20:27:20 +0800
Subject: [PATCH] Add doc on Engine::gen_fn_signatures.

---
 doc/src/SUMMARY.md           |  1 +
 doc/src/engine/get_fn_sig.md | 87 ++++++++++++++++++++++++++++++++++++
 src/engine_api.rs            |  4 +-
 3 files changed, 90 insertions(+), 2 deletions(-)
 create mode 100644 doc/src/engine/get_fn_sig.md

diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md
index e6a4da84..891b760f 100644
--- a/doc/src/SUMMARY.md
+++ b/doc/src/SUMMARY.md
@@ -135,6 +135,7 @@ The Rhai Scripting Language
       2. [Custom Operators](engine/custom-op.md)
       3. [Extending with Custom Syntax](engine/custom-syntax.md)
    5. [Multiple Instantiation](patterns/multiple.md)
+   6. [Get Function Signatures](engine/get_fn_sig.md)
 10. [Appendix](appendix/index.md)
     1. [Keywords](appendix/keywords.md)
     2. [Operators and Symbols](appendix/operators.md)
diff --git a/doc/src/engine/get_fn_sig.md b/doc/src/engine/get_fn_sig.md
new file mode 100644
index 00000000..69894633
--- /dev/null
+++ b/doc/src/engine/get_fn_sig.md
@@ -0,0 +1,87 @@
+Get Function Signatures
+=======================
+
+{{#include ../links.md}}
+
+
+`Engine::gen_fn_signatures`
+--------------------------
+
+As part of a _reflections_ API, `Engine::gen_fn_signatures` returns a list of function signatures
+(`Vec<String>`), each corresponding to a particular function available to that [`Engine`] instance.
+
+Functions from the following sources are included, in order:
+
+1) Functions registered into the global namespace via the `Engine::register_XXX` API,
+2) Functions in global sub-modules registered via [`Engine::register_module`]({{rootUrl}}/rust/modules/create.md),
+3) Functions in registered [packages] (optional)
+
+Included are both native Rust as well as script-defined functions (except [`private`] ones).
+
+
+Function Metadata
+-----------------
+
+Beware, however, that not all function signatures contain parameters and return value information.
+
+### `Engine::register_XXX`
+
+For instance, functions registered via `Engine::register_XXX` contain no information on
+the names of parameter and their actual types because Rust simply does not make such metadata
+available natively. The return type is also undetermined.
+
+A function registered under the name 'foo' with three parameters and unknown return type:
+
+> `foo(_, _, _)`
+
+An operator function - again, unknown parameters and return type.
+Notice that function names do not need to be valid identifiers.
+
+> `+(_, _)`
+
+A [property setter][getters/setters] - again, unknown parameters and return type.
+Notice that function names do not need to be valid identifiers.
+In this case, the first parameter should be '&mut T' of the custom type and the return value is '()':
+
+> `set$prop(_, _, _)`
+
+### Script-defined functions
+
+Script-defined [function] signatures contain parameter names. Since all parameters, as well as
+the return value, are [`Dynamic`] the types are simply not shown.
+
+A script-defined function always takes dynamic arguments, and the return type is also dynamic:
+
+> `foo(x, y, z)`
+
+probably defined as:
+
+```rust
+fn foo(x, y, z) {
+    ...
+}
+```
+
+is the same as:
+
+> `foo(x: Dynamic, y: Dynamic, z: Dynamic) -> Result<Dynamic, Box<EvalAltResult>>`
+
+### Plugin functions
+
+Functions defined in [plugin modules] are the best.  They contain all the metadata
+describing the functions.
+
+A plugin function `merge`:
+
+> `merge(list: &mut MyStruct<i64>, num: usize, name: &str) -> Option<bool>`
+
+Notice that function names do not need to be valid identifiers.
+
+An operator defined as a [fallible function] in a [plugin module] via `#[rhai_fn(name="+=", return_raw)]`
+returns `Result<bool, Box<EvalAltResult>>`:
+
+> `+=(list: &mut MyStruct<i64>, num: usize, name: &str) -> Result<bool, Box<EvalAltResult>>`
+
+A [property getter][getters/setters] defined in a [plugin module]:
+
+> `get$prop(obj: &mut MyStruct<i64>) -> String`
diff --git a/src/engine_api.rs b/src/engine_api.rs
index b801a33c..b3227c58 100644
--- a/src/engine_api.rs
+++ b/src/engine_api.rs
@@ -1650,10 +1650,10 @@ impl Engine {
     }
     /// Generate a list of all registered functions.
     ///
-    /// The ordering is:
+    /// Functions from the following sources are included, in order:
     /// 1) Functions registered into the global namespace
     /// 2) Functions in registered sub-modules
-    /// 3) Functions in packages
+    /// 3) Functions in packages (optional)
     pub fn gen_fn_signatures(&self, include_packages: bool) -> Vec<String> {
         let mut signatures: Vec<_> = Default::default();