Refine documentation and comments.

src/ast.rs

@@ -295,7 +295,7 @@ impl AST {
     ) -> Option<Shared<crate::module::resolvers::StaticModuleResolver>> {
         self.resolver.clone()
     }
-    /// _(INTERNALS)_ Get the embedded [module resolver][`ModuleResolver`].
+    /// _(INTERNALS)_ Get the embedded [module resolver][crate::ModuleResolver].
     /// Exported under the `internals` feature only.
     #[cfg(not(feature = "no_module"))]
     #[cfg(feature = "internals")]
@@ -318,7 +318,7 @@ impl AST {
     ///
     /// This operation is cheap because functions are shared.
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[inline(always)]
     pub fn clone_functions_only(&self) -> Self {
@@ -329,7 +329,7 @@ impl AST {
     ///
     /// This operation is cheap because functions are shared.
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[inline(always)]
     pub fn clone_functions_only_filtered(
@@ -614,7 +614,7 @@ impl AST {
     }
     /// Filter out the functions, retaining only some based on a filter predicate.
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     ///
     /// # Example
     ///
@@ -661,7 +661,7 @@ impl AST {
     }
     /// Iterate through all function definitions.
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[inline(always)]
     pub fn iter_functions<'a>(&'a self) -> impl Iterator<Item = ScriptFnMetadata> + 'a {
@@ -671,7 +671,7 @@ impl AST {
     }
     /// Clear all function definitions in the [`AST`].
     ///
-    /// Not available under [`no_function`].
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[inline(always)]
     pub fn clear_functions(&mut self) {

src/dynamic.rs

@@ -266,6 +266,8 @@ impl Dynamic {
         }
     }
     /// Is the value held by this [`Dynamic`] shared?
+    ///
+    /// Always [`false`] under the `no_closure` feature.
     #[inline(always)]
     pub fn is_shared(&self) -> bool {
         match self.0 {

src/module/mod.rs

@@ -221,6 +221,31 @@ impl AsRef<Module> for Module {
     }
 }
 
+impl<M: AsRef<Module>> Add<M> for &Module {
+    type Output = Module;
+
+    fn add(self, rhs: M) -> Self::Output {
+        let mut module = self.clone();
+        module.merge(rhs.as_ref());
+        module
+    }
+}
+
+impl<M: AsRef<Module>> Add<M> for Module {
+    type Output = Self;
+
+    fn add(mut self, rhs: M) -> Self::Output {
+        self.merge(rhs.as_ref());
+        self
+    }
+}
+
+impl<M: Into<Module>> AddAssign<M> for Module {
+    fn add_assign(&mut self, rhs: M) {
+        self.combine(rhs.into());
+    }
+}
+
 impl Module {
     /// Create a new [`Module`].
     ///
@@ -1983,13 +2008,16 @@ impl Module {
 ///
 /// This type is volatile and may change.
 #[derive(Clone, Eq, PartialEq, Default, Hash)]
-pub struct NamespaceRef(Option<NonZeroUsize>, StaticVec<Ident>);
+pub struct NamespaceRef {
+    index: Option<NonZeroUsize>,
+    path: StaticVec<Ident>,
+}
 
 impl fmt::Debug for NamespaceRef {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        fmt::Debug::fmt(&self.1, f)?;
+        fmt::Debug::fmt(&self.path, f)?;
 
-        if let Some(index) = self.0 {
+        if let Some(index) = self.index {
             write!(f, " -> {}", index)
         } else {
             Ok(())
@@ -2001,19 +2029,19 @@ impl Deref for NamespaceRef {
     type Target = StaticVec<Ident>;
 
     fn deref(&self) -> &Self::Target {
-        &self.1
+        &self.path
     }
 }
 
 impl DerefMut for NamespaceRef {
     fn deref_mut(&mut self) -> &mut Self::Target {
-        &mut self.1
+        &mut self.path
     }
 }
 
 impl fmt::Display for NamespaceRef {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        for Ident { name, .. } in self.1.iter() {
+        for Ident { name, .. } in self.path.iter() {
             write!(f, "{}{}", name, Token::DoubleColon.syntax())?;
         }
         Ok(())
@@ -2021,45 +2049,20 @@ impl fmt::Display for NamespaceRef {
 }
 
 impl From<StaticVec<Ident>> for NamespaceRef {
-    fn from(modules: StaticVec<Ident>) -> Self {
-        Self(None, modules)
-    }
-}
-
-impl<M: AsRef<Module>> Add<M> for &Module {
-    type Output = Module;
-
-    fn add(self, rhs: M) -> Self::Output {
-        let mut module = self.clone();
-        module.merge(rhs.as_ref());
-        module
-    }
-}
-
-impl<M: AsRef<Module>> Add<M> for Module {
-    type Output = Self;
-
-    fn add(mut self, rhs: M) -> Self::Output {
-        self.merge(rhs.as_ref());
-        self
-    }
-}
-
-impl<M: Into<Module>> AddAssign<M> for Module {
-    fn add_assign(&mut self, rhs: M) {
-        self.combine(rhs.into());
+    fn from(path: StaticVec<Ident>) -> Self {
+        Self { index: None, path }
     }
 }
 
 impl NamespaceRef {
     /// Get the [`Scope`][crate::Scope] index offset.
     pub(crate) fn index(&self) -> Option<NonZeroUsize> {
-        self.0
+        self.index
     }
     /// Set the [`Scope`][crate::Scope] index offset.
     #[cfg(not(feature = "no_module"))]
     pub(crate) fn set_index(&mut self, index: Option<NonZeroUsize>) {
-        self.0 = index
+        self.index = index
     }
 }
 

src/module/resolvers/collection.rs

@@ -1,7 +1,7 @@
 use crate::stdlib::{boxed::Box, ops::AddAssign, vec::Vec};
 use crate::{Engine, EvalAltResult, Module, ModuleResolver, Position, Shared};
 
-/// [Module] resolution service that holds a collection of [module][Module] resolves,
+/// [Module] resolution service that holds a collection of module resolvers,
 /// to be searched in sequential order.
 ///
 /// # Example

src/module/resolvers/mod.rs

@@ -29,7 +29,7 @@ pub trait ModuleResolver: SendSync {
         pos: Position,
     ) -> Result<Shared<Module>, Box<EvalAltResult>>;
 
-    /// Resolve a module into an `AST` based on a path string.
+    /// Resolve an `AST` based on a path string.
     ///
     /// Returns [`None`] (default) if such resolution is not supported
     /// (e.g. if the module is Rust-based).

src/module/resolvers/stat.rs

@@ -1,7 +1,7 @@
 use crate::stdlib::{boxed::Box, collections::HashMap, ops::AddAssign, string::String};
 use crate::{Engine, EvalAltResult, Module, ModuleResolver, Position, Shared};
 
-/// [Module] resolution service that serves [modules][Module] added into it.
+/// A static [module][Module] resolution service that serves [modules][Module] added into it.
 ///
 /// # Example
 ///

src/packages/mod.rs

@@ -50,7 +50,7 @@ pub trait Package {
     }
 }
 
-/// Macro that makes it easy to define a _package_ (which is basically a shared module)
+/// Macro that makes it easy to define a _package_ (which is basically a shared [module][Module])
 /// and register functions into it.
 ///
 /// Functions can be added to the package using the standard module methods such as
@@ -58,6 +58,8 @@ pub trait Package {
 ///
 /// # Example
 ///
+/// Define a package named `MyPackage` with a single function named `my_add`:
+///
 /// ```
 /// use rhai::{Dynamic, EvalAltResult};
 /// use rhai::def_package;
@@ -70,8 +72,6 @@ pub trait Package {
 ///     lib.set_fn_2("my_add", add);
 /// });
 /// ```
-///
-/// The above defines a package named 'MyPackage' with a single function named 'my_add'.
 #[macro_export]
 macro_rules! def_package {
     ($root:ident : $package:ident : $comment:expr , $lib:ident , $block:stmt) => {