diff --git a/boa_ast/src/declaration/mod.rs b/boa_ast/src/declaration/mod.rs index fa89cca1f5..2aceb7864b 100644 --- a/boa_ast/src/declaration/mod.rs +++ b/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. diff --git a/boa_ast/src/declaration/variable.rs b/boa_ast/src/declaration/variable.rs index e3012a7e27..c206ef49b7 100644 --- a/boa_ast/src/declaration/variable.rs +++ b/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 diff --git a/boa_ast/src/expression/identifier.rs b/boa_ast/src/expression/identifier.rs index 0f7f73a05b..cdcf275876 100644 --- a/boa_ast/src/expression/identifier.rs +++ b/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 diff --git a/boa_ast/src/expression/literal/mod.rs b/boa_ast/src/expression/literal/mod.rs index beed8d8f90..d609fc7809 100644 --- a/boa_ast/src/expression/literal/mod.rs +++ b/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: diff --git a/boa_ast/src/expression/literal/object.rs b/boa_ast/src/expression/literal/object.rs index 2d2b91c39f..61f023418e 100644 --- a/boa_ast/src/expression/literal/object.rs +++ b/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 diff --git a/boa_ast/src/expression/mod.rs b/boa_ast/src/expression/mod.rs index e5a0a295f2..23087ba762 100644 --- a/boa_ast/src/expression/mod.rs +++ b/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 diff --git a/boa_ast/src/expression/operator/conditional.rs b/boa_ast/src/expression/operator/conditional.rs index f18b8d8f6a..8ecca552bf 100644 --- a/boa_ast/src/expression/operator/conditional.rs +++ b/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 (`?`), diff --git a/boa_ast/src/keyword.rs b/boa_ast/src/keyword.rs index a90ac7f73b..6b48cd3d2f 100644 --- a/boa_ast/src/keyword.rs +++ b/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. diff --git a/boa_ast/src/lib.rs b/boa_ast/src/lib.rs index 61bb575bcc..56773314af 100644 --- a/boa_ast/src/lib.rs +++ b/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( diff --git a/boa_ast/src/position.rs b/boa_ast/src/position.rs index 5c7a0956b4..36cd621358 100644 --- a/boa_ast/src/position.rs +++ b/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. /// diff --git a/boa_ast/src/punctuator.rs b/boa_ast/src/punctuator.rs index 3ab065dc6b..9bda165b0d 100644 --- a/boa_ast/src/punctuator.rs +++ b/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] diff --git a/boa_ast/src/statement/block.rs b/boa_ast/src/statement/block.rs index ca7f4ff548..beeea6fb3c 100644 --- a/boa_ast/src/statement/block.rs +++ b/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. /// diff --git a/boa_ast/src/statement/mod.rs b/boa_ast/src/statement/mod.rs index bbd610b190..14fa656442 100644 --- a/boa_ast/src/statement/mod.rs +++ b/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. //! diff --git a/boa_ast/src/visitor.rs b/boa_ast/src/visitor.rs index 5cf62e2b5c..3a1c055a7f 100644 --- a/boa_ast/src/visitor.rs +++ b/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. diff --git a/boa_engine/src/bigint.rs b/boa_engine/src/bigint.rs index df113190f5..41e4a0be2f 100644 --- a/boa_engine/src/bigint.rs +++ b/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; diff --git a/boa_engine/src/builtins/array/mod.rs b/boa_engine/src/builtins/array/mod.rs index 5a859587d2..d98c3aff26 100644 --- a/boa_engine/src/builtins/array/mod.rs +++ b/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] diff --git a/boa_engine/src/builtins/array_buffer/mod.rs b/boa_engine/src/builtins/array_buffer/mod.rs index 6a694e57a2..8246964f24 100644 --- a/boa_engine/src/builtins/array_buffer/mod.rs +++ b/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] diff --git a/boa_engine/src/builtins/async_function/mod.rs b/boa_engine/src/builtins/async_function/mod.rs index bf508b104d..dfbe6a31f0 100644 --- a/boa_engine/src/builtins/async_function/mod.rs +++ b/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] diff --git a/boa_engine/src/builtins/async_generator/mod.rs b/boa_engine/src/builtins/async_generator/mod.rs index e377f18cd1..fdde02d675 100644 --- a/boa_engine/src/builtins/async_generator/mod.rs +++ b/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] diff --git a/boa_engine/src/builtins/async_generator_function/mod.rs b/boa_engine/src/builtins/async_generator_function/mod.rs index 59a94b35a2..fe6e810221 100644 --- a/boa_engine/src/builtins/async_generator_function/mod.rs +++ b/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] diff --git a/boa_engine/src/builtins/bigint/mod.rs b/boa_engine/src/builtins/bigint/mod.rs index ded2c5135a..e4c45e163f 100644 --- a/boa_engine/src/builtins/bigint/mod.rs +++ b/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 diff --git a/boa_engine/src/builtins/boolean/mod.rs b/boa_engine/src/builtins/boolean/mod.rs index 9a70f28879..8f23ec18cc 100644 --- a/boa_engine/src/builtins/boolean/mod.rs +++ b/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. //! diff --git a/boa_engine/src/builtins/console/mod.rs b/boa_engine/src/builtins/console/mod.rs index 4e1a1fdc1b..3847f1cf22 100644 --- a/boa_engine/src/builtins/console/mod.rs +++ b/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. //! diff --git a/boa_engine/src/builtins/dataview/mod.rs b/boa_engine/src/builtins/dataview/mod.rs index 76348367d0..43170d699e 100644 --- a/boa_engine/src/builtins/dataview/mod.rs +++ b/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] diff --git a/boa_engine/src/builtins/date/mod.rs b/boa_engine/src/builtins/date/mod.rs index 06ffdedf43..4671b13646 100644 --- a/boa_engine/src/builtins/date/mod.rs +++ b/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] diff --git a/boa_engine/src/builtins/error/mod.rs b/boa_engine/src/builtins/error/mod.rs index 3c7e3d52e0..3f53964752 100644 --- a/boa_engine/src/builtins/error/mod.rs +++ b/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. diff --git a/boa_engine/src/builtins/eval/mod.rs b/boa_engine/src/builtins/eval/mod.rs index 5786c741dc..b051a8fd6d 100644 --- a/boa_engine/src/builtins/eval/mod.rs +++ b/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] diff --git a/boa_engine/src/builtins/function/mod.rs b/boa_engine/src/builtins/function/mod.rs index 5d7cc9bfb4..2edb19c69f 100644 --- a/boa_engine/src/builtins/function/mod.rs +++ b/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. //! diff --git a/boa_engine/src/builtins/generator/mod.rs b/boa_engine/src/builtins/generator/mod.rs index 317781e5a5..0a19d24db9 100644 --- a/boa_engine/src/builtins/generator/mod.rs +++ b/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. //! diff --git a/boa_engine/src/builtins/generator_function/mod.rs b/boa_engine/src/builtins/generator_function/mod.rs index 49845956d2..8721647470 100644 --- a/boa_engine/src/builtins/generator_function/mod.rs +++ b/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] diff --git a/boa_engine/src/builtins/global_this/mod.rs b/boa_engine/src/builtins/global_this/mod.rs index ac6f6f2a68..b7e7c1f2bb 100644 --- a/boa_engine/src/builtins/global_this/mod.rs +++ b/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. diff --git a/boa_engine/src/builtins/infinity/mod.rs b/boa_engine/src/builtins/infinity/mod.rs index 2800be3cfc..a3b24ca753 100644 --- a/boa_engine/src/builtins/infinity/mod.rs +++ b/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. //! diff --git a/boa_engine/src/builtins/intl/mod.rs b/boa_engine/src/builtins/intl/mod.rs index c0290f7a3b..609914426b 100644 --- a/boa_engine/src/builtins/intl/mod.rs +++ b/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. //! diff --git a/boa_engine/src/builtins/iterable/mod.rs b/boa_engine/src/builtins/iterable/mod.rs index df48e8209d..6bb4a0f239 100644 --- a/boa_engine/src/builtins/iterable/mod.rs +++ b/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; diff --git a/boa_engine/src/builtins/json/mod.rs b/boa_engine/src/builtins/json/mod.rs index 3d0725f01f..83036b2f89 100644 --- a/boa_engine/src/builtins/json/mod.rs +++ b/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 diff --git a/boa_engine/src/builtins/map/mod.rs b/boa_engine/src/builtins/map/mod.rs index 928c8ca918..7626058f9f 100644 --- a/boa_engine/src/builtins/map/mod.rs +++ b/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: diff --git a/boa_engine/src/builtins/math/mod.rs b/boa_engine/src/builtins/math/mod.rs index f3b919cd75..64a0ac5565 100644 --- a/boa_engine/src/builtins/math/mod.rs +++ b/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. //! diff --git a/boa_engine/src/builtins/mod.rs b/boa_engine/src/builtins/mod.rs index e28b8f2d1b..5c1c215cdb 100644 --- a/boa_engine/src/builtins/mod.rs +++ b/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 /// diff --git a/boa_engine/src/builtins/nan/mod.rs b/boa_engine/src/builtins/nan/mod.rs index 7c89361d73..08ddc16184 100644 --- a/boa_engine/src/builtins/nan/mod.rs +++ b/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. diff --git a/boa_engine/src/builtins/number/mod.rs b/boa_engine/src/builtins/number/mod.rs index f12f670698..290c6b7bbf 100644 --- a/boa_engine/src/builtins/number/mod.rs +++ b/boa_engine/src/builtins/number/mod.rs @@ -1,10 +1,10 @@ -//! This module implements the global `Number` object. +//! Boa's implementation of ECMAScript's global `Number` object. //! -//! The `Number` JavaScript object is a wrapper object allowing you to work with numerical values. +//! The `Number` ECMAScript object is a wrapper object allowing you to work with numerical values. //! A `Number` object is created using the `Number()` constructor. A primitive type object number is created using the `Number()` **function**. //! -//! The JavaScript `Number` type is double-precision 64-bit binary format IEEE 754 value. In more recent implementations, -//! JavaScript also supports integers with arbitrary precision using the `BigInt` type. +//! The ECMAScript `Number` type is double-precision 64-bit binary format IEEE 754 value. In more recent implementations, +//! ECMAScript also supports integers with arbitrary precision using the `BigInt` type. //! //! More information: //! - [ECMAScript reference][spec] diff --git a/boa_engine/src/builtins/object/mod.rs b/boa_engine/src/builtins/object/mod.rs index 9502d706e2..e3205b5645 100644 --- a/boa_engine/src/builtins/object/mod.rs +++ b/boa_engine/src/builtins/object/mod.rs @@ -1,6 +1,6 @@ -//! This module implements the global `Object` object. +//! Boa's implementation of ECMAScript's global `Object` object. //! -//! The `Object` class represents one of JavaScript's data types. +//! The `Object` class represents one of ECMAScript's data types. //! //! It is used to store various keyed collections and more complex entities. //! Objects can be created using the `Object()` constructor or the diff --git a/boa_engine/src/builtins/promise/mod.rs b/boa_engine/src/builtins/promise/mod.rs index dc79743c05..222ab55833 100644 --- a/boa_engine/src/builtins/promise/mod.rs +++ b/boa_engine/src/builtins/promise/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the global `Promise` object. +//! Boa's implementation of ECMAScript's global `Promise` object. #[cfg(test)] mod tests; diff --git a/boa_engine/src/builtins/proxy/mod.rs b/boa_engine/src/builtins/proxy/mod.rs index a9d498ec6e..9a771a4e18 100644 --- a/boa_engine/src/builtins/proxy/mod.rs +++ b/boa_engine/src/builtins/proxy/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the global `Proxy` object. +//! Boa's implementation of ECMAScript's global `Proxy` object. //! //! The `Proxy` object enables you to create a proxy for another object, //! which can intercept and redefine fundamental operations for that object. diff --git a/boa_engine/src/builtins/reflect/mod.rs b/boa_engine/src/builtins/reflect/mod.rs index 5544685100..4333f48536 100644 --- a/boa_engine/src/builtins/reflect/mod.rs +++ b/boa_engine/src/builtins/reflect/mod.rs @@ -1,7 +1,7 @@ -//! This module implements the global `Reflect` object. +//! Boa's implementation of ECMAScript's global `Reflect` object. //! //! The `Reflect` global object is a built-in object that provides methods for interceptable -//! JavaScript operations. +//! ECMAScript operations. //! //! More information: //! - [ECMAScript reference][spec] diff --git a/boa_engine/src/builtins/regexp/mod.rs b/boa_engine/src/builtins/regexp/mod.rs index 3db60a5f32..d1e34cca8c 100644 --- a/boa_engine/src/builtins/regexp/mod.rs +++ b/boa_engine/src/builtins/regexp/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the global `RegExp` object. +//! Boa's implementation of ECMAScript's global `RegExp` object. //! //! The `RegExp` object is used for matching text with a pattern. //! diff --git a/boa_engine/src/builtins/set/mod.rs b/boa_engine/src/builtins/set/mod.rs index 124309ed55..928ba7b7d7 100644 --- a/boa_engine/src/builtins/set/mod.rs +++ b/boa_engine/src/builtins/set/mod.rs @@ -1,6 +1,6 @@ -//! This module implements the global `Set` object. +//! Boa's implementation of ECMAScript's global `Set` object. //! -//! The JavaScript `Set` class is a global object that is used in the construction of sets; which +//! The ECMAScript `Set` class is a global object that is used in the construction of sets; which //! are high-level, collections of values. //! //! More information: diff --git a/boa_engine/src/builtins/string/mod.rs b/boa_engine/src/builtins/string/mod.rs index 249c025074..9535168983 100644 --- a/boa_engine/src/builtins/string/mod.rs +++ b/boa_engine/src/builtins/string/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the global `String` object. +//! Boa's implementation of ECMAScript's global `String` object. //! //! The `String` global object is a constructor for strings or a sequence of characters. //! diff --git a/boa_engine/src/builtins/symbol/mod.rs b/boa_engine/src/builtins/symbol/mod.rs index 899b63b8fc..6d81a81dc7 100644 --- a/boa_engine/src/builtins/symbol/mod.rs +++ b/boa_engine/src/builtins/symbol/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the global `Symbol` object. +//! Boa's implementation of ECMAScript's global `Symbol` object. //! //! The data type symbol is a primitive data type. //! The `Symbol()` function returns a value of type symbol, has static properties that expose diff --git a/boa_engine/src/builtins/typed_array/mod.rs b/boa_engine/src/builtins/typed_array/mod.rs index aa1ecee2f1..ba4c12f857 100644 --- a/boa_engine/src/builtins/typed_array/mod.rs +++ b/boa_engine/src/builtins/typed_array/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the global `TypedArray` objects. +//! Boa's implementation of ECMAScript's global `TypedArray` objects. //! //! A `TypedArray` object describes an array-like view of an underlying binary data buffer. //! There is no global property named `TypedArray`, nor is there a directly visible `TypedArray` constructor. diff --git a/boa_engine/src/builtins/undefined/mod.rs b/boa_engine/src/builtins/undefined/mod.rs index 9b3e329765..f463f3f832 100644 --- a/boa_engine/src/builtins/undefined/mod.rs +++ b/boa_engine/src/builtins/undefined/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the global `undefined` property. +//! Boa's implementation of ECMAScript's global `undefined` property. //! //! The global undefined property represents the primitive value undefined. //! diff --git a/boa_engine/src/builtins/uri/mod.rs b/boa_engine/src/builtins/uri/mod.rs index 123225579c..9292e65936 100644 --- a/boa_engine/src/builtins/uri/mod.rs +++ b/boa_engine/src/builtins/uri/mod.rs @@ -1,4 +1,4 @@ -//! URI Handling Functions +//! Boa's implementation of ECMAScript's URI Handling Functions. //! //! Uniform Resource Identifiers, or URIs, are Strings that identify resources (e.g. web pages or //! files) and transport protocols by which to access them (e.g. HTTP or FTP) on the Internet. The diff --git a/boa_engine/src/builtins/weak/mod.rs b/boa_engine/src/builtins/weak/mod.rs index 6600a25952..48cbbfe16d 100644 --- a/boa_engine/src/builtins/weak/mod.rs +++ b/boa_engine/src/builtins/weak/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the global `Weak*` objects. +//! Boa's implementation of ECMAScript's `WeakRef` object. mod weak_ref; diff --git a/boa_engine/src/builtins/weak/weak_ref.rs b/boa_engine/src/builtins/weak/weak_ref.rs index 29f8cf6ef7..ba826a36f7 100644 --- a/boa_engine/src/builtins/weak/weak_ref.rs +++ b/boa_engine/src/builtins/weak/weak_ref.rs @@ -13,9 +13,16 @@ use crate::{ Context, JsNativeError, JsResult, JsValue, }; -/// The [`WeakRef`][wr] builtin object. +/// Boa's implementation of ECMAScript's `WeakRef` builtin object. /// -/// [wr]: https://tc39.es/ecma262/#sec-weak-ref-objects +/// The `WeakRef` is a way to refer to a target object without rooting the target and thus preserving it in garbage +/// collection. A `WeakRef` will allow the user to dereference the target as long as the target object has not been +/// collected by the garbage collector. +/// +/// More Information: +/// - [ECMAScript Reference][spec] +/// +/// [spec]: https://tc39.es/ecma262/#sec-weak-ref-objects #[derive(Debug, Clone, Trace, Finalize)] pub(crate) struct WeakRef; diff --git a/boa_engine/src/context/intrinsics.rs b/boa_engine/src/context/intrinsics.rs index 772883bd10..79b295407d 100644 --- a/boa_engine/src/context/intrinsics.rs +++ b/boa_engine/src/context/intrinsics.rs @@ -1,4 +1,4 @@ -//! This module implements the data structures that contain intrinsic objects and constructors. +//! Data structures that contain intrinsic objects and constructors. use crate::{ builtins::{ diff --git a/boa_engine/src/context/mod.rs b/boa_engine/src/context/mod.rs index 74a95b5c98..41de6029ef 100644 --- a/boa_engine/src/context/mod.rs +++ b/boa_engine/src/context/mod.rs @@ -1,4 +1,4 @@ -//! Javascript context. +//! The ECMAScript context. pub mod intrinsics; @@ -37,7 +37,7 @@ use icu_provider::DataError; #[cfg(all(feature = "intl", doc))] pub use icu::BoaProvider; -/// Javascript context. It is the primary way to interact with the runtime. +/// ECMAScript context. It is the primary way to interact with the runtime. /// /// `Context`s constructed in a thread share the same runtime, therefore it /// is possible to share objects from one context to another context, but they diff --git a/boa_engine/src/environments/mod.rs b/boa_engine/src/environments/mod.rs index d10b599c57..612c57a3a8 100644 --- a/boa_engine/src/environments/mod.rs +++ b/boa_engine/src/environments/mod.rs @@ -1,4 +1,4 @@ -//! This module implements ECMAScript `Environment Records`. +//! Boa's implementation of ECMAScript's `Environment Records`. //! //! Environments contain the bindings of identifiers to their values. //! The implementation differs from the methods defined by the specification, diff --git a/boa_engine/src/job.rs b/boa_engine/src/job.rs index 9561e346ba..75a4e031eb 100644 --- a/boa_engine/src/job.rs +++ b/boa_engine/src/job.rs @@ -1,4 +1,4 @@ -//! This module contains the data structures for the microtask job queue. +//! Data structures for the microtask job queue. use crate::{prelude::JsObject, Context, JsResult, JsValue}; use boa_gc::{Finalize, Trace}; diff --git a/boa_engine/src/lib.rs b/boa_engine/src/lib.rs index 884ad65677..c8a7b79007 100644 --- a/boa_engine/src/lib.rs +++ b/boa_engine/src/lib.rs @@ -1,5 +1,5 @@ -//! This is an experimental Javascript lexer, parser and compiler written in Rust. Currently, it -//! has support for some of the language. +//! Boa's **boa_engine** crate implements ECMAScript's standard library of builtin objects +//! and an ECMAScript context, bytecompiler, and virtual machine for code execution. //! //! # Crate Features //! - **serde** - Enables serialization and deserialization of the AST (Abstract Syntax Tree). @@ -7,8 +7,26 @@ //! - **profiler** - Enables profiling with measureme (this is mostly internal). //! - **intl** - Enables `boa`'s [ECMA-402 Internationalization API][ecma-402] (`Intl` object) //! +//! # 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 +//! //! [whatwg]: https://console.spec.whatwg.org //! [ecma-402]: https://tc39.es/ecma402 +//! [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", diff --git a/boa_engine/src/object/builtins/jsarray.rs b/boa_engine/src/object/builtins/jsarray.rs index 085b731771..3bb71ee9dd 100644 --- a/boa_engine/src/object/builtins/jsarray.rs +++ b/boa_engine/src/object/builtins/jsarray.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `Array` Builtin JavaScript Object +//! A Rust API wrapper for Boa's `Array` Builtin ECMAScript Object use crate::{ builtins::Array, error::JsNativeError, diff --git a/boa_engine/src/object/builtins/jsarraybuffer.rs b/boa_engine/src/object/builtins/jsarraybuffer.rs index abfa187d74..832439b3a8 100644 --- a/boa_engine/src/object/builtins/jsarraybuffer.rs +++ b/boa_engine/src/object/builtins/jsarraybuffer.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `ArrayBuffer` Builtin JavaScript Object +//! A Rust API wrapper for Boa's `ArrayBuffer` Builtin ECMAScript Object use crate::{ builtins::array_buffer::ArrayBuffer, context::intrinsics::StandardConstructors, @@ -11,7 +11,7 @@ use crate::{ use boa_gc::{Finalize, Trace}; use std::ops::Deref; -/// `JsArrayBuffer` provides a wrapper for Boa's implementation of the JavaScript `ArrayBuffer` object +/// `JsArrayBuffer` provides a wrapper for Boa's implementation of the ECMAScript `ArrayBuffer` object #[derive(Debug, Clone, Trace, Finalize)] pub struct JsArrayBuffer { inner: JsObject, diff --git a/boa_engine/src/object/builtins/jsdataview.rs b/boa_engine/src/object/builtins/jsdataview.rs index f62e5c678f..0956835324 100644 --- a/boa_engine/src/object/builtins/jsdataview.rs +++ b/boa_engine/src/object/builtins/jsdataview.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `DataView` Builtin JavaScript Object +//! A Rust API wrapper for Boa's `DataView` Builtin ECMAScript Object use crate::{ builtins::DataView, context::intrinsics::StandardConstructors, @@ -12,21 +12,24 @@ use crate::{ use boa_gc::{Finalize, Trace}; use std::ops::Deref; -/// `JsDataView` Provides a wrapper for Boa's implementation of the JavaScript `DataView` object +/// `JsDataView` provides a wrapper for Boa's implementation of the ECMAScript `DataView` object /// /// # Examples /// ``` /// # use boa_engine::{ /// # object::builtins::{JsArrayBuffer, JsDataView}, -/// # Context, JsValue +/// # Context, JsValue, JsResult, /// # }; -/// +/// # fn main() -> JsResult<()> { /// // Create a new context and ArrayBuffer /// let context = &mut Context::default(); -/// let array_buffer = JsArrayBuffer::new(4, context).unwrap(); +/// let array_buffer = JsArrayBuffer::new(4, context)?; /// /// // Create a new Dataview from pre-existing ArrayBuffer -/// let data_view = JsDataView::from_js_array_buffer(&array_buffer, None, None, context).unwrap(); +/// let data_view = JsDataView::from_js_array_buffer(&array_buffer, None, None, context)?; +/// +/// # Ok(()) +/// # } /// ``` #[derive(Debug, Clone, Trace, Finalize)] pub struct JsDataView { diff --git a/boa_engine/src/object/builtins/jsdate.rs b/boa_engine/src/object/builtins/jsdate.rs index f84bb832de..37bca0ac91 100644 --- a/boa_engine/src/object/builtins/jsdate.rs +++ b/boa_engine/src/object/builtins/jsdate.rs @@ -1,3 +1,4 @@ +//! A Rust API wrapper for Boa's `Date` ECMAScript Builtin Object. use std::ops::Deref; use boa_gc::{Finalize, Trace}; diff --git a/boa_engine/src/object/builtins/jsfunction.rs b/boa_engine/src/object/builtins/jsfunction.rs index 8e674d9fb3..aaadebcea5 100644 --- a/boa_engine/src/object/builtins/jsfunction.rs +++ b/boa_engine/src/object/builtins/jsfunction.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `Function` Builtin JavaScript Object +//! A Rust API wrapper for Boa's `Function` Builtin ECMAScript Object use crate::{ object::{JsObject, JsObjectType}, JsValue, diff --git a/boa_engine/src/object/builtins/jsgenerator.rs b/boa_engine/src/object/builtins/jsgenerator.rs index c1347f4c82..4645f4b31d 100644 --- a/boa_engine/src/object/builtins/jsgenerator.rs +++ b/boa_engine/src/object/builtins/jsgenerator.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `Generator` Builtin JavaScript Object +//! A Rust API wrapper for Boa's `Generator` Builtin ECMAScript Object use crate::{ builtins::generator::{Generator, GeneratorState}, object::{JsObject, JsObjectType, ObjectData}, @@ -8,7 +8,7 @@ use crate::{ use boa_gc::{Finalize, Trace}; use std::ops::Deref; -/// `JsGenerator` provides a wrapper for Boa's implementation of the JavaScript `Generator` builtin object +/// `JsGenerator` provides a wrapper for Boa's implementation of the ECMAScript `Generator` builtin object #[derive(Debug, Clone, Trace, Finalize)] pub struct JsGenerator { inner: JsObject, diff --git a/boa_engine/src/object/builtins/jsmap.rs b/boa_engine/src/object/builtins/jsmap.rs index bf3a155a8f..5ae954452c 100644 --- a/boa_engine/src/object/builtins/jsmap.rs +++ b/boa_engine/src/object/builtins/jsmap.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `Map` Builtin JavaScript Object +//! A Rust API wrapper for Boa's `Map` Builtin ECMAScript Object use crate::{ builtins::map::{add_entries_from_iterable, ordered_map::OrderedMap}, builtins::Map, @@ -10,7 +10,7 @@ use crate::{ use boa_gc::{Finalize, Trace}; use std::ops::Deref; -/// `JsMap` provides a wrapper for Boa's implementation of the JavaScript `Map` object. +/// `JsMap` provides a wrapper for Boa's implementation of the ECMAScript `Map` object. /// /// # Examples /// @@ -18,9 +18,9 @@ use std::ops::Deref; /// ``` /// # use boa_engine::{ /// # object::builtins::JsMap, -/// # Context, JsValue, +/// # Context, JsValue, JsResult, /// # }; -/// +/// # fn main() -> JsResult<()> { /// // Create default `Context` /// let context = &mut Context::default(); /// @@ -28,19 +28,21 @@ use std::ops::Deref; /// let map = JsMap::new(context); /// /// // Set key-value pairs for the `JsMap`. -/// map.set("Key-1", "Value-1", context).unwrap(); -/// map.set("Key-2", 10, context).unwrap(); +/// map.set("Key-1", "Value-1", context)?; +/// map.set("Key-2", 10, context)?; /// -/// assert_eq!(map.get_size(context).unwrap(), 2.into()); +/// assert_eq!(map.get_size(context)?, 2.into()); +/// # Ok(()) +/// # } /// ``` /// /// Create a `JsMap` from a `JsArray` /// ``` /// # use boa_engine::{ /// # object::builtins::{JsArray, JsMap}, -/// # Context, JsValue, +/// # Context, JsValue, JsResult, /// # }; -/// +/// # fn main() -> JsResult<()> { /// // Create a default `Context` /// let context = &mut Context::default(); /// @@ -51,17 +53,18 @@ use std::ops::Deref; /// let vec_one: Vec = vec![JsValue::new("first-key"), JsValue::new("first-value")]; /// /// // We create an push our `[key, value]` pair onto our array as a `JsArray` -/// js_array -/// .push(JsArray::from_iter(vec_one, context), context) -/// .unwrap(); +/// js_array.push(JsArray::from_iter(vec_one, context), context)?; /// /// // Create a `JsMap` from the `JsArray` using it's iterable property. -/// let js_iterable_map = JsMap::from_js_iterable(&js_array.into(), context).unwrap(); +/// let js_iterable_map = JsMap::from_js_iterable(&js_array.into(), context)?; /// /// assert_eq!( -/// js_iterable_map.get("first-key", context).unwrap(), +/// js_iterable_map.get("first-key", context)?, /// "first-value".into() /// ); +/// +/// # Ok(()) +/// } /// ``` #[derive(Debug, Clone, Trace, Finalize)] pub struct JsMap { @@ -72,16 +75,13 @@ impl JsMap { /// Creates a new empty [`JsMap`] object. /// /// # Example - /// /// ``` /// # use boa_engine::{ /// # object::builtins::JsMap, /// # Context, JsValue, /// # }; - /// - /// // Create a new context. - /// let context = &mut Context::default(); - /// + /// # // Create a new context. + /// # let context = &mut Context::default(); /// // Create a new empty `JsMap`. /// let map = JsMap::new(context); /// ``` @@ -99,21 +99,21 @@ impl JsMap { /// # object::builtins::{JsArray, JsMap}, /// # Context, JsResult, JsValue, /// # }; - /// - /// // Create a default `Context` - /// let context = &mut Context::default(); - /// + /// # fn main() -> JsResult<()> { + /// # // Create a default `Context` + /// # let context = &mut Context::default(); /// // Create an array of two `[key, value]` pairs /// let js_array = JsArray::new(context); /// /// // Create a `[key, value]` pair of JsValues and add it to the `JsArray` as a `JsArray` /// let vec_one: Vec = vec![JsValue::new("first-key"), JsValue::new("first-value")]; - /// js_array - /// .push(JsArray::from_iter(vec_one, context), context) - /// .unwrap(); + /// js_array.push(JsArray::from_iter(vec_one, context), context)?; /// /// // Create a `JsMap` from the `JsArray` using it's iterable property. - /// let js_iterable_map = JsMap::from_js_iterable(&js_array.into(), context).unwrap(); + /// let js_iterable_map = JsMap::from_js_iterable(&js_array.into(), context)?; + /// + /// # Ok(()) + /// # } /// ``` #[inline] pub fn from_js_iterable(iterable: &JsValue, context: &mut Context) -> JsResult { @@ -134,16 +134,15 @@ impl JsMap { /// /// # Examples /// - /// Valid Example - returns a `JsMap` object + /// ### Valid Example - returns a `JsMap` object /// ``` /// # use boa_engine::{ /// # builtins::map::ordered_map::OrderedMap, /// # object::{builtins::JsMap, JsObject, ObjectData}, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; - /// - /// let context = &mut Context::default(); - /// + /// # fn main() -> JsResult<()> { + /// # let context = &mut Context::default(); /// // `some_object` can be any JavaScript `Map` object. /// let some_object = JsObject::from_proto_and_data( /// context.intrinsics().constructors().map().prototype(), @@ -151,18 +150,18 @@ impl JsMap { /// ); /// /// // Create `JsMap` object with incoming object. - /// let js_map = JsMap::from_object(some_object).unwrap(); + /// let js_map = JsMap::from_object(some_object)?; + /// # Ok(()) + /// # } /// ``` /// - /// Invalid Example - returns a `TypeError` with the message "object is not a Map" + /// ### Invalid Example - returns a `TypeError` with the message "object is not a Map" /// ``` /// # use boa_engine::{ /// # object::{JsObject, builtins::{JsArray, JsMap}}, /// # Context, JsResult, JsValue, /// # }; - /// - /// let context = &mut Context::default(); - /// + /// # let context = &mut Context::default(); /// let some_object = JsArray::new(context); /// /// // `some_object` is an Array object, not a map object @@ -213,18 +212,19 @@ impl JsMap { /// ``` /// # use boa_engine::{ /// # object::builtins::JsMap, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; - /// - /// let context = &mut Context::default(); - /// + /// # fn main() -> JsResult<()> { + /// # let context = &mut Context::default(); /// let js_map = JsMap::new(context); /// - /// js_map.set("foo", "bar", context).unwrap(); - /// js_map.set(2, 4, context).unwrap(); + /// js_map.set("foo", "bar", context)?; + /// js_map.set(2, 4, context)?; /// - /// assert_eq!(js_map.get("foo", context).unwrap(), "bar".into()); - /// assert_eq!(js_map.get(2, context).unwrap(), 4.into()) + /// assert_eq!(js_map.get("foo", context)?, "bar".into()); + /// assert_eq!(js_map.get(2, context)?, 4.into()); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn set(&self, key: K, value: V, context: &mut Context) -> JsResult @@ -246,18 +246,19 @@ impl JsMap { /// ``` /// # use boa_engine::{ /// # object::builtins::JsMap, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; - /// - /// let context = &mut Context::default(); - /// + /// # fn main() -> JsResult<()> { + /// # let context = &mut Context::default(); /// let js_map = JsMap::new(context); /// - /// js_map.set("foo", "bar", context).unwrap(); + /// js_map.set("foo", "bar", context)?; /// - /// let map_size = js_map.get_size(context).unwrap(); + /// let map_size = js_map.get_size(context)?; /// /// assert_eq!(map_size, 1.into()); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn get_size(&self, context: &mut Context) -> JsResult { @@ -271,19 +272,20 @@ impl JsMap { /// ``` /// # use boa_engine::{ /// # object::builtins::JsMap, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; - /// - /// let context = &mut Context::default(); - /// + /// # fn main() -> JsResult<()> { + /// # let context = &mut Context::default(); /// let js_map = JsMap::new(context); - /// js_map.set("foo", "bar", context).unwrap(); - /// js_map.set("hello", "world", context).unwrap(); + /// js_map.set("foo", "bar", context)?; + /// js_map.set("hello", "world", context)?; /// - /// js_map.delete("foo", context).unwrap(); + /// js_map.delete("foo", context)?; /// - /// assert_eq!(js_map.get_size(context).unwrap(), 1.into()); - /// assert_eq!(js_map.get("foo", context).unwrap(), JsValue::undefined()); + /// assert_eq!(js_map.get_size(context)?, 1.into()); + /// assert_eq!(js_map.get("foo", context)?, JsValue::undefined()); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn delete(&self, key: T, context: &mut Context) -> JsResult @@ -300,16 +302,18 @@ impl JsMap { /// ``` /// # use boa_engine::{ /// # object::builtins::JsMap, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; - /// - /// let context = &mut Context::default(); + /// # fn main() -> JsResult<()> { + /// # let context = &mut Context::default(); /// let js_map = JsMap::new(context); - /// js_map.set("foo", "bar", context).unwrap(); + /// js_map.set("foo", "bar", context)?; /// - /// let retrieved_value = js_map.get("foo", context).unwrap(); + /// let retrieved_value = js_map.get("foo", context)?; /// /// assert_eq!(retrieved_value, "bar".into()); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn get(&self, key: T, context: &mut Context) -> JsResult @@ -326,18 +330,19 @@ impl JsMap { /// ``` /// # use boa_engine::{ /// # object::builtins::JsMap, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; - /// - /// let context = &mut Context::default(); - /// + /// # fn main() -> JsResult<()> { + /// # let context = &mut Context::default(); /// let js_map = JsMap::new(context); - /// js_map.set("foo", "bar", context).unwrap(); - /// js_map.set("hello", "world", context).unwrap(); + /// js_map.set("foo", "bar", context)?; + /// js_map.set("hello", "world", context)?; /// - /// js_map.clear(context).unwrap(); + /// js_map.clear(context)?; /// - /// assert_eq!(js_map.get_size(context).unwrap(), 0.into()); + /// assert_eq!(js_map.get_size(context)?, 0.into()); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn clear(&self, context: &mut Context) -> JsResult { @@ -351,17 +356,18 @@ impl JsMap { /// ``` /// # use boa_engine::{ /// # object::builtins::JsMap, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; - /// - /// let context = &mut Context::default(); - /// + /// # fn main() -> JsResult<()> { + /// # let context = &mut Context::default(); /// let js_map = JsMap::new(context); - /// js_map.set("foo", "bar", context).unwrap(); + /// js_map.set("foo", "bar", context)?; /// - /// let has_key = js_map.has("foo", context).unwrap(); + /// let has_key = js_map.has("foo", context)?; /// /// assert_eq!(has_key, true.into()); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn has(&self, key: T, context: &mut Context) -> JsResult diff --git a/boa_engine/src/object/builtins/jsmap_iterator.rs b/boa_engine/src/object/builtins/jsmap_iterator.rs index 5503eb4aa2..dad6ff663f 100644 --- a/boa_engine/src/object/builtins/jsmap_iterator.rs +++ b/boa_engine/src/object/builtins/jsmap_iterator.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `MapIterator` Builtin JavaScript Object +//! A Rust API wrapper for Boa's `MapIterator` Builtin ECMAScript Object use crate::{ builtins::map::map_iterator::MapIterator, error::JsNativeError, @@ -9,7 +9,7 @@ use crate::{ use boa_gc::{Finalize, Trace}; use std::ops::Deref; -/// JavaScript `MapIterator` rust object +/// `JsMapIterator` provides a wrapper for Boa's implementation of the ECMAScript `MapIterator` object. #[derive(Debug, Clone, Finalize, Trace)] pub struct JsMapIterator { inner: JsObject, diff --git a/boa_engine/src/object/builtins/jsproxy.rs b/boa_engine/src/object/builtins/jsproxy.rs index c37419ac4b..28fd04603a 100644 --- a/boa_engine/src/object/builtins/jsproxy.rs +++ b/boa_engine/src/object/builtins/jsproxy.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `Proxy` Builtin JavaScript Object +//! A Rust API wrapper for the `Proxy` Builtin ECMAScript Object use boa_gc::{Finalize, Trace}; use crate::{ @@ -9,7 +9,7 @@ use crate::{ use super::JsFunction; -/// JavaScript [`Proxy`][proxy] rust object. +/// `JsProxy` provides a wrapper for Boa's implementation of the ECMAScript `Proxy` object /// /// This is a wrapper type for the [`Proxy`][proxy] API that allows customizing /// essential behaviour for an object, like [property accesses][get] or the @@ -58,7 +58,7 @@ impl std::ops::Deref for JsProxy { impl JsObjectType for JsProxy {} -/// JavaScript [`Proxy`][proxy] rust object that can be disabled. +/// `JsRevocableProxy` provides a wrapper for `JsProxy` that can be disabled. /// /// Safe interface for the [`Proxy.revocable`][revocable] method that creates a /// proxy that can be disabled using the [`JsRevocableProxy::revoke`] method. diff --git a/boa_engine/src/object/builtins/jsregexp.rs b/boa_engine/src/object/builtins/jsregexp.rs index 5d507a6615..4c1c617b05 100644 --- a/boa_engine/src/object/builtins/jsregexp.rs +++ b/boa_engine/src/object/builtins/jsregexp.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `RegExp` Builtin JavaScript Object +//! A Rust API wrapper for Boa's `RegExp` Builtin ECMAScript Object use crate::{ builtins::RegExp, object::{JsArray, JsObject, JsObjectType}, @@ -8,7 +8,7 @@ use crate::{ use boa_gc::{Finalize, Trace}; use std::ops::Deref; -/// `JsRegExp` provides a wrapper for Boa's implementation of the JavaScript `RegExp` builtin object +/// `JsRegExp` provides a wrapper for Boa's implementation of the ECMAScript `RegExp` builtin object /// /// # Examples /// @@ -17,21 +17,22 @@ use std::ops::Deref; /// ``` /// # use boa_engine::{ /// # object::builtins::JsRegExp, -/// # Context, JsValue, +/// # Context, JsValue, JsResult, /// # }; -/// +/// # fn main() -> JsResult<()> { /// // Initialize the `Context` /// let context = &mut Context::default(); /// /// // Create a new RegExp with pattern and flags -/// let regexp = JsRegExp::new("foo", "gi", context).unwrap(); +/// let regexp = JsRegExp::new("foo", "gi", context)?; /// -/// let test_result = regexp.test("football", context).unwrap(); +/// let test_result = regexp.test("football", context)?; /// assert!(test_result); /// -/// let to_string = regexp.to_string(context).unwrap(); +/// let to_string = regexp.to_string(context)?; /// assert_eq!(to_string, String::from("/foo/gi")); -/// +/// # Ok(()) +/// # } /// ``` /// #[derive(Debug, Clone, Trace, Finalize)] @@ -44,13 +45,16 @@ impl JsRegExp { /// ``` /// # use boa_engine::{ /// # object::builtins::JsRegExp, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; + /// # fn main() -> JsResult<()> { /// // Initialize the `Context` /// let context = &mut Context::default(); /// /// // Create a new RegExp with pattern and flags - /// let regexp = JsRegExp::new("foo", "gi", context).unwrap(); + /// let regexp = JsRegExp::new("foo", "gi", context)?; + /// # Ok(()) + /// # } /// ``` #[inline] pub fn new(pattern: S, flags: S, context: &mut Context) -> JsResult @@ -138,13 +142,16 @@ impl JsRegExp { /// ``` /// # use boa_engine::{ /// # object::builtins::JsRegExp, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; + /// # fn main() -> JsResult<()> { /// # let context = &mut Context::default(); - /// let regexp = JsRegExp::new("foo", "gi", context).unwrap(); + /// let regexp = JsRegExp::new("foo", "gi", context)?; /// - /// let flags = regexp.flags(context).unwrap(); + /// let flags = regexp.flags(context)?; /// assert_eq!(flags, String::from("gi")); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn flags(&self, context: &mut Context) -> JsResult { @@ -160,13 +167,16 @@ impl JsRegExp { /// ``` /// # use boa_engine::{ /// # object::builtins::JsRegExp, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; + /// # fn main() -> JsResult<()> { /// # let context = &mut Context::default(); - /// let regexp = JsRegExp::new("foo", "gi", context).unwrap(); + /// let regexp = JsRegExp::new("foo", "gi", context)?; /// - /// let src = regexp.source(context).unwrap(); + /// let src = regexp.source(context)?; /// assert_eq!(src, String::from("foo")); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn source(&self, context: &mut Context) -> JsResult { @@ -182,13 +192,16 @@ impl JsRegExp { /// ``` /// # use boa_engine::{ /// # object::builtins::JsRegExp, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; + /// # fn main() -> JsResult<()> { /// # let context = &mut Context::default(); - /// let regexp = JsRegExp::new("foo", "gi", context).unwrap(); + /// let regexp = JsRegExp::new("foo", "gi", context)?; /// - /// let test_result = regexp.test("football", context).unwrap(); + /// let test_result = regexp.test("football", context)?; /// assert!(test_result); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn test(&self, search_string: S, context: &mut Context) -> JsResult @@ -223,13 +236,16 @@ impl JsRegExp { /// ``` /// # use boa_engine::{ /// # object::builtins::JsRegExp, - /// # Context, JsValue, + /// # Context, JsValue, JsResult, /// # }; + /// # fn main() -> JsResult<()> { /// # let context = &mut Context::default(); - /// let regexp = JsRegExp::new("foo", "gi", context).unwrap(); + /// let regexp = JsRegExp::new("foo", "gi", context)?; /// - /// let to_string = regexp.to_string(context).unwrap(); + /// let to_string = regexp.to_string(context)?; /// assert_eq!(to_string, String::from("/foo/gi")); + /// # Ok(()) + /// # } /// ``` #[inline] pub fn to_string(&self, context: &mut Context) -> JsResult { diff --git a/boa_engine/src/object/builtins/jsset.rs b/boa_engine/src/object/builtins/jsset.rs index f8af1ab90e..d22399b7d6 100644 --- a/boa_engine/src/object/builtins/jsset.rs +++ b/boa_engine/src/object/builtins/jsset.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `Set` Builtin JavaScript Object +//! A Rust API wrapper for the `Set` Builtin ECMAScript Object use std::ops::Deref; use boa_gc::{Finalize, Trace}; @@ -10,7 +10,7 @@ use crate::{ Context, JsResult, JsValue, }; -/// `JsSet` provides a wrapper for Boa's implementation of the JavaScript `Set` object. +/// `JsSet` provides a wrapper for Boa's implementation of the ECMAScript `Set` object. #[derive(Debug, Clone, Trace, Finalize)] pub struct JsSet { inner: JsObject, diff --git a/boa_engine/src/object/builtins/jsset_iterator.rs b/boa_engine/src/object/builtins/jsset_iterator.rs index 2e417d8187..e1c598d708 100644 --- a/boa_engine/src/object/builtins/jsset_iterator.rs +++ b/boa_engine/src/object/builtins/jsset_iterator.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `SetIterator` Builtin JavaScript Object +//! A Rust API wrapper for Boa's `SetIterator` Builtin ECMAScript Object use std::ops::Deref; use boa_gc::{Finalize, Trace}; @@ -10,7 +10,7 @@ use crate::{ Context, JsResult, JsValue, }; -/// `JsSetIterator` provides a wrapper for Boa's implementation of the JavaScript `SetIterator` object +/// `JsSetIterator` provides a wrapper for Boa's implementation of the ECMAScript `SetIterator` object #[derive(Debug, Clone, Finalize, Trace)] pub struct JsSetIterator { inner: JsObject, diff --git a/boa_engine/src/object/builtins/jstypedarray.rs b/boa_engine/src/object/builtins/jstypedarray.rs index b19a5b6415..757e3b0774 100644 --- a/boa_engine/src/object/builtins/jstypedarray.rs +++ b/boa_engine/src/object/builtins/jstypedarray.rs @@ -1,4 +1,4 @@ -//! This module implements a wrapper for the `TypedArray` Builtin JavaScript Object +//! Rust API wrappers for the `TypedArray` Builtin ECMAScript Objects use crate::{ builtins::typed_array::TypedArray, error::JsNativeError, @@ -9,7 +9,7 @@ use crate::{ use boa_gc::{Finalize, Trace}; use std::ops::Deref; -/// JavaScript `TypedArray` rust object. +/// `JsTypedArray` provides a wrapper for Boa's implementation of the ECMAScript `TypedArray` builtin object. #[derive(Debug, Clone, Trace, Finalize)] pub struct JsTypedArray { inner: JsValue, @@ -343,7 +343,7 @@ impl JsObjectType for JsTypedArray {} macro_rules! JsTypedArrayType { ($name:ident, $constructor_function:ident, $constructor_object:ident, $element:ty) => { - #[doc = concat!("JavaScript `", stringify!($constructor_function), "` rust object.")] + #[doc = concat!("`", stringify!($name), "` provides a wrapper for Boa's implementation of the ECMAScript `", stringify!($constructor_function) ,"` builtin object.")] #[derive(Debug, Clone, Trace, Finalize)] pub struct $name { inner: JsTypedArray, diff --git a/boa_engine/src/object/builtins/mod.rs b/boa_engine/src/object/builtins/mod.rs index c984fde056..435a233774 100644 --- a/boa_engine/src/object/builtins/mod.rs +++ b/boa_engine/src/object/builtins/mod.rs @@ -1,4 +1,6 @@ -//! Contains all the Rust representations of JavaScript objects. +//! All Rust API wrappers for Boa's ECMAScript objects. +//! +//! The structs available in this module provide functionality to interact with the implemented ECMAScript object from Rust. mod jsarray; mod jsarraybuffer; diff --git a/boa_engine/src/object/mod.rs b/boa_engine/src/object/mod.rs index 6c0afb39e0..6971516d47 100644 --- a/boa_engine/src/object/mod.rs +++ b/boa_engine/src/object/mod.rs @@ -1,7 +1,6 @@ -//! This module implements the Rust representation of a JavaScript object, -//! see [`object::builtins`][builtins] for implementors. +//! Boa's representation of a JavaScript object and builtin object wrappers //! -//! This module also provides helper objects for working with JavaScript objects. +//! For the builtin object wrappers, please see [`object::builtins`][builtins] for implementors. pub use jsobject::{RecursionLimiter, Ref, RefMut}; pub use operations::IntegrityLevel; diff --git a/boa_engine/src/property/mod.rs b/boa_engine/src/property/mod.rs index caa46425ea..941bd0fbb6 100644 --- a/boa_engine/src/property/mod.rs +++ b/boa_engine/src/property/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the Property Descriptor. +//! Boa's implementation of ECMAScript's Property Descriptor. //! //! The Property Descriptor type is used to explain the manipulation and reification of `Object` //! property attributes. Values of the Property Descriptor type are Records. Each field's name is @@ -23,7 +23,7 @@ use std::fmt; pub use attribute::Attribute; -/// This represents a JavaScript Property AKA The Property Descriptor. +/// This represents an ECMAScript Property AKA The Property Descriptor. /// /// Property descriptors present in objects come in three main flavors: /// - data descriptors diff --git a/boa_engine/src/realm.rs b/boa_engine/src/realm.rs index 31d076cf4c..ed8a205797 100644 --- a/boa_engine/src/realm.rs +++ b/boa_engine/src/realm.rs @@ -1,3 +1,5 @@ +//! Boa's implementation of ECMAScript's `Realm Records` +//! //! Conceptually, a realm consists of a set of intrinsic objects, an ECMAScript global environment, //! all of the ECMAScript code that is loaded within the scope of that global environment, //! and other associated state and resources. diff --git a/boa_engine/src/symbol.rs b/boa_engine/src/symbol.rs index 26792b99ba..18228c3e71 100644 --- a/boa_engine/src/symbol.rs +++ b/boa_engine/src/symbol.rs @@ -1,4 +1,4 @@ -//! This module implements the global `Symbol` object. +//! Boa's implementation of ECMAScript's global `Symbol` object. //! //! The data type symbol is a primitive data type. //! The `Symbol()` function returns a value of type symbol, has static properties that expose diff --git a/boa_engine/src/value/mod.rs b/boa_engine/src/value/mod.rs index ddca745d04..2b10940fbd 100644 --- a/boa_engine/src/value/mod.rs +++ b/boa_engine/src/value/mod.rs @@ -1,4 +1,4 @@ -//! This module implements the JavaScript Value. +//! Boa's ECMAScript Value implementation. //! //! Javascript values, utility methods and conversion between Javascript values and Rust values. diff --git a/boa_engine/src/vm/mod.rs b/boa_engine/src/vm/mod.rs index 08426c73e8..dabb08162d 100644 --- a/boa_engine/src/vm/mod.rs +++ b/boa_engine/src/vm/mod.rs @@ -1,3 +1,5 @@ +//! Boa's ECMAScript Virtual Machine +//! //! The Virtual Machine (VM) handles generating instructions, then executing them. //! This module will provide an instruction set for the AST to use, various traits, //! plus an interpreter to execute those instructions diff --git a/boa_gc/src/lib.rs b/boa_gc/src/lib.rs index 6db1b8d614..814b89fd88 100644 --- a/boa_gc/src/lib.rs +++ b/boa_gc/src/lib.rs @@ -1,5 +1,32 @@ -//! Garbage collector for the Boa JavaScript engine. - +//! Boa's **boa_gc** crate implements a garbage collector. +//! +//! # Crate Overview +//! **boa_gc** is a mark-sweep garbage collector that implements a Trace and Finalize trait +//! for garbage collected values. +//! +//! # 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 +//! +//! [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( diff --git a/boa_interner/src/lib.rs b/boa_interner/src/lib.rs index ebcdd4d7d9..dbbad51bc2 100644 --- a/boa_interner/src/lib.rs +++ b/boa_interner/src/lib.rs @@ -1,5 +1,6 @@ -//! String interner for Boa. +//! Boa's **boa_interner** is a string interner for compiler performance. //! +//! # Crate Overview //! The idea behind using a string interner is that in most of the code, strings such as //! identifiers and literals are often repeated. This causes extra burden when comparing them and //! storing them. A string interner stores a unique `usize` symbol for each string, making sure @@ -7,6 +8,25 @@ //! to `usize`, and also it's easier to store, since instead of a heap-allocated string, you only //! need to store a `usize`. This reduces memory consumption and improves performance in the //! compiler. +//! +//! # 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 +//! +//! [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", diff --git a/boa_macros/src/lib.rs b/boa_macros/src/lib.rs index 6525e7665c..c875947a10 100644 --- a/boa_macros/src/lib.rs +++ b/boa_macros/src/lib.rs @@ -1,5 +1,9 @@ //! Macros for the Boa JavaScript engine. +#![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( diff --git a/boa_parser/src/lexer/comment.rs b/boa_parser/src/lexer/comment.rs index b5db8a5b32..abd9633855 100644 --- a/boa_parser/src/lexer/comment.rs +++ b/boa_parser/src/lexer/comment.rs @@ -1,4 +1,4 @@ -//! This module implements lexing for comments used in the JavaScript programing language. +//! Boa's lexing for ECMAScript comments. use crate::lexer::{Cursor, Error, Token, TokenKind, Tokenizer}; use boa_ast::{Position, Span}; diff --git a/boa_parser/src/lexer/cursor.rs b/boa_parser/src/lexer/cursor.rs index 5dd890f838..88a095c529 100644 --- a/boa_parser/src/lexer/cursor.rs +++ b/boa_parser/src/lexer/cursor.rs @@ -1,4 +1,4 @@ -//! Module implementing the lexer cursor. This is used for managing the input byte stream. +//! Boa's lexer cursor that manages the input byte stream. use boa_ast::Position; use boa_profiler::Profiler; use std::io::{self, Bytes, Error, ErrorKind, Read}; diff --git a/boa_parser/src/lexer/identifier.rs b/boa_parser/src/lexer/identifier.rs index d66038d306..288cef2d16 100644 --- a/boa_parser/src/lexer/identifier.rs +++ b/boa_parser/src/lexer/identifier.rs @@ -1,4 +1,4 @@ -//! This module implements lexing for identifiers (foo, myvar, etc.) used in the JavaScript programing language. +//! This module implements lexing for identifiers (foo, myvar, etc.) used in ECMAScript. use crate::lexer::{Cursor, Error, StringLiteral, Token, TokenKind, Tokenizer}; use boa_ast::{Keyword, Position, Span}; diff --git a/boa_parser/src/lexer/mod.rs b/boa_parser/src/lexer/mod.rs index 7c2c17adae..3d878af86c 100644 --- a/boa_parser/src/lexer/mod.rs +++ b/boa_parser/src/lexer/mod.rs @@ -1,6 +1,4 @@ -//! A lexical analyzer for JavaScript source code. -//! -//! This module contains the Boa lexer or tokenizer implementation. +//! Boa's lexical analyzer(Lexer) for ECMAScript source code. //! //! The Lexer splits its input source code into a sequence of input elements called tokens, //! represented by the [Token] structure. It also removes diff --git a/boa_parser/src/lexer/number.rs b/boa_parser/src/lexer/number.rs index 82127aeb02..585b69a751 100644 --- a/boa_parser/src/lexer/number.rs +++ b/boa_parser/src/lexer/number.rs @@ -1,4 +1,4 @@ -//! This module implements lexing for number literals (123, 787) used in the JavaScript programing language. +//! This module implements lexing for number literals (123, 787) used in ECMAScript. use crate::lexer::{token::Numeric, Cursor, Error, Token, TokenKind, Tokenizer}; use boa_ast::{Position, Span}; diff --git a/boa_parser/src/lexer/operator.rs b/boa_parser/src/lexer/operator.rs index acfb686c4b..821781faec 100644 --- a/boa_parser/src/lexer/operator.rs +++ b/boa_parser/src/lexer/operator.rs @@ -1,4 +1,4 @@ -//! This module implements lexing for operators (+, - etc.) used in the JavaScript programing language. +//! Boa's lexing for ECMAScript operators (+, - etc.). use crate::lexer::{Cursor, Error, Token, TokenKind, Tokenizer}; use boa_ast::{Position, Punctuator, Span}; diff --git a/boa_parser/src/lexer/private_identifier.rs b/boa_parser/src/lexer/private_identifier.rs index 0d1bd85248..296fe13c1d 100644 --- a/boa_parser/src/lexer/private_identifier.rs +++ b/boa_parser/src/lexer/private_identifier.rs @@ -1,4 +1,4 @@ -//! This module implements lexing for private identifiers (#foo, #myvar, etc.) used in the JavaScript programing language. +//! Boa's lexing for ECMAScript private identifiers (#foo, #myvar, etc.). use crate::lexer::{identifier::Identifier, Cursor, Error, Token, TokenKind, Tokenizer}; use boa_ast::{Position, Span}; diff --git a/boa_parser/src/lexer/regex.rs b/boa_parser/src/lexer/regex.rs index 6b2a9f39cc..41d6270dc4 100644 --- a/boa_parser/src/lexer/regex.rs +++ b/boa_parser/src/lexer/regex.rs @@ -1,4 +1,4 @@ -//! This module implements lexing for regex literals used in the JavaScript programing language. +//! Boa's lexing for ECMAScript regex literals. use crate::lexer::{Cursor, Error, Span, Token, TokenKind, Tokenizer}; use bitflags::bitflags; diff --git a/boa_parser/src/lexer/spread.rs b/boa_parser/src/lexer/spread.rs index b26b8f5d47..d22a1f41cb 100644 --- a/boa_parser/src/lexer/spread.rs +++ b/boa_parser/src/lexer/spread.rs @@ -1,4 +1,4 @@ -//! This module implements lexing for spread (...) literals used in the JavaScript programing language. +//! Boa's lexing for ECMAScript spread (...) literals. use crate::lexer::{Cursor, Error, Token, Tokenizer}; use boa_ast::{Position, Punctuator, Span}; diff --git a/boa_parser/src/lexer/string.rs b/boa_parser/src/lexer/string.rs index 38f44ef2d8..ed337e1b33 100644 --- a/boa_parser/src/lexer/string.rs +++ b/boa_parser/src/lexer/string.rs @@ -1,4 +1,4 @@ -//! This module implements lexing for string literals used in the JavaScript programing language. +//! Boa's lexing for ECMAScript string literals. use crate::lexer::{Cursor, Error, Token, TokenKind, Tokenizer}; use boa_ast::{Position, Span}; diff --git a/boa_parser/src/lexer/template.rs b/boa_parser/src/lexer/template.rs index b1ab0e12cb..7a666d745e 100644 --- a/boa_parser/src/lexer/template.rs +++ b/boa_parser/src/lexer/template.rs @@ -1,4 +1,4 @@ -//! This module implements lexing for template literals used in the JavaScript programing language. +//! Boa's lexing for ECMAScript template literals. use crate::lexer::{ string::{StringLiteral, UTF16CodeUnitsBuffer}, diff --git a/boa_parser/src/lexer/token.rs b/boa_parser/src/lexer/token.rs index df752d6893..5fcd06cb1d 100644 --- a/boa_parser/src/lexer/token.rs +++ b/boa_parser/src/lexer/token.rs @@ -1,4 +1,4 @@ -//! This module implements all of the [Token]s used in the JavaScript programing language. +//! Boa's implementation of all ECMAScript [Token]s. //! //! More information: //! - [ECMAScript reference][spec] diff --git a/boa_parser/src/lib.rs b/boa_parser/src/lib.rs index 372efae3a1..6ef21433ba 100644 --- a/boa_parser/src/lib.rs +++ b/boa_parser/src/lib.rs @@ -1,13 +1,36 @@ -//! Parser targeting the latest [ECMAScript language specification][spec]. +//! Boa's **boa_parser** crate is a parser targeting the latest [ECMAScript language specification][spec]. //! +//! # Crate Overview //! This crate contains implementations of a [`Lexer`] and a [`Parser`] for the **ECMAScript** //! language. The [lexical grammar][lex] and the [syntactic grammar][grammar] being targeted are //! fully defined in the specification. See the links provided for more information. //! +//! # 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 +//! //! [spec]: https://tc39.es/ecma262 //! [lex]: https://tc39.es/ecma262/#sec-ecmascript-language-lexical-grammar //! [grammar]: https://tc39.es/ecma262/#sec-ecmascript-language-expressions +//! [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( diff --git a/boa_profiler/src/lib.rs b/boa_profiler/src/lib.rs index c57cce497b..2b9b07b2fa 100644 --- a/boa_profiler/src/lib.rs +++ b/boa_profiler/src/lib.rs @@ -1,4 +1,28 @@ -//! Profiler for the Boa JavaScript engine. +//! The **`boa_profiler`** crate is a code profiler for Boa. +//! +//! # Crate Overview +//! This crate provides a code profiler for Boa. For more information, please +//! see Boa's page on [profiling][profiler-md] +//! +//! # 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 +//! +//! [profiler-md]: https://github.com/boa-dev/boa/blob/main/docs/profiling.md +//! [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/ #![cfg_attr(not(test), forbid(clippy::unwrap_used))] #![warn(missing_docs, clippy::dbg_macro)] diff --git a/boa_unicode/src/lib.rs b/boa_unicode/src/lib.rs index fd4ce3a45c..7e00b09154 100644 --- a/boa_unicode/src/lib.rs +++ b/boa_unicode/src/lib.rs @@ -1,10 +1,33 @@ -//! This library implements the extension to query if a char belongs to a particular unicode identifier property. -//! Version: Unicode 15.0.0 +//! Boa's **boa_unicode** crate for query valid Unicode identifiers. +//! +//! # Crate Overview +//! This crate implements the extension to query if a char belongs to a particular unicode identifier property. +//! +//! Current Version: +//! - Unicode 15.0.0 //! //! More information: //! - [Unicode® Standard Annex #31][uax31] //! +//! # 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 +//! //! [uax31]: http://unicode.org/reports/tr31 +//! [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",