From 8877be4a67a64aa843aaabfdbc5745f98b129adf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Cabrera?= Date: Tue, 7 May 2024 09:26:00 -0400 Subject: [PATCH] docs: Improve READMEs for `apis` and `javy` crates (#640) * docs: Slight improvement to `javy-apis` In preparation to adding more APIs I decided to do a very light cleanup of some of the documentation in this crate. I opted to remove the documentation in the README to reduce the overhead of having to maintain the same documentation in multiple places. * Review comments * Bring example to README and fix error Brings the APIs example to the README and fixes a dangling statement. * Use the right example * Standardize the READMEs even more Adds crates.io and docs.rs badges and updates the `javy` crate with similar updates. Includes a link to the documentation to ensure that there's a direct navigation from the README to the crate-level docs. --- crates/apis/README.md | 31 +++++++++++----------- crates/apis/src/lib.rs | 60 ++++++++++++++++++++---------------------- crates/javy/README.md | 24 +++++++++-------- 3 files changed, 57 insertions(+), 58 deletions(-) diff --git a/crates/apis/README.md b/crates/apis/README.md index cc492007..8718cc5e 100644 --- a/crates/apis/README.md +++ b/crates/apis/README.md @@ -1,13 +1,20 @@ -# javy-apis - -A collection of APIs that can be added to a Javy runtime. - -APIs are registered by enabling crate features. - -## Example usage +
+

Javy APIs

+

+ A collection of APIs for Javy +

+ +

+ Documentation Status + crates.io status +

+
+ +Refer to the [crate level documentation](https://docs.rs/javy-apis) to learn more. + +Example usage: ```rust - // With the `console` feature enabled. use javy::{Runtime, from_js_error}; use javy_apis::RuntimeExt; @@ -24,14 +31,6 @@ fn main() -> Result<()> { } ``` -If you want to customize the runtime or the APIs, you can use the `Runtime::new_with_apis` method instead to provide a `javy::Config` for the underlying `Runtime` or an `APIConfig` for the APIs. - -## Features -* `console` - Registers an implementation of the `console` API. -* `text_encoding` - Registers implementations of `TextEncoder` and `TextDecoder`. -* `random` - Overrides the implementation of `Math.random` to one that seeds the RNG on first call to `Math.random`. This is helpful to enable when using Wizer to snapshot a Javy Runtime so that the output of `Math.random` relies on the WASI context used at runtime and not the WASI context used when Wizening. Enabling this feature will increase the size of the Wasm module that includes the Javy Runtime and will introduce an additional hostcall invocation when `Math.random` is invoked for the first time. -* `stream_io` - Registers implementations of `Javy.IO.readSync` and `Javy.IO.writeSync`. - ## Publishing to crates.io To publish this crate to crates.io, run `./publish.sh`. diff --git a/crates/apis/src/lib.rs b/crates/apis/src/lib.rs index e433f6bf..d9b30ce1 100644 --- a/crates/apis/src/lib.rs +++ b/crates/apis/src/lib.rs @@ -1,28 +1,25 @@ -//! JS APIs for Javy. +//! A collection of APIs for Javy. //! -//! This crate provides JS APIs you can add to Javy. +//! APIs are enabled through cargo features. //! //! Example usage: -//! ``` -//! # use anyhow::{anyhow, Error, Result}; -//! use javy::{quickjs::JSValue, Runtime}; +//! ```rust +//! +//! //With the `console` feature enabled. +//! use javy::{Runtime, from_js_error}; //! use javy_apis::RuntimeExt; +//! use anyhow::Result; +//! +//! fn main() -> Result<()> { +//! let runtime = Runtime::new_with_defaults()?; +//! let context = runtime.context(); +//! context.with(|cx| { +//! cx.eval_with_options(Default::default(), "console.log('hello!');") +//! .map_err(|e| to_js_error(cx.clone(), e))? +//! }); +//! Ok(()) +//! } //! -//! let runtime = Runtime::new_with_defaults()?; -//! let context = runtime.context(); -//! context.global_object()?.set_property( -//! "print", -//! context.wrap_callback(move |_ctx, _this, args| { -//! let str = args -//! .first() -//! .ok_or(anyhow!("Need to pass an argument"))? -//! .to_string(); -//! println!("{str}"); -//! Ok(JSValue::Undefined) -//! })?, -//! )?; -//! context.eval_global("hello.js", "print('hello!');")?; -//! # Ok::<(), Error>(()) //! ``` //! //! If you want to customize the runtime or the APIs, you can use the @@ -30,17 +27,18 @@ //! for the underlying [`Runtime`] or an [`APIConfig`] for the APIs. //! //! ## Features -//! * `console` - Registers an implementation of the `console` API. -//! * `text_encoding` - Registers implementations of `TextEncoder` and `TextDecoder`. -//! * `random` - Overrides the implementation of `Math.random` to one that -//! seeds the RNG on first call to `Math.random`. This is helpful to enable -//! when using Wizer to snapshot a [`javy::Runtime`] so that the output of -//! `Math.random` relies on the WASI context used at runtime and not the -//! WASI context used when Wizening. Enabling this feature will increase the -//! size of the Wasm module that includes the Javy Runtime and will -//! introduce an additional hostcall invocation when `Math.random` is -//! invoked for the first time. -//! * `stream_io` - Registers implementations of `Javy.IO.readSync` and `Javy.IO.writeSync`. +//! * `console`: Adds an implementation of the `console.log` and `console.error`, +//! enabling the configuration of the standard streams. +//! * `text_encoding`: Registers implementations of `TextEncoder` and `TextDecoder`. +//! * `random`: Overrides the implementation of `Math.random` to one that seeds +//! the RNG on first call to `Math.random`. This is helpful to enable when using +//! using a tool like Wizer to snapshot a [`Runtime`] so that the output of +//! `Math.random` relies on the WASI context used at runtime and not the WASI +//! context used when Wizening. Enabling this feature will increase the size of +//! the Wasm module that includes the Javy Runtime and will introduce an +//! additional hostcall invocation when `Math.random` is invoked for the first +//! time. +//! * `stream_io`: Adds an implementation of `Javy.IO.readSync` and `Javy.IO.writeSync`. use anyhow::Result; use javy::Runtime; diff --git a/crates/javy/README.md b/crates/javy/README.md index 43ad13b5..51e2676b 100644 --- a/crates/javy/README.md +++ b/crates/javy/README.md @@ -1,11 +1,21 @@ -# javy +
+

Javy

+

+ A configurable JavaScript runtime for WebAssembly +

+

+ Documentation Status + crates.io status +

+
-A configurable JavaScript runtime for WebAssembly. Uses QuickJS through the [`rquickjs`](https://docs.rs/rquickjs/latest/rquickjs/) crate to evalulate JavaScript source code or QuickJS bytecode. -## Example usage +Refer to the [crate level documentation](https://docs.rs/javy) to learn more. + +Example usage: ```rust use anyhow::anyhow; @@ -33,14 +43,6 @@ context.with(|cx| { }); ``` -Create a `Runtime` and use the reference returned by `context()` to add functions and evaluate source code. - -## Features - -- `export_alloc_fns` - exports `canonical_abi_realloc` and `canonical_abi_free` from generated WebAssembly for allocating and freeing memory -- `json` - transcoding functions for converting between `JSValueRef` and JSON -- `messagepack` - transcoding functions for converting between `JSValueRef` and MessagePack - ## Publishing to crates.io To publish this crate to crates.io, run `./publish.sh`.