From e320c55d214d26759f0757e4e570ed543b9c2594 Mon Sep 17 00:00:00 2001
From: Kevin <46825870+nekevss@users.noreply.github.com>
Date: Thu, 4 May 2023 06:07:47 -0400
Subject: [PATCH] Docs update for boa_runtime and console documentation (#2891)

* Update to primary docs to account for console update

* fix intra-doc link

* Forgot a period

* Fixing the errors on runtime docs

* Add hidden panic to example
---
 boa_engine/src/lib.rs  | 11 ++++++-
 boa_runtime/src/lib.rs | 67 +++++++++++++++++++++++++++++++++++++++---
 2 files changed, 73 insertions(+), 5 deletions(-)

diff --git a/boa_engine/src/lib.rs b/boa_engine/src/lib.rs
index 5ba437c63b..8b37dc5aaa 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](runtime-docs).
+//!
 //! # 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();
@@ -35,6 +42,7 @@
 //!     Err(e) => {
 //!         // Pretty print the error
 //!         eprintln!("Uncaught {e}");
+//!         # panic!("There was an error in boa_engine's introduction example.");
 //!     }
 //! };
 //! ```
@@ -59,6 +67,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(
diff --git a/boa_runtime/src/lib.rs b/boa_runtime/src/lib.rs
index 965025d997..107f803794 100644
--- a/boa_runtime/src/lib.rs
+++ b/boa_runtime/src/lib.rs
@@ -1,8 +1,67 @@
-//! 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, property::Attribute };
+//! use boa_runtime::Console;
+//!
+//! // Create the context.
+//! let mut context = Context::default();
+//!
+//! // Initialize the Console object.
+//! 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");
+//!
+//! // 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)) {
+//!     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");
+//!     }
+//! };
+//!
+//! ```
+//!
+//! # 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",