Refine docs.

This commit is contained in:
Stephen Chung
2020-12-26 23:21:16 +08:00
parent 66d3af256e
commit 88f63fa24b
16 changed files with 116 additions and 58 deletions

View File

@@ -736,7 +736,7 @@ impl Stmt {
_ => false,
}
}
/// Get the [position][`Position`] of this statement.
/// Get the [position][Position] of this statement.
pub fn position(&self) -> Position {
match self {
Self::Noop(pos)
@@ -765,7 +765,7 @@ impl Stmt {
Self::Share(x) => x.pos,
}
}
/// Override the [position][`Position`] of this statement.
/// Override the [position][Position] of this statement.
pub fn set_position(&mut self, new_pos: Position) -> &mut Self {
match self {
Self::Noop(pos)
@@ -973,7 +973,7 @@ pub enum Expr {
Property(Box<(ImmutableString, ImmutableString, Ident)>),
/// { [statement][Stmt] }
Stmt(Box<StaticVec<Stmt>>, Position),
/// Wrapped [expression][`Expr`] - should not be optimized away.
/// Wrapped [expression][Expr] - should not be optimized away.
Expr(Box<Expr>),
/// func `(` expr `,` ... `)`
FnCall(Box<FnCallExpr>, Position),
@@ -1052,7 +1052,7 @@ impl Expr {
_ => None,
}
}
/// Get the [position][`Position`] of the expression.
/// Get the [position][Position] of the expression.
pub fn position(&self) -> Position {
match self {
Self::Expr(x) => x.position(),
@@ -1082,7 +1082,7 @@ impl Expr {
Self::Custom(_, pos) => *pos,
}
}
/// Override the [position][`Position`] of the expression.
/// Override the [position][Position] of the expression.
pub fn set_position(&mut self, new_pos: Position) -> &mut Self {
match self {
Self::Expr(x) => {

View File

@@ -19,8 +19,7 @@ use crate::stdlib::{
fmt, format,
hash::{Hash, Hasher},
iter::{empty, once, FromIterator},
num::NonZeroU64,
num::NonZeroUsize,
num::{NonZeroU64, NonZeroU8, NonZeroUsize},
ops::DerefMut,
string::{String, ToString},
};
@@ -637,7 +636,7 @@ pub struct Engine {
/// A hashset containing symbols to disable.
pub(crate) disabled_symbols: HashSet<String>,
/// A hashmap containing custom keywords and precedence to recognize.
pub(crate) custom_keywords: HashMap<String, Option<u8>>,
pub(crate) custom_keywords: HashMap<String, Option<NonZeroU8>>,
/// Custom syntax.
pub(crate) custom_syntax: HashMap<ImmutableString, CustomSyntax>,
/// Callback closure for resolving variable access.
@@ -989,7 +988,7 @@ impl Engine {
new_val: Option<(Dynamic, Position)>,
) -> Result<(Dynamic, bool), Box<EvalAltResult>> {
if chain_type == ChainType::None {
panic!();
unreachable!();
}
let is_ref = target.is_ref();

View File

@@ -723,21 +723,22 @@ impl Engine {
self.register_indexer_get(getter)
.register_indexer_set(setter)
}
/// Register a shared [`Module`][crate::Module] into the global namespace of [`Engine`].
/// Register a shared [`Module`] into the global namespace of [`Engine`].
///
/// All functions and type iterators are automatically available to scripts without namespace qualifications.
/// All functions and type iterators are automatically available to scripts without namespace
/// qualifications.
///
/// Sub-modules and variables are **ignored**.
///
/// When searching for functions, modules loaded later are preferred.
/// In other words, loaded modules are searched in reverse order.
/// When searching for functions, modules loaded later are preferred. In other words, loaded
/// modules are searched in reverse order.
#[inline(always)]
pub fn register_global_module(&mut self, module: Shared<Module>) -> &mut Self {
// Insert the module into the front
self.global_modules.insert(0, module);
self
}
/// Register a shared [`Module`][crate::Module] into the global namespace of [`Engine`].
/// Register a shared [`Module`] into the global namespace of [`Engine`].
///
/// ## Deprecated
///
@@ -747,9 +748,11 @@ impl Engine {
pub fn load_package(&mut self, module: impl Into<Shared<Module>>) -> &mut Self {
self.register_global_module(module.into())
}
/// Register a shared [`Module`][crate::Module] as a static module namespace with the [`Engine`].
/// Register a shared [`Module`] as a static module namespace with the
/// [`Engine`].
///
/// Functions marked `FnNamespace::Global` and type iterators are exposed to scripts without namespace qualifications.
/// Functions marked [`FnNamespace::Global`] and type iterators are exposed to scripts without
/// namespace qualifications.
///
/// # Example
///
@@ -825,7 +828,7 @@ impl Engine {
self
}
/// Register a shared [`Module`][crate::Module] as a static module namespace with the [`Engine`].
/// Register a shared [`Module`] as a static module namespace with the [`Engine`].
///
/// ## Deprecated
///
@@ -1719,7 +1722,7 @@ impl Engine {
/// With this method, it is no longer necessary to recompile a large script.
/// The script [`AST`] can be compiled just once. Before evaluation,
/// constants are passed into the [`Engine`] via an external scope
/// (i.e. with [`scope.push_constant(...)`][crate::Scope::push_constant]).
/// (i.e. with [`Scope::push_constant`]).
/// Then, the [`AST`] is cloned and the copy re-optimized before running.
#[cfg(not(feature = "no_optimize"))]
#[inline]

View File

@@ -356,7 +356,7 @@ impl Module {
self.get_var(name).and_then(Dynamic::try_cast::<T>)
}
/// Get a module variable as a [`Dynamic`][crate::Dynamic].
/// Get a module variable as a [`Dynamic`].
///
/// # Example
///
@@ -466,10 +466,18 @@ impl Module {
}
/// Get a mutable reference to the underlying [`HashMap`] of sub-modules.
///
/// ## Warning
///
/// By taking a mutable reference, it is assumed that some sub-modules will be modified.
/// Thus the module is automatically set to be non-indexed.
#[inline(always)]
pub(crate) fn sub_modules_mut(&mut self) -> &mut HashMap<ImmutableString, Shared<Module>> {
// We must assume that the user has changed the sub-modules
// (otherwise why take a mutable reference?)
self.all_functions.clear();
self.all_variables.clear();
self.all_type_iterators.clear();
self.indexed = false;
&mut self.modules
@@ -652,7 +660,7 @@ impl Module {
}
/// Set a Rust function taking a reference to the scripting [`Engine`][crate::Engine],
/// the current set of functions, plus a list of mutable [`Dynamic`][crate::Dynamic] references
/// the current set of functions, plus a list of mutable [`Dynamic`] references
/// into the module, returning a hash key.
///
/// Use this to register a built-in function which must reference settings on the scripting
@@ -667,7 +675,7 @@ impl Module {
///
/// A list of [`TypeId`]'s is taken as the argument types.
///
/// Arguments are simply passed in as a mutable array of [`&mut Dynamic`][crate::Dynamic],
/// Arguments are simply passed in as a mutable array of [`&mut Dynamic`],
/// which is guaranteed to contain enough arguments of the correct types.
///
/// The function is assumed to be a _method_, meaning that the first argument should not be consumed.

View File

@@ -152,7 +152,7 @@ fn call_fn_with_constant_arguments(
.map(|(v, _)| v)
}
/// Optimize a block of [statements][crate::ast::Stmt].
/// Optimize a block of [statements][Stmt].
fn optimize_stmt_block(
mut statements: Vec<Stmt>,
pos: Position,
@@ -277,7 +277,7 @@ fn optimize_stmt_block(
}
}
/// Optimize a [statement][crate::ast::Stmt].
/// Optimize a [statement][Stmt].
fn optimize_stmt(stmt: &mut Stmt, state: &mut State, preserve_result: bool) {
match stmt {
// expr op= expr
@@ -473,7 +473,7 @@ fn optimize_stmt(stmt: &mut Stmt, state: &mut State, preserve_result: bool) {
}
}
/// Optimize an [expression][crate::ast::Expr].
/// Optimize an [expression][Expr].
fn optimize_expr(expr: &mut Expr, state: &mut State) {
// These keywords are handled specially
const DONT_EVAL_KEYWORDS: &[&str] = &[
@@ -737,7 +737,7 @@ fn optimize_expr(expr: &mut Expr, state: &mut State) {
}
}
/// Optimize a block of [statements][crate::ast::Stmt] at top level.
/// Optimize a block of [statements][Stmt] at top level.
fn optimize_top_level(
mut statements: Vec<Stmt>,
engine: &Engine,