[Merged by Bors] - Documentation Updates

boa_ast/src/declaration/mod.rs

@@ -1,6 +1,6 @@
 //! The [`Declaration`] Parse Node, as defined by the [spec].
 //!
-//! Javascript declarations include:
+//! ECMAScript declarations include:
 //! - [Lexical][lex] declarations (`let`, `const`).
 //! - [Function][fun] declarations (`function`, `async function`).
 //! - [Class][class] declarations.

boa_ast/src/declaration/variable.rs

@@ -19,7 +19,7 @@ use super::Declaration;
 ///
 /// The scope of a variable declared with `var` is its current execution context, which is either
 /// the enclosing function or, for variables declared outside any function, global. If you
-/// re-declare a JavaScript variable, it will not lose its value.
+/// re-declare a ECMAScript variable, it will not lose its value.
 ///
 /// Although a bit confusing, `VarDeclaration`s are not considered [`Declaration`]s by the spec.
 /// This is partly because it has very different semantics from `let` and `const` declarations, but

boa_ast/src/expression/identifier.rs

@@ -25,7 +25,7 @@ pub const RESERVED_IDENTIFIERS_STRICT: [Sym; 9] = [
 /// An `identifier` is a sequence of characters in the code that identifies a variable,
 /// function, or property.
 ///
-/// In JavaScript, identifiers are case-sensitive and can contain Unicode letters, $, _, and
+/// In ECMAScript, identifiers are case-sensitive and can contain Unicode letters, $, _, and
 /// digits (0-9), but may not start with a digit.
 ///
 /// An identifier differs from a string in that a string is data, while an identifier is part

boa_ast/src/expression/literal/mod.rs

@@ -1,4 +1,4 @@
-//! This module contains all literal expressions, which represents the primitive values in JavaScript.
+//! This module contains all literal expressions, which represents the primitive values in ECMAScript.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]
@@ -22,7 +22,7 @@ use num_bigint::BigInt;
 
 use super::Expression;
 
-/// Literals represent values in JavaScript.
+/// Literals represent values in ECMAScript.
 ///
 /// These are fixed values **not variables** that you literally provide in your script.
 ///
@@ -40,7 +40,7 @@ pub enum Literal {
     ///
     /// A string must be delimited by quotation marks of the same type (that is, either both single quotation marks, or both double quotation marks).
     /// You can call any of the String object's methods on a string literal value.
-    /// JavaScript automatically converts the string literal to a temporary String object,
+    /// ECMAScript automatically converts the string literal to a temporary String object,
     /// calls the method, then discards the temporary String object.
     ///
     /// More information:
@@ -74,7 +74,7 @@ pub enum Literal {
     /// [mdn]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#Numeric_literals
     Int(i32),
 
-    /// BigInt provides a way to represent whole numbers larger than the largest number JavaScript
+    /// BigInt provides a way to represent whole numbers larger than the largest number ECMAScript
     /// can reliably represent with the `Number` primitive.
     ///
     /// More information:

boa_ast/src/expression/literal/object.rs

@@ -13,7 +13,7 @@ use crate::{
 use boa_interner::{Interner, Sym, ToIndentedString, ToInternedString};
 use core::ops::ControlFlow;
 
-/// Objects in JavaScript may be defined as an unordered collection of related data, of
+/// Objects in ECMAScript may be defined as an unordered collection of related data, of
 /// primitive or reference types, in the form of “key: value” pairs.
 ///
 /// Objects can be initialized using `new Object()`, `Object.create()`, or using the literal

boa_ast/src/expression/mod.rs

@@ -1,6 +1,6 @@
 //! The [`Expression`] Parse Node, as defined by the [spec].
 //!
-//! Javascript expressions include:
+//! ECMAScript expressions include:
 //! - [Primary][primary] expressions (`this`, function expressions, literals).
 //! - [Left hand side][lhs] expressions (accessors, `new` operator, `super`).
 //! - [operator] expressions.
@@ -54,7 +54,7 @@ pub mod operator;
 #[cfg_attr(feature = "fuzz", derive(arbitrary::Arbitrary))]
 #[derive(Debug, Clone, PartialEq)]
 pub enum Expression {
-    /// The JavaScript `this` keyword refers to the object it belongs to.
+    /// The ECMAScript `this` keyword refers to the object it belongs to.
     ///
     /// A property of an execution context (global, function or eval) that,
     /// in non–strict mode, is always a reference to an object and in strict

boa_ast/src/expression/operator/conditional.rs

@@ -6,7 +6,7 @@ use crate::{
 use boa_interner::{Interner, ToInternedString};
 use core::ops::ControlFlow;
 
-/// The `conditional` (ternary) operation is the only JavaScript operation that takes three
+/// The `conditional` (ternary) operation is the only ECMAScript operation that takes three
 /// operands.
 ///
 /// This operation takes three operands: a condition followed by a question mark (`?`),

boa_ast/src/keyword.rs

@@ -1,7 +1,7 @@
-//! The `Keyword` AST node, which represents reserved words of the JavaScript language.
+//! The `Keyword` AST node, which represents reserved words of the ECMAScript language.
 //!
 //! The [specification][spec] defines keywords as tokens that match an `IdentifierName`, but also
-//! have special meaning in JavaScript. In JavaScript you cannot use these reserved words as variables,
+//! have special meaning in ECMAScript. In ECMAScript, you cannot use these reserved words as variables,
 //! labels, or function names.
 //!
 //! The [MDN documentation][mdn] contains a more extensive explanation about keywords.

boa_ast/src/lib.rs

@@ -1,16 +1,40 @@
-//! The Javascript Abstract Syntax Tree.
+//! Boa's **boa_ast** crate implements an ECMAScript abstract syntax tree.
 //!
-//! This crate contains representations of [**Parse Nodes**][grammar] as defined by the ECMAScript spec.
-//! Some `Parse Node`s are not represented by Boa's AST, because a lot of grammar productions are
-//! only used to throw [**Early Errors**][early], and don't influence the evaluation of the AST itself.
+//! # Crate Overview
+//! **boa_ast** contains representations of [**Parse Nodes**][grammar] as defined by the ECMAScript
+//! spec. Some `Parse Node`s are not represented by Boa's AST, because a lot of grammar productions
+//! are only used to throw [**Early Errors**][early], and don't influence the evaluation of the AST
+//! itself.
 //!
 //! Boa's AST is mainly split in three main components: [`Declaration`]s, [`Expression`]s and
 //! [`Statement`]s, with [`StatementList`] being the primordial Parse Node that combines
 //! all of them to create a proper AST.
 //!
+//! # 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].  
+//!
+//! # 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
+//!
 //! [grammar]: https://tc39.es/ecma262/#sec-syntactic-grammar
 //! [early]: https://tc39.es/ecma262/#sec-static-semantic-rules
+//! [boa-conformance]: https://boa-dev.github.io/boa/test262/
+//! [boa-web]: https://boa-dev.github.io/
+//! [boa-playground]: https://boa-dev.github.io/boa/playground/
 
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/boa-dev/boa/main/assets/logo.svg",
+    html_favicon_url = "https://raw.githubusercontent.com/boa-dev/boa/main/assets/logo.svg"
+)]
 #![cfg_attr(not(test), forbid(clippy::unwrap_used))]
 #![warn(missing_docs, clippy::dbg_macro)]
 #![deny(

boa_ast/src/position.rs

@@ -1,6 +1,6 @@
 use std::{cmp::Ordering, fmt, num::NonZeroU32};
 
-/// A position in the JavaScript source code.
+/// A position in the ECMAScript source code.
 ///
 /// Stores both the column number and the line number.
 ///
@@ -48,7 +48,7 @@ impl fmt::Display for Position {
     }
 }
 
-/// A span in the JavaScript source code.
+/// A span in the ECMAScript source code.
 ///
 /// Stores a start position and an end position.
 ///

boa_ast/src/punctuator.rs

@@ -1,4 +1,4 @@
-//! The `Punctuator` enum, which contains all punctuators used in JavaScript.
+//! The `Punctuator` enum, which contains all punctuators used in ECMAScript.
 //!
 //! More information:
 //!  - [ECMAScript Reference][spec]
@@ -14,7 +14,7 @@ use std::{
     fmt::{Display, Error, Formatter},
 };
 
-/// All of the punctuators used in JavaScript.
+/// All of the punctuators used in ECMAScript.
 ///
 /// More information:
 ///  - [ECMAScript Reference][spec]

boa_ast/src/statement/block.rs

@@ -11,8 +11,8 @@ use core::ops::ControlFlow;
 /// more statements.
 ///
 /// The block statement is often called compound statement in other languages.
-/// It allows you to use multiple statements where JavaScript expects only one statement.
-/// Combining statements into blocks is a common practice in JavaScript. The opposite behavior
+/// It allows you to use multiple statements where ECMAScript expects only one statement.
+/// Combining statements into blocks is a common practice in ECMAScript. The opposite behavior
 /// is possible using an empty statement, where you provide no statement, although one is
 /// required.
 ///

boa_ast/src/statement/mod.rs

@@ -1,6 +1,6 @@
 //! The [`Statement`] Parse Node, as defined by the [spec].
 //!
-//! Javascript [statements] are mainly composed of control flow operations, such as [`If`],
+//! ECMAScript [statements] are mainly composed of control flow operations, such as [`If`],
 //! [`WhileLoop`], and [`Break`]. However, it also contains statements such as [`VarDeclaration`],
 //! [`Block`] or [`Expression`] which are not strictly used for control flow.
 //!

boa_ast/src/visitor.rs

@@ -1,4 +1,4 @@
-//! Javascript Abstract Syntax Tree visitors.
+//! ECMAScript Abstract Syntax Tree visitors.
 //!
 //! This module contains visitors which can be used to inspect or modify AST nodes. This allows for
 //! fine-grained manipulation of ASTs for analysis, rewriting, or instrumentation.

boa_engine/src/bigint.rs

@@ -1,4 +1,4 @@
-//! This module implements the JavaScript bigint primitive rust type.
+//! Boa's implementation of ECMAScript's bigint primitive type.
 
 use crate::{builtins::Number, error::JsNativeError, JsResult};
 use num_integer::Integer;

boa_engine/src/builtins/array/mod.rs

@@ -1,6 +1,6 @@
-//! This module implements the global `Array` object.
+//! Boa's implementation of ECMAScript's global `Array` object.
 //!
-//! The JavaScript `Array` class is a global object that is used in the construction of arrays; which are high-level, list-like objects.
+//! The ECMAScript `Array` class is a global object that is used in the construction of arrays; which are high-level, list-like objects.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]

boa_engine/src/builtins/array_buffer/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `ArrayBuffer` object.
+//! Boa's implementation of ECMAScript's global `ArrayBuffer` object.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]

boa_engine/src/builtins/async_function/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `AsyncFunction` object.
+//! Boa's implementation of ECMAScript's global `AsyncFunction` object.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]

boa_engine/src/builtins/async_generator/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `AsyncGenerator` object.
+//! Boa's implementation of ECMAScript's global `AsyncGenerator` object.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]

boa_engine/src/builtins/async_generator_function/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the `AsyncGeneratorFunction` object.
+//! Boa's implementation of ECMAScript's `AsyncGeneratorFunction` object.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]

boa_engine/src/builtins/bigint/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `BigInt` object.
+//! Boa's implementation of ECMAScript's global `BigInt` object.
 //!
 //! `BigInt` is a built-in object that provides a way to represent whole numbers larger
 //! than the largest number JavaScript can reliably represent with the Number primitive

boa_engine/src/builtins/boolean/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `Boolean` object.
+//! Boa's implementation of ECMAScript's global `Boolean` object.
 //!
 //! The `Boolean` object is an object wrapper for a boolean value.
 //!

boa_engine/src/builtins/console/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `console` object.
+//! Boa's implementation of JavaScript's `console` Web API object.
 //!
 //! The `console` object can be accessed from any global object.
 //!

boa_engine/src/builtins/dataview/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `DataView` object.
+//! Boa's implementation of ECMAScript's global `DataView` object.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]

boa_engine/src/builtins/date/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `Date` object.
+//! Boa's implementation of ECMAScript's `Date` object.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]

boa_engine/src/builtins/error/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `Error` object.
+//! Boa's implementation of ECMAScript's global `Error` object.
 //!
 //! Error objects are thrown when runtime errors occur.
 //! The Error object can also be used as a base object for user-defined exceptions.

boa_engine/src/builtins/eval/mod.rs

@@ -1,6 +1,6 @@
-//! This module implements the global `eval` function.
+//! Boa's implementation of ECMAScript's global `eval` function.
 //!
-//! The `eval()` function evaluates JavaScript code represented as a string.
+//! The `eval()` function evaluates ECMAScript code represented as a string.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]

boa_engine/src/builtins/function/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `Function` object as well as creates Native Functions.
+//! Boa's implementation of ECMAScript's global `Function` object and Native Functions.
 //!
 //! Objects wrap `Function`s and expose them via call/construct slots.
 //!

boa_engine/src/builtins/generator/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `Generator` object.
+//! Boa's implementation of ECMAScript's global `Generator` object.
 //!
 //! A Generator is an instance of a generator function and conforms to both the Iterator and Iterable interfaces.
 //!

boa_engine/src/builtins/generator_function/mod.rs

@@ -1,7 +1,7 @@
-//! This module implements the global `GeneratorFunction` object.
+//! Boa's implementation of ECMAScript's global `GeneratorFunction` object.
 //!
 //! The `GeneratorFunction` constructor creates a new generator function object.
-//! In JavaScript, every generator function is actually a `GeneratorFunction` object.
+//! In ECMAScript, every generator function is actually a `GeneratorFunction` object.
 //!
 //! More information:
 //!  - [ECMAScript reference][spec]

boa_engine/src/builtins/global_this/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `globalThis` property.
+//! Boa's implementation of ECMAScript's global `globalThis` property.
 //!
 //! The global globalThis property contains the global this value,
 //! which is akin to the global object.

boa_engine/src/builtins/infinity/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `Infinity` property.
+//! Boa's implementation of ECMAScript's global `Infinity` property.
 //!
 //! The global property `Infinity` is a numeric value representing infinity.
 //!

boa_engine/src/builtins/intl/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `Intl` object.
+//! Boa's implementation of ECMAScript's global `Intl` object.
 //!
 //! `Intl` is a built-in object that has properties and methods for i18n. It's not a function object.
 //!

boa_engine/src/builtins/iterable/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global iterator prototype objects.
+//! Boa's implementation of ECMAScript's `IteratorRecord` and iterator prototype objects.
 
 mod async_from_sync_iterator;
 

boa_engine/src/builtins/json/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `JSON` object.
+//! Boa's implementation of ECMAScript's global `JSON` object.
 //!
 //! The `JSON` object contains methods for parsing [JavaScript Object Notation (JSON)][spec]
 //! and converting values to JSON. It can't be called or constructed, and aside from its

boa_engine/src/builtins/map/mod.rs

@@ -1,6 +1,6 @@
-//! This module implements the global `Map` object.
+//! Boa's implementation of ECMAScript's global `Map` object.
 //!
-//! The JavaScript `Map` class is a global object that is used in the construction of maps; which
+//! The ECMAScript `Map` class is a global object that is used in the construction of maps; which
 //! are high-level, key-value stores.
 //!
 //! More information:

boa_engine/src/builtins/math/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `Math` object.
+//! Boa's implementation of ECMAScript's global `Math` object.
 //!
 //! `Math` is a built-in object that has properties and methods for mathematical constants and functions. It’s not a function object.
 //!

boa_engine/src/builtins/mod.rs

@@ -1,4 +1,6 @@
-//! Builtins live here, such as Object, String, Math, etc.
+//! Boa's ECMAScript built-in object implementations, e.g. Object, String, Math, Array, etc.
+//!
+//! This module also contains a JavaScript Console implementation.
 
 pub mod array;
 pub mod array_buffer;
@@ -91,12 +93,12 @@ use crate::{
 
 /// Trait representing a global built-in object such as `Math`, `Object` or `String`.
 ///
-/// This trait must be implemented for any global built-in accessible from JavaScript.
+/// This trait must be implemented for any global built-in accessible from ECMAScript/JavaScript.
 pub(crate) trait BuiltIn {
     /// Binding name of the built-in inside the global object.
     ///
     /// E.g. If you want access the properties of a `Complex` built-in with the name `Cplx` you must
-    /// assign `"Cplx"` to this constant, making any property inside it accessible from Javascript
+    /// assign `"Cplx"` to this constant, making any property inside it accessible from ECMAScript/JavaScript
     /// as `Cplx.prop`
     const NAME: &'static str;
 
@@ -108,7 +110,7 @@ pub(crate) trait BuiltIn {
     /// Initialization code for the built-in.
     ///
     /// This is where the methods, properties, static methods and the constructor of a built-in must
-    /// be initialized to be accessible from Javascript.
+    /// be initialized to be accessible from ECMAScript/JavaScript.
     ///
     /// # Note
     ///

boa_engine/src/builtins/nan/mod.rs

@@ -1,4 +1,4 @@
-//! This module implements the global `NaN` property.
+//! Boa's implementation of ECMAScript's global `NaN` property.
 //!
 //! The global `NaN` is a property of the global object. In other words,
 //! it is a variable in global scope.