Improve documentation on internal types.

Cargo.toml

@@ -75,3 +75,6 @@ optional = true
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]
 instant= { version = "0.1.4", features = ["wasm-bindgen"] } # WASM implementation of std::time::Instant
+
+[package.metadata.docs.rs]
+features = [ "serde", "internals" ]

src/engine.rs

@@ -39,6 +39,11 @@ pub type Array = Vec<Dynamic>;
 pub type Map = HashMap<ImmutableString, Dynamic>;
 
 /// A stack of imported modules.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 pub type Imports<'a> = Vec<(Cow<'a, str>, Module)>;
 
 #[cfg(not(feature = "unchecked"))]
@@ -190,11 +195,16 @@ impl<T: Into<Dynamic>> From<T> for Target<'_> {
 }
 
 /// A type that holds all the current states of the Engine.
+/// Exported under the `internals` feature only.
 ///
 /// # Safety
 ///
 /// This type uses some unsafe code, mainly for avoiding cloning of local variable names via
 /// direct lifetime casting.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[derive(Debug, Clone, Eq, PartialEq, Hash, Default)]
 pub struct State {
     /// Normally, access to variables are parsed with a relative offset into the scope to avoid a lookup.

src/error.rs

@@ -10,7 +10,12 @@ use crate::stdlib::{
     string::{String, ToString},
 };
 
-/// Error when tokenizing the script text.
+/// Error encountered when tokenizing the script text.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[derive(Debug, Eq, PartialEq, Clone, Hash)]
 #[non_exhaustive]
 pub enum LexError {

src/fn_native.rs

@@ -9,7 +9,9 @@ use crate::token::{is_valid_identifier, Position};
 use crate::utils::{ImmutableString, StaticVec};
 use crate::Scope;
 
-use crate::stdlib::{boxed::Box, convert::TryFrom, fmt, mem, rc::Rc, string::String, sync::Arc};
+use crate::stdlib::{
+    boxed::Box, convert::TryFrom, fmt, mem, rc::Rc, string::String, sync::Arc, vec::Vec,
+};
 
 /// Trait that maps to `Send + Sync` only under the `sync` feature.
 #[cfg(feature = "sync")]

src/lib.rs

@@ -166,7 +166,7 @@ pub use token::{get_next_token, parse_string_literal, InputStream, Token, Tokeni
 
 #[cfg(feature = "internals")]
 #[deprecated(note = "this type is volatile and may change")]
-pub use parser::{CustomExpr, Expr, ReturnType, ScriptFnDef, Stmt};
+pub use parser::{CustomExpr, Expr, FloatWrapper, ReturnType, ScriptFnDef, Stmt};
 
 #[cfg(feature = "internals")]
 #[deprecated(note = "this type is volatile and may change")]

src/module.rs

@@ -1129,10 +1129,16 @@ impl Module {
 }
 
 /// A chain of module names to qualify a variable or function call.
-/// A `u64` hash key is kept for quick search purposes.
+/// Exported under the `internals` feature only.
+///
+/// A `u64` hash key is cached for quick search purposes.
 ///
 /// A `StaticVec` is used because most module-level access contains only one level,
 /// and it is wasteful to always allocate a `Vec` with one element.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[derive(Clone, Eq, PartialEq, Default, Hash)]
 pub struct ModuleRef(StaticVec<(String, Position)>, Option<NonZeroUsize>);
 

src/parser.rs

@@ -342,7 +342,12 @@ impl fmt::Display for FnAccess {
     }
 }
 
-/// A scripted function definition.
+/// A type containing information on a scripted function.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[derive(Debug, Clone, Hash)]
 pub struct ScriptFnDef {
     /// Function name.
@@ -376,7 +381,12 @@ impl fmt::Display for ScriptFnDef {
     }
 }
 
-/// `return`/`throw` statement.
+/// A type encapsulating the mode of a `return`/`throw` statement.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[derive(Debug, Eq, PartialEq, Clone, Copy, Hash)]
 pub enum ReturnType {
     /// `return` statement.
@@ -477,7 +487,8 @@ impl ParseSettings {
     }
 }
 
-/// A statement.
+/// A Rhai statement.
+/// Exported under the `internals` feature only.
 ///
 /// Each variant is at most one pointer in size (for speed),
 /// with everything being allocated together in one single tuple.
@@ -582,6 +593,12 @@ impl Stmt {
     }
 }
 
+/// A type wrapping a custom syntax definition.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[derive(Clone)]
 pub struct CustomExpr(pub StaticVec<Expr>, pub Shared<FnCustomSyntaxEval>);
 
@@ -592,11 +609,20 @@ impl fmt::Debug for CustomExpr {
 }
 
 impl Hash for CustomExpr {
-    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+    fn hash<H: Hasher>(&self, state: &mut H) {
         self.0.hash(state);
     }
 }
 
+/// A type wrapping a floating-point number.
+/// Exported under the `internals` feature only.
+///
+/// This type is mainly used to provide a standard `Hash` implementation
+/// to floating-point numbers, allowing `Expr` to derive `Hash` automatically.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[cfg(not(feature = "no_float"))]
 #[derive(Debug, PartialEq, PartialOrd, Clone)]
 pub struct FloatWrapper(pub FLOAT, pub Position);
@@ -609,10 +635,15 @@ impl Hash for FloatWrapper {
     }
 }
 
-/// An expression.
+/// An expression sub-tree.
+/// Exported under the `internals` feature only.
 ///
 /// Each variant is at most one pointer in size (for speed),
 /// with everything being allocated together in one single tuple.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[derive(Debug, Clone, Hash)]
 pub enum Expr {
     /// Integer constant.

src/syntax.rs

@@ -12,7 +12,8 @@ use crate::token::{is_valid_identifier, Position, Token};
 use crate::utils::StaticVec;
 
 use crate::stdlib::{
-    fmt,
+    boxed::Box,
+    fmt, format,
     rc::Rc,
     string::{String, ToString},
     sync::Arc,

src/token.rs

@@ -136,89 +136,181 @@ impl fmt::Debug for Position {
     }
 }
 
-/// Tokens.
+/// A language token.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[derive(Debug, PartialEq, Clone)]
 pub enum Token {
+    /// An `INT` constant.
     IntegerConstant(INT),
+    /// A `FLOAT` constaint.
+    ///
+    /// Never appears under the `no_float` feature.
     #[cfg(not(feature = "no_float"))]
     FloatConstant(FLOAT),
+    /// An identifier.
     Identifier(String),
+    /// A character constant.
     CharConstant(char),
+    /// A string constant.
     StringConstant(String),
+    /// `{`
     LeftBrace,
+    /// `}`
     RightBrace,
+    /// `(`
     LeftParen,
+    /// `)`
     RightParen,
+    /// `[`
     LeftBracket,
+    /// `]`
     RightBracket,
+    /// `+`
     Plus,
+    /// `+` (unary)
     UnaryPlus,
+    /// `-`
     Minus,
+    /// `-` (unary)
     UnaryMinus,
+    /// `*`
     Multiply,
+    /// `/`
     Divide,
+    /// `%`
     Modulo,
+    /// `~`
     PowerOf,
+    /// `<<`
     LeftShift,
+    /// `>>`
     RightShift,
+    /// `;`
     SemiColon,
+    /// `:`
     Colon,
+    /// `::`
     DoubleColon,
+    /// `,`
     Comma,
+    /// `.`
     Period,
+    /// `#{`
     MapStart,
+    /// `=`
     Equals,
+    /// `true`
     True,
+    /// `false`
     False,
+    /// `let`
     Let,
+    /// `const`
     Const,
+    /// `if`
     If,
+    /// `else`
     Else,
+    /// `while`
     While,
+    /// `loop`
     Loop,
+    /// `for`
     For,
+    /// `in`
     In,
+    /// `<`
     LessThan,
+    /// `>`
     GreaterThan,
+    /// `<=`
     LessThanEqualsTo,
+    /// `>=`
     GreaterThanEqualsTo,
+    /// `==`
     EqualsTo,
+    /// `!=`
     NotEqualsTo,
+    /// `!`
     Bang,
+    /// `|`
     Pipe,
+    /// `||`
     Or,
+    /// `^`
     XOr,
+    /// `&`
     Ampersand,
+    /// `&&`
     And,
+    /// `fn`
+    ///
+    /// Never appears under the `no_function` feature.
     #[cfg(not(feature = "no_function"))]
     Fn,
+    /// `continue`
     Continue,
+    /// `break`
     Break,
+    /// `return`
     Return,
+    /// `throw`
     Throw,
+    /// `+=`
     PlusAssign,
+    /// `-=`
     MinusAssign,
+    /// `*=`
     MultiplyAssign,
+    /// `/=`
     DivideAssign,
+    /// `<<=`
     LeftShiftAssign,
+    /// `>>=`
     RightShiftAssign,
+    /// `&=`
     AndAssign,
+    /// `|=`
     OrAssign,
+    /// `^=`
     XOrAssign,
+    /// `%=`
     ModuloAssign,
+    /// `~=`
     PowerOfAssign,
+    /// `private`
+    ///
+    /// Never appears under the `no_function` feature.
     #[cfg(not(feature = "no_function"))]
     Private,
+    /// `import`
+    ///
+    /// Never appears under the `no_module` feature.
     #[cfg(not(feature = "no_module"))]
     Import,
+    /// `export`
+    ///
+    /// Never appears under the `no_module` feature.
     #[cfg(not(feature = "no_module"))]
     Export,
+    /// `as`
+    ///
+    /// Never appears under the `no_module` feature.
     #[cfg(not(feature = "no_module"))]
     As,
+    /// A lexer error.
     LexError(Box<LexError>),
+    /// A comment block.
     Comment(String),
+    /// A reserved symbol.
     Reserved(String),
+    /// A custom keyword.
     Custom(String),
+    /// End of the input stream.
     EOF,
 }
 
@@ -566,7 +658,7 @@ impl Token {
         }
     }
 
-    /// Is this token a reserved keyword?
+    /// Is this token a reserved symbol?
     pub fn is_reserved(&self) -> bool {
         match self {
             Self::Reserved(_) => true,
@@ -590,6 +682,11 @@ impl From<Token> for String {
 }
 
 /// State of the tokenizer.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 #[derive(Debug, Clone, Eq, PartialEq, Default)]
 pub struct TokenizeState {
     /// Maximum length of a string (0 = unlimited).
@@ -605,6 +702,11 @@ pub struct TokenizeState {
 }
 
 /// Trait that encapsulates a peekable character input stream.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This trait is volatile and may change.
 pub trait InputStream {
     /// Get the next character
     fn get_next(&mut self) -> Option<char>;
@@ -629,6 +731,11 @@ pub fn is_valid_identifier(name: impl Iterator<Item = char>) -> bool {
 }
 
 /// Parse a string literal wrapped by `enclosing_char`.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 pub fn parse_string_literal(
     stream: &mut impl InputStream,
     state: &mut TokenizeState,
@@ -794,7 +901,12 @@ fn scan_comment(
     }
 }
 
-/// Get the next token.
+/// Get the next token from the `InputStream`.
+/// Exported under the `internals` feature only.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 pub fn get_next_token(
     stream: &mut impl InputStream,
     state: &mut TokenizeState,

src/utils.rs

@@ -92,9 +92,12 @@ pub fn calc_fn_spec<'a>(
     s.finish()
 }
 
-/// A type to hold a number of values in static storage for no-allocation, quick access.
+/// An array-like type that holds a number of values in static storage for no-allocation, quick access.
+/// Exported under the `internals` feature only.
+///
 /// If too many items are stored, it converts into using a `Vec`.
 ///
+///
 /// This is essentially a knock-off of the [`staticvec`](https://crates.io/crates/staticvec) crate.
 /// This simplified implementation here is to avoid pulling in another crate.
 ///
@@ -130,6 +133,10 @@ pub fn calc_fn_spec<'a>(
 /// # Safety
 ///
 /// This type uses some unsafe code (mainly for uninitialized/unused array slots) for efficiency.
+///
+/// ## WARNING
+///
+/// This type is volatile and may change.
 //
 // TODO - remove unsafe code
 pub struct StaticVec<T> {