Refine doc comments.

src/api/mod.rs

@@ -16,6 +16,8 @@ pub mod call_fn;
 
 pub mod options;
 
+pub mod optimize;
+
 pub mod limits;
 
 pub mod events;
@@ -59,83 +61,6 @@ pub mod default_limits {
     pub const MAX_DYNAMIC_PARAMETERS: usize = 16;
 }
 
-/// Script optimization API.
-#[cfg(not(feature = "no_optimize"))]
-impl Engine {
-    /// Control whether and how the [`Engine`] will optimize an [`AST`][crate::AST] after compilation.
-    ///
-    /// Not available under `no_optimize`.
-    #[inline(always)]
-    pub fn set_optimization_level(
-        &mut self,
-        optimization_level: crate::OptimizationLevel,
-    ) -> &mut Self {
-        self.optimization_level = optimization_level;
-        self
-    }
-    /// The current optimization level.
-    /// It controls whether and how the [`Engine`] will optimize an [`AST`][crate::AST] after compilation.
-    ///
-    /// Not available under `no_optimize`.
-    #[inline(always)]
-    #[must_use]
-    pub const fn optimization_level(&self) -> crate::OptimizationLevel {
-        self.optimization_level
-    }
-    /// Optimize the [`AST`][crate::AST] with constants defined in an external Scope.
-    /// An optimized copy of the [`AST`][crate::AST] is returned while the original [`AST`][crate::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`][crate::AST].
-    ///
-    /// For example, when working with constants that are passed in via an external scope, it will
-    /// be more efficient to optimize the [`AST`][crate::AST] once again to take advantage of the
-    /// new constants.
-    ///
-    /// With this method, it is no longer necessary to recompile a large script. The script
-    /// [`AST`][crate::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]).
-    ///
-    /// Then, the [`AST`][crate::AST] is cloned and the copy re-optimized before running.
-    #[inline]
-    #[must_use]
-    pub fn optimize_ast(
-        &self,
-        scope: &crate::Scope,
-        ast: crate::AST,
-        optimization_level: crate::OptimizationLevel,
-    ) -> crate::AST {
-        let mut ast = ast;
-
-        #[cfg(not(feature = "no_function"))]
-        let lib = ast
-            .shared_lib()
-            .iter_fn()
-            .filter(|f| f.func.is_script())
-            .map(|f| {
-                f.func
-                    .get_script_fn_def()
-                    .expect("script-defined function")
-                    .clone()
-            })
-            .collect();
-
-        crate::optimizer::optimize_into_ast(
-            self,
-            scope,
-            ast.take_statements(),
-            #[cfg(not(feature = "no_function"))]
-            lib,
-            optimization_level,
-        )
-    }
-}
-
 impl Engine {
     /// Set the module resolution service used by the [`Engine`].
     ///
@@ -149,6 +74,7 @@ impl Engine {
         self.module_resolver = Some(Box::new(resolver));
         self
     }
+
     /// Disable a particular keyword or operator in the language.
     ///
     /// # Examples
@@ -190,6 +116,7 @@ impl Engine {
         self.disabled_symbols.insert(symbol.into());
         self
     }
+
     /// Register a custom operator with a precedence into the language.
     ///
     /// The operator can be a valid identifier, a reserved symbol, a disabled operator or a disabled keyword.

src/api/optimize.rs

@@ -0,0 +1,76 @@
+//! Module that defines the script optimization API of [`Engine`].
+#![cfg(not(feature = "no_optimize"))]
+
+use crate::{Engine, OptimizationLevel, Scope, AST};
+
+impl Engine {
+    /// Control whether and how the [`Engine`] will optimize an [`AST`] after compilation.
+    ///
+    /// Not available under `no_optimize`.
+    #[inline(always)]
+    pub fn set_optimization_level(&mut self, optimization_level: OptimizationLevel) -> &mut Self {
+        self.optimization_level = optimization_level;
+        self
+    }
+
+    /// The current optimization level.
+    /// It controls whether and how the [`Engine`] will optimize an [`AST`] after compilation.
+    ///
+    /// Not available under `no_optimize`.
+    #[inline(always)]
+    #[must_use]
+    pub const fn optimization_level(&self) -> OptimizationLevel {
+        self.optimization_level
+    }
+
+    /// 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 of the new constants.
+    ///
+    /// 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`][Scope::push_constant]).
+    ///
+    /// Then, the [`AST`] is cloned and the copy re-optimized before running.
+    #[inline]
+    #[must_use]
+    pub fn optimize_ast(
+        &self,
+        scope: &Scope,
+        ast: AST,
+        optimization_level: OptimizationLevel,
+    ) -> AST {
+        let mut ast = ast;
+
+        #[cfg(not(feature = "no_function"))]
+        let lib = ast
+            .shared_lib()
+            .iter_fn()
+            .filter(|f| f.func.is_script())
+            .map(|f| {
+                f.func
+                    .get_script_fn_def()
+                    .expect("script-defined function")
+                    .clone()
+            })
+            .collect();
+
+        crate::optimizer::optimize_into_ast(
+            self,
+            scope,
+            ast.take_statements(),
+            #[cfg(not(feature = "no_function"))]
+            lib,
+            optimization_level,
+        )
+    }
+}

src/ast/expr.rs

@@ -168,8 +168,6 @@ impl FnCallHashes {
 #[derive(Clone, Default, Hash)]
 pub struct FnCallExpr {
     /// Namespace of the function, if any.
-    ///
-    /// Not available under `no_module`.
     #[cfg(not(feature = "no_module"))]
     pub namespace: Option<crate::module::Namespace>,
     /// Function name.
@@ -369,8 +367,6 @@ pub enum Expr {
     /// Integer constant.
     IntegerConstant(INT, Position),
     /// Floating-point constant.
-    ///
-    /// Not available under `no_float`.
     #[cfg(not(feature = "no_float"))]
     FloatConstant(FloatWrapper<crate::FLOAT>, Position),
     /// Character constant.
@@ -575,11 +571,7 @@ impl Expr {
                 if !x.is_qualified() && x.args.len() == 1 && x.name == KEYWORD_FN_PTR =>
             {
                 if let Expr::StringConstant(ref s, ..) = x.args[0] {
-                    if let Ok(fn_ptr) = FnPtr::new(s) {
+                    FnPtr::new(s).ok()?.into()
-                        fn_ptr.into()
-                    } else {
-                        return None;
-                    }
                 } else {
                     return None;
                 }

src/ast/script_fn.rs

@@ -34,8 +34,6 @@ pub struct ScriptFnDef {
     /// Function body.
     pub body: StmtBlock,
     /// Encapsulated AST environment, if any.
-    ///
-    /// Not available under `no_module` or `no_function`.
     #[cfg(not(feature = "no_module"))]
     #[cfg(not(feature = "no_function"))]
     pub environ: Option<EncapsulatedEnviron>,

src/eval/global_state.rs

@@ -24,13 +24,9 @@ pub type GlobalConstants =
 #[derive(Clone)]
 pub struct GlobalRuntimeState<'a> {
     /// Stack of module names.
-    ///
-    /// Not available under `no_module`.
     #[cfg(not(feature = "no_module"))]
     keys: crate::StaticVec<Identifier>,
     /// Stack of imported [modules][crate::Module].
-    ///
-    /// Not available under `no_module`.
     #[cfg(not(feature = "no_module"))]
     modules: crate::StaticVec<crate::Shared<crate::Module>>,
     /// Source of the current context.

src/func/callable_function.rs

@@ -21,8 +21,6 @@ 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>),
 }

src/types/dynamic.rs

@@ -162,8 +162,6 @@ 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(crate::ast::FloatWrapper<crate::FLOAT>, Tag, AccessMode),
     /// _(decimal)_ A fixed-precision decimal value.
@@ -171,25 +169,17 @@ pub enum Union {
     #[cfg(feature = "decimal")]
     Decimal(Box<rust_decimal::Decimal>, Tag, AccessMode),
     /// An array value.
-    ///
-    /// Not available under `no_index`.
     #[cfg(not(feature = "no_index"))]
     Array(Box<crate::Array>, Tag, AccessMode),
     /// An blob (byte array).
-    ///
-    /// Not available under `no_index`.
     #[cfg(not(feature = "no_index"))]
     Blob(Box<crate::Blob>, Tag, AccessMode),
     /// An object map value.
-    ///
-    /// Not available under `no_object`.
     #[cfg(not(feature = "no_object"))]
     Map(Box<crate::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),
 
@@ -198,8 +188,6 @@ 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),
 }
@@ -256,8 +244,6 @@ enum DynamicWriteLockInner<'d, T: Clone> {
     Reference(&'d mut T),
 
     /// A write guard to a shared value.
-    ///
-    /// Not available under `no_closure`.
     #[cfg(not(feature = "no_closure"))]
     Guard(crate::func::native::LockGuard<'d, Dynamic>),
 }