From 65a1c24d7b129e440b9bdd530bbd41a463c7c0cc Mon Sep 17 00:00:00 2001
From: Stephen Chung <schungx@live.com>
Date: Sat, 25 Sep 2021 15:57:38 +0800
Subject: [PATCH] Add signatures to callback function docs.

---
 src/custom_syntax.rs | 18 +++++++++++++
 src/engine_api.rs    | 62 +++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 76 insertions(+), 4 deletions(-)

diff --git a/src/custom_syntax.rs b/src/custom_syntax.rs
index eaee3c27..7f98ae18 100644
--- a/src/custom_syntax.rs
+++ b/src/custom_syntax.rs
@@ -316,6 +316,24 @@ impl Engine {
     ///
     /// All custom keywords used as symbols must be manually registered via [`Engine::register_custom_operator`].
     /// Otherwise, they won't be recognized.
+    ///
+    /// # Implementation Function Signature
+    ///
+    /// The implementation function has the following signature:
+    ///
+    /// > `Fn(symbols: &[ImmutableString], look_ahead: &str) -> Result<Option<ImmutableString>, ParseError>`
+    ///
+    /// where:
+    /// * `symbols`: a slice of symbols that have been parsed so far, possibly containing `$expr$` and/or `$block$`;
+    ///   `$ident$` and other literal markers are replaced by the actual text
+    /// * `look_ahead`: a string slice containing the next symbol that is about to be read
+    ///
+    /// ## Return value
+    ///
+    /// * `Ok(None)`: parsing complete and there are no more symbols to match.
+    /// * `Ok(Some(symbol))`: the next symbol to match, which can also be `$expr$`, `$ident$` or `$block$`.
+    /// * `Err(ParseError)`: error that is reflected back to the [`Engine`], normally `ParseError(ParseErrorType::BadInput(LexError::ImproperSymbol(message)), Position::NONE)` to indicate a syntax error, but it can be any [`ParseError`].
+    ///
     pub fn register_custom_syntax_raw(
         &mut self,
         key: impl Into<Identifier>,
diff --git a/src/engine_api.rs b/src/engine_api.rs
index 0abcaa89..8ba01d01 100644
--- a/src/engine_api.rs
+++ b/src/engine_api.rs
@@ -2080,12 +2080,28 @@ impl Engine {
     }
     /// Provide a callback that will be invoked before each variable access.
     ///
-    /// # Return Value of Callback
+    /// # Callback Function Signature
     ///
-    /// Return `Ok(None)` to continue with normal variable access.  
-    /// Return `Ok(Some(Dynamic))` as the variable's value.
+    /// The callback function signature takes the following form:
     ///
-    /// # Errors in Callback
+    /// > `Fn(name: &str, index: usize, context: &EvalContext)`  
+    /// > `   -> Result<Option<Dynamic>, Box<EvalAltResult>> + 'static`
+    ///
+    /// where:
+    /// * `index`: an offset from the bottom of the current [`Scope`] that the variable is supposed
+    ///   to reside. Offsets start from 1, with 1 meaning the last variable in the current
+    ///   [`Scope`].  Essentially the correct variable is at position `scope.len() - index`.
+    ///   If `index` is zero, then there is no pre-calculated offset position and a search through the
+    ///   current [`Scope`] must be performed.
+    ///
+    /// * `context`: the current [evaluation context][`EvalContext`].
+    ///
+    /// ## Return value
+    ///
+    /// * `Ok(None)`: continue with normal variable access.
+    /// * `Ok(Some(Dynamic))`: the variable's value.
+    ///
+    /// ## Raising errors
     ///
     /// Return `Err(...)` if there is an error.
     ///
@@ -2123,6 +2139,22 @@ impl Engine {
     /// _(internals)_ Provide a callback that will be invoked during parsing to remap certain tokens.
     /// Exported under the `internals` feature only.
     ///
+    /// # Callback Function Signature
+    ///
+    /// The callback function signature takes the following form:
+    ///
+    /// > `Fn(token: Token, pos: Position, state: &TokenizeState) -> Token`
+    ///
+    /// where:
+    /// * [`token`][crate::token::Token]: current token parsed
+    /// * [`pos`][`Position`]: location of the token
+    /// * [`state`][crate::token::TokenizeState]: current state of the tokenizer
+    ///
+    /// ## Raising errors
+    ///
+    /// It is possible to raise a parsing error by returning
+    /// [`Token::LexError`][crate::token::Token::LexError] as the mapped token.
+    ///
     /// # Example
     ///
     /// ```
@@ -2168,6 +2200,17 @@ impl Engine {
     ///
     /// Not available under `unchecked`.
     ///
+    /// # Callback Function Signature
+    ///
+    /// The callback function signature takes the following form:
+    ///
+    /// > `Fn(counter: u64) -> Option<Dynamic>`
+    ///
+    /// ## Return value
+    ///
+    /// * `None`: continue running the script.
+    /// * `Some(Dynamic)`: terminate the script with the specified exception value.
+    ///
     /// # Example
     ///
     /// ```
@@ -2240,6 +2283,17 @@ impl Engine {
     }
     /// Override default action of `debug` (print to stdout using [`println!`])
     ///
+    /// # Callback Function Signature
+    ///
+    /// The callback function signature passed takes the following form:
+    ///
+    /// > `Fn(text: &str, source: Option<&str>, pos: Position)`
+    ///
+    /// where:
+    /// * `text`: the text to display
+    /// * `source`: current source, if any
+    /// * [`pos`][`Position`]: location of the `debug` call
+    ///
     /// # Example
     ///
     /// ```