From deb752cbd1e93221aaf7a1a3a582cc9222f089fc Mon Sep 17 00:00:00 2001 From: nekevss Date: Mon, 1 May 2023 21:56:24 -0400 Subject: [PATCH 1/5] Update to primary docs to account for console update --- boa_engine/src/lib.rs | 9 +++++- boa_runtime/src/lib.rs | 63 +++++++++++++++++++++++++++++++++++++++--- 2 files changed, 67 insertions(+), 5 deletions(-) diff --git a/boa_engine/src/lib.rs b/boa_engine/src/lib.rs index 5ba437c63be..f81f46b34eb 100644 --- a/boa_engine/src/lib.rs +++ b/boa_engine/src/lib.rs @@ -9,6 +9,8 @@ //! //! Try out the most recent release with Boa's live demo [playground][boa-playground]. //! +//! For information related to Web API features, please see [`boa_runtime`] +//! //! # Example usage //! //! You can find multiple examples of the usage of Boa in the [`boa_examples`][examples] crate. In @@ -19,7 +21,12 @@ //! ``` //! use boa_engine::{Context, Source}; //! -//! let js_code = "console.log('Hello World from a JS code string!')"; +//! let js_code = r#" +//! let two = 1 + 1; +//! let definitely_not_four = two + "2"; +//! +//! definitely_not_four +//! "#; //! //! // Instantiate the execution context //! let mut context = Context::default(); diff --git a/boa_runtime/src/lib.rs b/boa_runtime/src/lib.rs index 965025d997c..e10be89243c 100644 --- a/boa_runtime/src/lib.rs +++ b/boa_runtime/src/lib.rs @@ -1,8 +1,63 @@ -//! Example runtime for Boa +//! Boa's **boa_runtime** crate contains an example runtime and basic runtime features and functionality for the `boa_engine` crate for +//! runtime implementors. //! -//! This crate contains an example runtime for the `boa_engine` crate, so that it can be used as a -//! template for runtime implementors. It contains some basic functionality that can be used by -//! other crates. +//! # About Boa +//! +//! Boa is an open-source, experimental ECMAScript Engine written in Rust for lexing, parsing and +//! executing ECMAScript/JavaScript. Currently, Boa supports some of the [language][boa-conformance]. +//! More information can be viewed at [Boa's website][boa-web]. +//! +//! Try out the most recent release with Boa's live demo [playground][boa-playground]. +//! +//! # Example: Adding Web API's Console Object +//! +//! 1. Add **boa_runtime** as a dependency to your project along with **boa_engine**. +//! +//! ``` +//! use boa-engine::{ Context, Source }; +//! use boa_runtime::Console; +//! +//! // Create the context. +//! let mut context = Context::default(); +//! +//! // Initialize the Console object. +//! let console = Console::init(context); +//! +//! // Register the console as a global property to the context. +//! context +//! .register_global_property(Console::NAME, console, Attribute::all) +//! .expect("the console object shouldn't exist yet") +//! +//! // Parse the source code +//! match context.eval_script(Source::from_bytes(js_code)) { +//! Ok(res) => { +//! println!( +//! "{}", +//! res.to_string(&mut context).unwrap().to_std_string_escaped() +//! ); +//! } +//! Err(e) => { +//! // Pretty print the error +//! eprintln!("Uncaught {e}"); +//! } +//! }; +//! +//! ``` +//! +//! # Boa Crates +//! - **`boa_ast`** - Boa's ECMAScript Abstract Syntax Tree. +//! - **`boa_engine`** - Boa's implementation of ECMAScript builtin objects and execution. +//! - **`boa_gc`** - Boa's garbage collector. +//! - **`boa_interner`** - Boa's string interner. +//! - **`boa_parser`** - Boa's lexer and parser. +//! - **`boa_profiler`** - Boa's code profiler. +//! - **`boa_unicode`** - Boa's Unicode identifier. +//! - **`boa_icu_provider`** - Boa's ICU4X data provider. +//! +//! [ecma-402]: https://tc39.es/ecma402 +//! [boa-conformance]: https://boajs.dev/boa/test262/ +//! [boa-web]: https://boajs.dev/ +//! [boa-playground]: https://boajs.dev/boa/playground/ #![doc( html_logo_url = "https://raw.githubusercontent.com/boa-dev/boa/main/assets/logo.svg", From c68061c19bc5c45d12498350dd68a5f697ba394d Mon Sep 17 00:00:00 2001 From: nekevss Date: Mon, 1 May 2023 22:10:25 -0400 Subject: [PATCH 2/5] fix intra-doc link --- boa_engine/src/lib.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/boa_engine/src/lib.rs b/boa_engine/src/lib.rs index f81f46b34eb..a93a0fb2b85 100644 --- a/boa_engine/src/lib.rs +++ b/boa_engine/src/lib.rs @@ -9,7 +9,7 @@ //! //! Try out the most recent release with Boa's live demo [playground][boa-playground]. //! -//! For information related to Web API features, please see [`boa_runtime`] +//! For information related to Web API features, please see [boa_runtime](runtime-docs) //! //! # Example usage //! @@ -66,6 +66,7 @@ //! [boa-conformance]: https://boajs.dev/boa/test262/ //! [boa-web]: https://boajs.dev/ //! [boa-playground]: https://boajs.dev/boa/playground/ +//! [runtime-docs]: https://boajs.dev/boa/doc/boa_runtime/index.html //! [examples]: https://github.com/boa-dev/boa/tree/main/boa_examples #![doc( From 48f3be5c7886b22ef92afdd8348f567e73d4c5f4 Mon Sep 17 00:00:00 2001 From: nekevss Date: Mon, 1 May 2023 22:11:04 -0400 Subject: [PATCH 3/5] Forgot a period --- boa_engine/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/boa_engine/src/lib.rs b/boa_engine/src/lib.rs index a93a0fb2b85..7af602631df 100644 --- a/boa_engine/src/lib.rs +++ b/boa_engine/src/lib.rs @@ -9,7 +9,7 @@ //! //! Try out the most recent release with Boa's live demo [playground][boa-playground]. //! -//! For information related to Web API features, please see [boa_runtime](runtime-docs) +//! For information related to Web API features, please see [boa_runtime](runtime-docs). //! //! # Example usage //! From 1de8341c1a6a36a277a510766e82cfdb332730e4 Mon Sep 17 00:00:00 2001 From: nekevss Date: Mon, 1 May 2023 22:30:03 -0400 Subject: [PATCH 4/5] Fixing the errors on runtime docs --- boa_runtime/src/lib.rs | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/boa_runtime/src/lib.rs b/boa_runtime/src/lib.rs index e10be89243c..e486b87d279 100644 --- a/boa_runtime/src/lib.rs +++ b/boa_runtime/src/lib.rs @@ -14,19 +14,22 @@ //! 1. Add **boa_runtime** as a dependency to your project along with **boa_engine**. //! //! ``` -//! use boa-engine::{ Context, Source }; +//! use boa_engine::{ Context, Source, property::Attribute }; //! use boa_runtime::Console; //! //! // Create the context. //! let mut context = Context::default(); //! //! // Initialize the Console object. -//! let console = Console::init(context); +//! let console = Console::init(&mut context); //! //! // Register the console as a global property to the context. //! context -//! .register_global_property(Console::NAME, console, Attribute::all) -//! .expect("the console object shouldn't exist yet") +//! .register_global_property(Console::NAME, console, Attribute::all()) +//! .expect("the console object shouldn't exist yet"); +//! +//! // JavaScript source for parsing. +//! let js_code = "console.log('Hello World from a JS code string!')"; //! //! // Parse the source code //! match context.eval_script(Source::from_bytes(js_code)) { From caa82364cef9a8bee23fdc9838b664baa7d6c024 Mon Sep 17 00:00:00 2001 From: nekevss Date: Wed, 3 May 2023 18:53:29 -0400 Subject: [PATCH 5/5] Add hidden panic to example --- boa_engine/src/lib.rs | 1 + boa_runtime/src/lib.rs | 21 +++++++++++---------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/boa_engine/src/lib.rs b/boa_engine/src/lib.rs index 7af602631df..8b37dc5aaa2 100644 --- a/boa_engine/src/lib.rs +++ b/boa_engine/src/lib.rs @@ -42,6 +42,7 @@ //! Err(e) => { //! // Pretty print the error //! eprintln!("Uncaught {e}"); +//! # panic!("There was an error in boa_engine's introduction example."); //! } //! }; //! ``` diff --git a/boa_runtime/src/lib.rs b/boa_runtime/src/lib.rs index e486b87d279..107f803794b 100644 --- a/boa_runtime/src/lib.rs +++ b/boa_runtime/src/lib.rs @@ -33,16 +33,17 @@ //! //! // Parse the source code //! match context.eval_script(Source::from_bytes(js_code)) { -//! Ok(res) => { -//! println!( -//! "{}", -//! res.to_string(&mut context).unwrap().to_std_string_escaped() -//! ); -//! } -//! Err(e) => { -//! // Pretty print the error -//! eprintln!("Uncaught {e}"); -//! } +//! Ok(res) => { +//! println!( +//! "{}", +//! res.to_string(&mut context).unwrap().to_std_string_escaped() +//! ); +//! } +//! Err(e) => { +//! // Pretty print the error +//! eprintln!("Uncaught {e}"); +//! # panic!("An error occured in boa_runtime's js_code"); +//! } //! }; //! //! ```