docs

Author: rscarson

Cargo.toml

@@ -11,6 +11,9 @@ keywords = ["rust", "javascript", "deno", "runtime", "embedding"]
 categories = ["web-programming", "network-programming", "api-bindings", "compilers", "development-tools::ffi"]
 readme = "readme.md"
 
+[package.metadata.docs.rs]
+all-features = true
+
 [features]
 default = ["worker", "safe_extensions"]
 
@@ -241,9 +244,6 @@ checksum      = { version = "0.2.1", optional = true }
 version-sync = "0.9.5"
 criterion = "0.5.1"
 
-[package.metadata.docs.rs]
-all-features = true
-
 [[example]]
 name = "custom_threaded_worker"
 required-features = ["worker"]

examples/thread_safety.rs

@@ -6,9 +6,15 @@
 /// See `examples/default_threaded_worker` and `examples/custom_threaded_worker`
 /// for a more flexible way to run rustyscript in a threaded environment
 ///
-use rustyscript::{module, static_runtime, Error, StaticModule};
+use rustyscript::{module, static_runtime, Error, RuntimeOptions, StaticModule};
+use std::time::Duration;
 
-static_runtime!(RUNTIME);
+static_runtime!(RUNTIME, {
+    RuntimeOptions {
+        timeout: Duration::from_secs(5),
+        ..Default::default()
+    }
+});
 
 // Modules can be defined statically using this macro!
 static MY_MODULE: StaticModule = module!(

src/ext/mod.rs

@@ -88,41 +88,59 @@ pub mod runtime;
 /// Options for configuring extensions
 pub struct ExtensionOptions {
     /// Options specific to the `deno_web`, `deno_fetch` and `deno_net` extensions
+    ///
+    /// Requires the `web` feature to be enabled
     #[cfg(feature = "web")]
     pub web: web::WebOptions,
 
     /// Optional seed for the `deno_crypto` extension
+    ///
+    /// Requires the `crypto` feature to be enabled
     #[cfg(feature = "crypto")]
     pub crypto_seed: Option<u64>,
 
     /// Configures the stdin/out/err pipes for the `deno_io` extension
+    ///
+    /// Requires the `io` feature to be enabled
     #[cfg(feature = "io")]
     pub io_pipes: Option<deno_io::Stdio>,
 
     /// Optional path to the directory where the webstorage extension will store its data
+    ///
+    /// Requires the `webstorage` feature to be enabled
     #[cfg(feature = "webstorage")]
     pub webstorage_origin_storage_dir: Option<std::path::PathBuf>,
 
     /// Optional cache configuration for the `deno_cache` extension
+    ///
+    /// Requires the `cache` feature to be enabled
     #[cfg(feature = "cache")]
     pub cache: Option<deno_cache::CreateCache<cache::CacheBackend>>,
 
     /// Filesystem implementation for the `deno_fs` extension
+    ///
+    /// Requires the `fs` feature to be enabled
     #[cfg(feature = "fs")]
     pub filesystem: deno_fs::FileSystemRc,
 
     /// Shared in-memory broadcast channel for the `deno_broadcast_channel` extension
     /// Also used by `WebWorker` to communicate with the main thread, if node is enabled
+    ///
+    /// Requires the `broadcast_channel` feature to be enabled
     #[cfg(feature = "broadcast_channel")]
     pub broadcast_channel: deno_broadcast_channel::InMemoryBroadcastChannel,
 
     /// Key-value store for the `deno_kv` extension
+    ///
+    /// Requires the `kv` feature to be enabled
     #[cfg(feature = "kv")]
     pub kv_store: kv::KvStore,
 
     /// Package resolver for the `deno_node` extension
     /// `RustyResolver` allows you to select the base dir for modules
     /// as well as the filesystem implementation to use
+    ///
+    /// Requires the `node_experimental` feature to be enabled
     #[cfg(feature = "node_experimental")]
     pub node_resolver: std::sync::Arc<node::RustyResolver>,
 }

src/snapshot_builder.rs

@@ -96,7 +96,7 @@ impl SnapshotBuilder {
     }
 
     /// Creates a new instance of the runtime with the provided options and a pre-configured tokio runtime.
-    /// See [`Runtime::new`] for more information.
+    /// See [`crate::Runtime::new`] for more information.
     ///
     /// # Errors
     /// Can fail if the deno runtime initialization fails (usually issues with extensions)
@@ -161,7 +161,7 @@ impl SnapshotBuilder {
     }
 
     /// Advance the JS event loop by a single tick
-    /// See [`Runtime::await_event_loop`] for fully running the event loop
+    /// See [`crate::Runtime::await_event_loop`] for fully running the event loop
     ///
     /// Returns true if the event loop has pending work, or false if it has completed
     ///
@@ -194,7 +194,7 @@ impl SnapshotBuilder {
     /// Run the JS event loop to completion, or until a timeout is reached
     /// Required when using the `_immediate` variants of functions
     ///
-    /// This is the blocking variant of [`Runtime::await_event_loop`]
+    /// This is the blocking variant of [`crate::Runtime::await_event_loop`]
     ///
     /// # Arguments
     /// * `options` - Options for the event loop polling, see [`deno_core::PollEventLoopOptions`]
@@ -307,7 +307,7 @@ impl SnapshotBuilder {
     ///
     /// Note that synchronous functions are run synchronously. Returned promises will be run asynchronously, however.
     ///
-    /// See [`Runtime::call_function`] for an example
+    /// See [`crate::Runtime::call_function`] for an example
     ///
     /// # Arguments
     /// * `module_context` - Optional handle to a module to search - if None, or if the search fails, the global context is used
@@ -390,7 +390,7 @@ impl SnapshotBuilder {
     /// Calls a javascript function within the Deno runtime by its name and deserializes its return value.
     /// Will not attempt to resolve promises, or run the event loop
     /// Promises can be returned by specifying the return type as [`crate::js_value::Promise`]
-    /// The event loop should be run using [`Runtime::await_event_loop`]
+    /// The event loop should be run using [`crate::Runtime::await_event_loop`]
     ///
     /// # Arguments
     /// * `module_context` - Optional handle to a module to search - if None, or if the search fails, the global context is used
@@ -480,7 +480,7 @@ impl SnapshotBuilder {
     /// - The event loop is resolved, and
     /// - If the value is a promise, the promise is resolved
     ///
-    /// See [`Runtime::get_value`] for an example
+    /// See [`crate::Runtime::get_value`] for an example
     ///
     /// # Arguments
     /// * `module_context` - Optional handle to a module to search - if None, or if the search fails, the global context is used
@@ -508,7 +508,7 @@ impl SnapshotBuilder {
     /// Get a value from a runtime instance
     /// Will not attempt to resolve promises, or run the event loop
     /// Promises can be returned by specifying the return type as [`crate::js_value::Promise`]
-    /// The event loop should be run using [`Runtime::await_event_loop`]
+    /// The event loop should be run using [`crate::Runtime::await_event_loop`]
     ///
     /// # Arguments
     /// * `module_context` - Optional handle to a module to search - if None, or if the search fails, the global context is used
@@ -550,7 +550,7 @@ impl SnapshotBuilder {
     /// And call functions
     ///
     /// Blocks until the module has been executed AND the event loop has fully resolved
-    /// See [`Runtime::load_module_async`] for a non-blocking variant, or use with async
+    /// See [`crate::Runtime::load_module_async`] for a non-blocking variant, or use with async
     /// background tasks
     ///
     /// # Arguments
@@ -590,7 +590,7 @@ impl SnapshotBuilder {
     /// And call functions
     ///
     /// Returns a future that resolves to the handle for the loaded module
-    /// Makes no attempt to fully resolve the event loop - call [`Runtime::await_event_loop`]
+    /// Makes no attempt to fully resolve the event loop - call [`crate::Runtime::await_event_loop`]
     /// to resolve background tasks and async listeners
     ///
     /// # Arguments
@@ -603,7 +603,7 @@ impl SnapshotBuilder {
     /// # Errors
     /// Can fail if the module cannot be loaded, or execution fails
     ///
-    /// See [`Runtime::load_module`] for an example
+    /// See [`crate::Runtime::load_module`] for an example
     pub async fn load_module_async(&mut self, module: &Module) -> Result<ModuleHandle, Error> {
         self.inner.load_modules(None, vec![module]).await
     }
@@ -612,7 +612,7 @@ impl SnapshotBuilder {
     /// And call functions.
     ///
     /// Blocks until all modules have been executed AND the event loop has fully resolved
-    /// See [`Runtime::load_module_async`] for a non-blocking variant, or use with async
+    /// See [`crate::Runtime::load_module_async`] for a non-blocking variant, or use with async
     /// background tasks
     ///
     /// This will load 'module' as the main module, and the others as side-modules.
@@ -660,13 +660,13 @@ impl SnapshotBuilder {
     /// And call functions.
     ///
     /// Returns a future that resolves to the handle for the loaded module
-    /// Makes no attempt to resolve the event loop - call [`Runtime::await_event_loop`] to
+    /// Makes no attempt to resolve the event loop - call [`crate::Runtime::await_event_loop`] to
     /// resolve background tasks and async listeners
     ///
     /// This will load 'module' as the main module, and the others as side-modules.
     /// Only one main module can be loaded per runtime
     ///
-    /// See [`Runtime::load_modules`] for an example
+    /// See [`crate::Runtime::load_modules`] for an example
     ///
     /// # Arguments
     /// * `module` - A `Module` object containing the module's filename and contents.

src/static_runtime.rs

@@ -32,6 +32,7 @@
 //!         runtime.eval::<()>("console.log('Hello, world!')")
 //!     })
 //! }
+//! ```
 use crate::{Error, Runtime, RuntimeOptions};
 use std::cell::{OnceCell, RefCell, RefMut};
 
@@ -90,6 +91,7 @@ impl<'a> StaticRuntimeLock<'a> {
 ///         runtime.eval::<()>("console.log('Hello, world!')")
 ///     })
 /// }
+/// ```
 pub struct StaticRuntime {
     init_options: fn() -> RuntimeOptions,
     cell: OnceCell<RefCell<Result<Runtime, Error>>>,
@@ -158,23 +160,9 @@ impl StaticRuntime {
 /// The first argument is the name of the static runtime
 /// The second argument is an optional block that should return a `RuntimeOptions` instance
 ///
-/// # Example
-/// ```rust
-/// use rustyscript::{static_runtime, RuntimeOptions};
-/// use std::time::Duration;
-///
-/// static_runtime!(MY_DEFAULT_RUNTIME);
-///
-/// static_runtime!(MY_CUSTOM_RUNTIME, {
-///     RuntimeOptions {
-///         timeout: Duration::from_secs(5),
-///         ..Default::default()
-///     }
-/// });
-/// ```
+/// See [`crate::static_runtime`] for an example
 ///
-/// The resulting runtime can be accessed using `with`, following by either `lock` or `with_runtime`  
-/// See [`static_runtime::StaticRuntime`] for more information
+/// The resulting runtime can be accessed using `with`, which accepts a closure that takes a mutable reference to the runtime
 #[macro_export]
 macro_rules! static_runtime {
     ($name:ident, $options:block) => {
@@ -190,6 +178,8 @@ macro_rules! static_runtime {
                     = const { $crate::static_runtime::StaticRuntime::new(|| $options) };
             }
 
+            /// Perform an operation on the runtime instance
+            #[allow(dead_code)]
             pub fn with<T, F>(callback: F) -> Result<T, $crate::Error>
             where
                 F: FnMut(&mut $crate::Runtime) -> Result<T, $crate::Error>,