From fd19d625b075f4f82c870db55d8fceda442ff7ac Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Mon, 10 May 2021 11:07:19 +0800 Subject: [PATCH] Refine doc comments. --- CHANGELOG.md | 1 + src/ast.rs | 30 ++++++++++++++++++++++++--- src/dynamic.rs | 51 +++++++++++++++++++++++++++++++++++----------- src/engine_api.rs | 40 +++++++++++++++++++++++++++++++++++- src/fn_native.rs | 16 +++++++++++++++ src/fn_register.rs | 6 +++--- src/lib.rs | 10 +++++---- 7 files changed, 131 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 247b0044..3c37b45f 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/src/ast.rs b/src/ast.rs index f4fa30ec..c0f096c6 100644 --- a/src/ast.rs +++ b/src/ast.rs @@ -53,6 +53,8 @@ pub struct ScriptFnDef { /// Encapsulated running environment, if any. pub lib: Option>, /// 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, /// Access to external variables. + /// + /// Not available under `no_closure`. #[cfg(not(feature = "no_closure"))] pub externals: std::collections::BTreeSet, - /// 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, @@ -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, /// Embedded module resolver, if any. + /// + /// Not available under `no_module`. #[cfg(not(feature = "no_module"))] resolver: Option>, } @@ -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, Position), /// `import` expr `as` var + /// + /// Not available under `no_module`. #[cfg(not(feature = "no_module"))] Import(Expr, Option>, Position), /// `export` var `as` var `,` ... + /// + /// Not available under `no_module`. #[cfg(not(feature = "no_module"))] Export(Box<[(Ident, Option)]>, 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); @@ -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, Position), /// Character constant. diff --git a/src/dynamic.rs b/src/dynamic.rs index e1cb2568..3ec2b1d7 100644 --- a/src/dynamic.rs +++ b/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, Tag, AccessMode), - /// A fixed-precision decimal value. + /// _(DECIMAL)_ A fixed-precision decimal value. + /// Exported under the `decimal` feature only. #[cfg(feature = "decimal")] Decimal(Box, Tag, AccessMode), /// An array value. + /// + /// Not available under `no_index`. #[cfg(not(feature = "no_index"))] Array(Box, Tag, AccessMode), /// An object map value. + /// + /// Not available under `no_object`. #[cfg(not(feature = "no_object"))] Map(Box, Tag, AccessMode), /// A function pointer. FnPtr(Box, Tag, AccessMode), /// A timestamp value. + /// + /// Not available under `no-std`. #[cfg(not(feature = "no_std"))] TimeStamp(Box, Tag, AccessMode), @@ -185,14 +194,21 @@ pub enum Union { Variant(Box>, Tag, AccessMode), /// A _shared_ value of any type. + /// + /// Not available under `no_closure`. #[cfg(not(feature = "no_closure"))] Shared(crate::Shared>, 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 -/// normal [`Dynamic`] and shared [`Dynamic`] values. +/// This type provides transparent interoperability between normal [`Dynamic`] and shared +/// [`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 -/// normal [`Dynamic`] and shared [`Dynamic`] values. +/// This type provides transparent interoperability between normal [`Dynamic`] and shared +/// [`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 std::iter::FromIterator 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( diff --git a/src/engine_api.rs b/src/engine_api.rs index 006103f6..152a5338 100644 --- a/src/engine_api.rs +++ b/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 /// /// ``` diff --git a/src/fn_native.rs b/src/fn_native.rs index 48ae8077..5996d6db 100644 --- a/src/fn_native.rs +++ b/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 { @@ -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), /// A script-defined function. + /// + /// Not available under `no_function`. #[cfg(not(feature = "no_function"))] Script(Shared), } @@ -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]. diff --git a/src/fn_register.rs b/src/fn_register.rs index a4535ead..3e752f36 100644 --- a/src/fn_register.rs +++ b/src/fn_register.rs @@ -61,15 +61,15 @@ pub trait RegisterNativeFunction { 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; diff --git a/src/lib.rs b/src/lib.rs index 694af76a..30b9faa9 100644 --- a/src/lib.rs +++ b/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::{ - get_next_token, parse_string_literal, InputStream, Token, TokenizeState, TokenizerControl, - TokenizerControlBlock, -}; +pub use token::{InputStream, Token, TokenizeState, TokenizerControl, TokenizerControlBlock}; #[cfg(feature = "internals")] #[deprecated = "this type is volatile and may change"]