Refine doc comments.

CHANGELOG.md

@@ -14,6 +14,7 @@ New features
 
 * Each `Dynamic` value can now contain arbitrary data (type `i16`) in the form of a _tag_. This is to use up otherwise wasted space in the `Dynamic` type.
 * A new internal feature `no_smartstring` to turn off `SmartString` for those rare cases that it is needed.
+* `DynamicReadLock` and `DynamicWriteLoc` are exposed under `internals`.
 
 
 Version 0.20.1

src/ast.rs

@@ -53,6 +53,8 @@ pub struct ScriptFnDef {
     /// Encapsulated running environment, if any.
     pub lib: Option<Shared<Module>>,
     /// Encapsulated imported modules.
+    ///
+    /// Not available under `no_module`.
     #[cfg(not(feature = "no_module"))]
     pub mods: crate::engine::Imports,
     /// Function name.
@@ -62,9 +64,14 @@ pub struct ScriptFnDef {
     /// Names of function parameters.
     pub params: StaticVec<Identifier>,
     /// Access to external variables.
+    ///
+    /// Not available under `no_closure`.
     #[cfg(not(feature = "no_closure"))]
     pub externals: std::collections::BTreeSet<Identifier>,
-    /// Function doc-comments (if any).
+    /// _(METADATA)_ Function doc-comments (if any).
+    /// Exported under the `metadata` feature only.
+    ///
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[cfg(feature = "metadata")]
     pub comments: StaticVec<String>,
@@ -98,7 +105,10 @@ impl fmt::Display for ScriptFnDef {
 #[cfg(not(feature = "no_function"))]
 #[derive(Debug, Eq, PartialEq, Clone, Hash)]
 pub struct ScriptFnMetadata<'a> {
-    /// Function doc-comments (if any).
+    /// _(METADATA)_ Function doc-comments (if any).
+    /// Exported under the `metadata` feature only.
+    ///
+    /// Not available under `no_function`.
     ///
     /// Block doc-comments are kept in a single string slice with line-breaks within.
     ///
@@ -180,6 +190,8 @@ pub struct AST {
     /// Script-defined functions.
     functions: Shared<Module>,
     /// Embedded module resolver, if any.
+    ///
+    /// Not available under `no_module`.
     #[cfg(not(feature = "no_module"))]
     resolver: Option<Shared<crate::module::resolvers::StaticModuleResolver>>,
 }
@@ -287,7 +299,7 @@ impl AST {
     /// _(INTERNALS)_ Get the internal shared [`Module`] containing all script-defined functions.
     /// Exported under the `internals` feature only.
     ///
-    /// Not available under `no_function`.
+    /// Not available under `no_function` or `no_module`.
     #[cfg(feature = "internals")]
     #[deprecated = "this method is volatile and may change"]
     #[cfg(not(feature = "no_module"))]
@@ -323,6 +335,8 @@ impl AST {
     }
     /// _(INTERNALS)_ Get the embedded [module resolver][crate::ModuleResolver].
     /// Exported under the `internals` feature only.
+    ///
+    /// Not available under `no_module`.
     #[cfg(not(feature = "no_module"))]
     #[cfg(feature = "internals")]
     #[inline(always)]
@@ -960,12 +974,18 @@ pub enum Stmt {
     /// `return`/`throw`
     Return(ReturnType, Option<Expr>, Position),
     /// `import` expr `as` var
+    ///
+    /// Not available under `no_module`.
     #[cfg(not(feature = "no_module"))]
     Import(Expr, Option<Box<Ident>>, Position),
     /// `export` var `as` var `,` ...
+    ///
+    /// Not available under `no_module`.
     #[cfg(not(feature = "no_module"))]
     Export(Box<[(Ident, Option<Ident>)]>, Position),
     /// Convert a variable to shared.
+    ///
+    /// Not available under `no_closure`.
     #[cfg(not(feature = "no_closure"))]
     Share(Identifier),
 }
@@ -1529,6 +1549,8 @@ impl FnCallExpr {
 }
 
 /// A type that wraps a floating-point number and implements [`Hash`].
+///
+/// Not available under `no_float`.
 #[cfg(not(feature = "no_float"))]
 #[derive(Clone, Copy, PartialEq, PartialOrd)]
 pub struct FloatWrapper<F>(F);
@@ -1659,6 +1681,8 @@ pub enum Expr {
     /// Integer constant.
     IntegerConstant(INT, Position),
     /// Floating-point constant.
+    ///
+    /// Not available under `no_float`.
     #[cfg(not(feature = "no_float"))]
     FloatConstant(FloatWrapper<FLOAT>, Position),
     /// Character constant.

src/dynamic.rs

@@ -164,20 +164,29 @@ pub enum Union {
     /// An integer value.
     Int(INT, Tag, AccessMode),
     /// A floating-point value.
+    ///
+    /// Not available under `no_float`.
     #[cfg(not(feature = "no_float"))]
     Float(FloatWrapper<FLOAT>, Tag, AccessMode),
-    /// A fixed-precision decimal value.
+    /// _(DECIMAL)_ A fixed-precision decimal value.
+    /// Exported under the `decimal` feature only.
     #[cfg(feature = "decimal")]
     Decimal(Box<Decimal>, Tag, AccessMode),
     /// An array value.
+    ///
+    /// Not available under `no_index`.
     #[cfg(not(feature = "no_index"))]
     Array(Box<Array>, Tag, AccessMode),
     /// An object map value.
+    ///
+    /// Not available under `no_object`.
     #[cfg(not(feature = "no_object"))]
     Map(Box<Map>, Tag, AccessMode),
     /// A function pointer.
     FnPtr(Box<FnPtr>, Tag, AccessMode),
     /// A timestamp value.
+    ///
+    /// Not available under `no-std`.
     #[cfg(not(feature = "no_std"))]
     TimeStamp(Box<Instant>, Tag, AccessMode),
 
@@ -185,14 +194,21 @@ pub enum Union {
     Variant(Box<Box<dyn Variant>>, Tag, AccessMode),
 
     /// A _shared_ value of any type.
+    ///
+    /// Not available under `no_closure`.
     #[cfg(not(feature = "no_closure"))]
     Shared(crate::Shared<crate::Locked<Dynamic>>, Tag, AccessMode),
 }
 
-/// Underlying [`Variant`] read guard for [`Dynamic`].
+/// _(INTERNALS)_ Lock guard for reading a [`Dynamic`].
+/// Exported under the `internals` feature only.
 ///
-/// This data structure provides transparent interoperability between
+/// This type provides transparent interoperability between normal [`Dynamic`] and shared
-/// normal [`Dynamic`] and shared [`Dynamic`] values.
+/// [`Dynamic`] values.
+///
+/// # Volatile Data Structure
+///
+/// This type is volatile and may change.
 #[derive(Debug)]
 pub struct DynamicReadLock<'d, T: Clone>(DynamicReadLockInner<'d, T>);
 
@@ -226,10 +242,15 @@ impl<'d, T: Any + Clone> Deref for DynamicReadLock<'d, T> {
     }
 }
 
-/// Underlying [`Variant`] write guard for [`Dynamic`].
+/// _(INTERNALS)_ Lock guard for writing a [`Dynamic`].
+/// Exported under the `internals` feature only.
 ///
-/// This data structure provides transparent interoperability between
+/// This type provides transparent interoperability between normal [`Dynamic`] and shared
-/// normal [`Dynamic`] and shared [`Dynamic`] values.
+/// [`Dynamic`] values.
+///
+/// # Volatile Data Structure
+///
+/// This type is volatile and may change.
 #[derive(Debug)]
 pub struct DynamicWriteLock<'d, T: Clone>(DynamicWriteLockInner<'d, T>);
 
@@ -758,21 +779,27 @@ impl Dynamic {
     pub const ONE: Dynamic = Self(Union::Int(1, DEFAULT_TAG, AccessMode::ReadWrite));
     /// A [`Dynamic`] containing the integer negative one.
     pub const NEGATIVE_ONE: Dynamic = Self(Union::Int(-1, DEFAULT_TAG, AccessMode::ReadWrite));
-    /// A [`Dynamic`] containing the floating-point zero.
+    /// A [`Dynamic`] containing `0.0`.
+    ///
+    /// Not available under `no_float`.
     #[cfg(not(feature = "no_float"))]
     pub const FLOAT_ZERO: Dynamic = Self(Union::Float(
         FloatWrapper::const_new(0.0),
         DEFAULT_TAG,
         AccessMode::ReadWrite,
     ));
-    /// A [`Dynamic`] containing the floating-point one.
+    /// A [`Dynamic`] containing `1.0`.
+    ///
+    /// Not available under `no_float`.
     #[cfg(not(feature = "no_float"))]
     pub const FLOAT_ONE: Dynamic = Self(Union::Float(
         FloatWrapper::const_new(1.0),
         DEFAULT_TAG,
         AccessMode::ReadWrite,
     ));
-    /// A [`Dynamic`] containing the floating-point negative one.
+    /// A [`Dynamic`] containing the `-1.0`.
+    ///
+    /// Not available under `no_float`.
     #[cfg(not(feature = "no_float"))]
     pub const FLOAT_NEGATIVE_ONE: Dynamic = Self(Union::Float(
         FloatWrapper::const_new(-1.0),
@@ -1806,7 +1833,7 @@ impl From<&crate::Identifier> for Dynamic {
 }
 #[cfg(not(feature = "no_index"))]
 impl Dynamic {
-    /// Create a [`Dynamc`] from an [`Array`].
+    /// Create a [`Dynamic`] from an [`Array`].
     #[inline(always)]
     pub(crate) fn from_array(array: Array) -> Self {
         Self(Union::Array(
@@ -1851,7 +1878,7 @@ impl<T: Variant + Clone> std::iter::FromIterator<T> for Dynamic {
 }
 #[cfg(not(feature = "no_object"))]
 impl Dynamic {
-    /// Create a [`Dynamc`] from a [`Map`].
+    /// Create a [`Dynamic`] from a [`Map`].
     #[inline(always)]
     pub(crate) fn from_map(map: Map) -> Self {
         Self(Union::Map(

src/engine_api.rs

@@ -183,6 +183,8 @@ impl Engine {
     /// Register a custom type for use with the [`Engine`].
     /// The type must implement [`Clone`].
     ///
+    /// Not available under `no_object`.
+    ///
     /// # Example
     ///
     /// ```
@@ -224,6 +226,8 @@ impl Engine {
     /// Register a custom type for use with the [`Engine`], with a pretty-print name
     /// for the `type_of` function. The type must implement [`Clone`].
     ///
+    /// Not available under `no_object`.
+    ///
     /// # Example
     ///
     /// ```
@@ -284,6 +288,8 @@ impl Engine {
     ///
     /// The function signature must start with `&mut self` and not `&self`.
     ///
+    /// Not available under `no_object`.
+    ///
     /// # Example
     ///
     /// ```
@@ -329,6 +335,8 @@ impl Engine {
     ///
     /// The function signature must start with `&mut self` and not `&self`.
     ///
+    /// Not available under `no_object`.
+    ///
     /// # Example
     ///
     /// ```
@@ -374,6 +382,8 @@ impl Engine {
     }
     /// Register a setter function for a member of a registered type with the [`Engine`].
     ///
+    /// Not available under `no_object`.
+    ///
     /// # Example
     ///
     /// ```
@@ -420,6 +430,8 @@ impl Engine {
     }
     /// Register a setter function for a member of a registered type with the [`Engine`].
     ///
+    /// Not available under `no_object`.
+    ///
     /// # Example
     ///
     /// ```
@@ -474,6 +486,8 @@ impl Engine {
     ///
     /// All function signatures must start with `&mut self` and not `&self`.
     ///
+    /// Not available under `no_object`.
+    ///
     /// # Example
     ///
     /// ```
@@ -522,6 +536,8 @@ impl Engine {
     ///
     /// The function signature must start with `&mut self` and not `&self`.
     ///
+    /// Not available under `no_index`.
+    ///
     /// # Panics
     ///
     /// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@@ -586,6 +602,8 @@ impl Engine {
     ///
     /// The function signature must start with `&mut self` and not `&self`.
     ///
+    /// Not available under `no_index`.
+    ///
     /// # Panics
     ///
     /// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@@ -654,6 +672,8 @@ impl Engine {
     }
     /// Register an index setter for a custom type with the [`Engine`].
     ///
+    /// Not available under `no_index`.
+    ///
     /// # Panics
     ///
     /// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@@ -718,6 +738,8 @@ impl Engine {
     }
     /// Register an index setter for a custom type with the [`Engine`].
     ///
+    /// Not available under `no_index`.
+    ///
     /// # Panics
     ///
     /// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@@ -792,6 +814,8 @@ impl Engine {
     }
     /// Short-hand for register both index getter and setter functions for a custom type with the [`Engine`].
     ///
+    /// Not available under `no_index`.
+    ///
     /// # Panics
     ///
     /// Panics if the type is [`Array`], [`Map`], [`String`], [`ImmutableString`][crate::ImmutableString] or `&str`.
@@ -870,6 +894,8 @@ impl Engine {
     /// Functions marked [`FnNamespace::Global`] and type iterators are exposed to scripts without
     /// namespace qualifications.
     ///
+    /// Not available under `no_module`.
+    ///
     /// # Example
     ///
     /// ```
@@ -1024,6 +1050,8 @@ impl Engine {
     /// Compile a string into an [`AST`] using own scope, which can be used later for evaluation,
     /// embedding all imported modules.
     ///
+    /// Not available under `no_module`.
+    ///
     /// Modules referred by `import` statements containing literal string paths are eagerly resolved
     /// via the current [module resolver][crate::ModuleResolver] and embedded into the resultant
     /// [`AST`]. When it is evaluated later, `import` statement directly recall pre-resolved
@@ -1272,6 +1300,8 @@ impl Engine {
     /// Parse a JSON string into an [object map][`Map`].
     /// This is a light-weight alternative to using, say, [`serde_json`] to deserialize the JSON.
     ///
+    /// Not available under `no_object`.
+    ///
     /// The JSON string must be an object hash.  It cannot be a simple scalar value.
     ///
     /// Set `has_null` to `true` in order to map `null` values to `()`.
@@ -1788,6 +1818,8 @@ impl Engine {
     /// Call a script function defined in an [`AST`] with multiple arguments.
     /// Arguments are passed as a tuple.
     ///
+    /// Not available under `no_function`.
+    ///
     /// The [`AST`] is evaluated before calling the function.
     /// This allows a script to load the necessary modules.
     /// This is usually desired. If not, a specialized [`AST`] can be prepared that contains only
@@ -1855,6 +1887,8 @@ impl Engine {
     /// Call a script function defined in an [`AST`] with multiple [`Dynamic`] arguments
     /// and optionally a value for binding to the `this` pointer.
     ///
+    /// Not available under `no_function`.
+    ///
     /// There is an option to evaluate the [`AST`] to load necessary modules before calling the function.
     ///
     /// # WARNING
@@ -1971,6 +2005,8 @@ impl Engine {
     /// Optimize the [`AST`] with constants defined in an external Scope.
     /// An optimized copy of the [`AST`] is returned while the original [`AST`] is consumed.
     ///
+    /// Not available under `no_optimize`.
+    ///
     /// Although optimization is performed by default during compilation, sometimes it is necessary to
     /// _re_-optimize an [`AST`]. For example, when working with constants that are passed in via an
     /// external scope, it will be more efficient to optimize the [`AST`] once again to take advantage
@@ -2003,7 +2039,7 @@ impl Engine {
         let stmt = std::mem::take(ast.statements_mut());
         crate::optimize::optimize_into_ast(self, scope, stmt.into_vec(), lib, optimization_level)
     }
-    /// Generate a list of all registered functions.
+    /// _(METADATA)_ Generate a list of all registered functions.
     /// Exported under the `metadata` feature only.
     ///
     /// Functions from the following sources are included, in order:
@@ -2074,6 +2110,8 @@ impl Engine {
     }
     /// Register a callback for script evaluation progress.
     ///
+    /// Not available under `unchecked`.
+    ///
     /// # Example
     ///
     /// ```

src/fn_native.rs

@@ -39,10 +39,14 @@ pub use std::rc::Rc as Shared;
 pub use std::sync::Arc as Shared;
 
 /// Synchronized shared object.
+///
+/// Not available under `no_closure`.
 #[cfg(not(feature = "no_closure"))]
 #[cfg(not(feature = "sync"))]
 pub use std::cell::RefCell as Locked;
 /// Synchronized shared object.
+///
+/// Not available under `no_closure`.
 #[cfg(not(feature = "no_closure"))]
 #[cfg(feature = "sync")]
 pub use std::sync::RwLock as Locked;
@@ -101,6 +105,8 @@ impl<'a> NativeCallContext<'a> {
     }
     /// _(INTERNALS)_ Create a new [`NativeCallContext`].
     /// Exported under the `internals` feature only.
+    ///
+    /// Not available under `no_module`.
     #[cfg(feature = "internals")]
     #[cfg(not(feature = "no_module"))]
     #[inline(always)]
@@ -135,6 +141,8 @@ impl<'a> NativeCallContext<'a> {
         self.source
     }
     /// Get an iterator over the current set of modules imported via `import` statements.
+    ///
+    /// Not available under `no_module`.
     #[cfg(not(feature = "no_module"))]
     #[inline(always)]
     pub fn iter_imports(&self) -> impl Iterator<Item = (&str, &Module)> {
@@ -151,6 +159,8 @@ impl<'a> NativeCallContext<'a> {
     }
     /// _(INTERNALS)_ The current set of modules imported via `import` statements.
     /// Exported under the `internals` feature only.
+    ///
+    /// Not available under `no_module`.
     #[cfg(feature = "internals")]
     #[cfg(not(feature = "no_module"))]
     #[inline(always)]
@@ -303,6 +313,8 @@ impl FnPtr {
         !self.1.is_empty()
     }
     /// Does the function pointer refer to an anonymous function?
+    ///
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     #[inline(always)]
     pub fn is_anonymous(&self) -> bool {
@@ -467,6 +479,8 @@ pub enum CallableFunction {
     /// A plugin function,
     Plugin(Shared<FnPlugin>),
     /// A script-defined function.
+    ///
+    /// Not available under `no_function`.
     #[cfg(not(feature = "no_function"))]
     Script(Shared<crate::ast::ScriptFnDef>),
 }
@@ -601,6 +615,8 @@ impl CallableFunction {
     }
     /// Get a shared reference to a script-defined function definition.
     ///
+    /// Not available under `no_function`.
+    ///
     /// # Panics
     ///
     /// Panics if the [`CallableFunction`] is not [`Script`][CallableFunction::Script].

src/fn_register.rs

@@ -61,15 +61,15 @@ pub trait RegisterNativeFunction<Args, Result> {
     fn into_callable_function(self) -> CallableFunction;
     /// Get the type ID's of this function's parameters.
     fn param_types() -> Box<[TypeId]>;
-    /// Get the type names of this function's parameters.
+    /// _(METADATA)_ Get the type names of this function's parameters.
     /// Exported under the `metadata` feature only.
     #[cfg(feature = "metadata")]
     fn param_names() -> Box<[&'static str]>;
-    /// Get the type ID of this function's return value.
+    /// _(METADATA)_ Get the type ID of this function's return value.
     /// Exported under the `metadata` feature only.
     #[cfg(feature = "metadata")]
     fn return_type() -> TypeId;
-    /// Get the type name of this function's return value.
+    /// _(METADATA)_ Get the type name of this function's return value.
     /// Exported under the `metadata` feature only.
     #[cfg(feature = "metadata")]
     fn return_type_name() -> &'static str;

src/lib.rs

@@ -209,13 +209,15 @@ pub use optimize::OptimizationLevel;
 #[deprecated = "this type is volatile and may change"]
 pub use dynamic::{DynamicReadLock, DynamicWriteLock, Variant};
 
+// Expose internal data structures.
+#[cfg(feature = "internals")]
+#[deprecated = "this function is volatile and may change"]
+pub use token::{get_next_token, parse_string_literal};
+
 // Expose internal data structures.
 #[cfg(feature = "internals")]
 #[deprecated = "this type is volatile and may change"]
-pub use token::{
+pub use token::{InputStream, Token, TokenizeState, TokenizerControl, TokenizerControlBlock};
-    get_next_token, parse_string_literal, InputStream, Token, TokenizeState, TokenizerControl,
-    TokenizerControlBlock,
-};
 
 #[cfg(feature = "internals")]
 #[deprecated = "this type is volatile and may change"]