From ab87b2fd5b48401b02ed7d8bad757e208d3d3e23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Juli=C3=A1n=20Espina?= Date: Wed, 17 May 2023 20:46:40 +0000 Subject: [PATCH] Extract "About Boa" section into a separate file (#2938) * Extract "About Boa" section into a separate file * Add newline * cargo fmt --- ABOUT.md | 33 +++++++++++++++++++++++++++++++++ boa_ast/src/lib.rs | 21 +-------------------- boa_cli/src/main.rs | 3 ++- boa_engine/src/lib.rs | 27 ++------------------------- boa_gc/src/lib.rs | 23 ++--------------------- boa_icu_provider/src/lib.rs | 2 +- boa_interner/src/lib.rs | 22 ++-------------------- boa_macros/src/lib.rs | 3 ++- boa_parser/src/lib.rs | 23 +++-------------------- boa_profiler/src/lib.rs | 25 ++++--------------------- boa_runtime/src/lib.rs | 28 +++------------------------- boa_tester/src/main.rs | 3 ++- boa_unicode/src/lib.rs | 22 ++-------------------- boa_wasm/src/lib.rs | 5 +++-- 14 files changed, 62 insertions(+), 178 deletions(-) create mode 100644 ABOUT.md diff --git a/ABOUT.md b/ABOUT.md new file mode 100644 index 0000000000..ecb9e95e0e --- /dev/null +++ b/ABOUT.md @@ -0,0 +1,33 @@ +# 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`**][ast] - Boa's ECMAScript Abstract Syntax Tree. +- [**`boa_engine`**][engine] - Boa's implementation of ECMAScript builtin objects and + execution. +- [**`boa_gc`**][gc] - Boa's garbage collector. +- [**`boa_interner`**][interner] - Boa's string interner. +- [**`boa_parser`**][parser] - Boa's lexer and parser. +- [**`boa_profiler`**][profiler] - Boa's code profiler. +- [**`boa_icu_provider`**][icu] - Boa's ICU4X data provider. +- [**`boa_runtime`**][runtime] - Boa's WebAPI features. + +[boa-conformance]: https://boajs.dev/boa/test262/ +[boa-web]: https://boajs.dev/ +[boa-playground]: https://boajs.dev/boa/playground/ +[ast]: https://boajs.dev/boa/doc/boa_ast/index.html +[engine]: https://boajs.dev/boa/doc/boa_engine/index.html +[gc]: https://boajs.dev/boa/doc/boa_gc/index.html +[interner]: https://boajs.dev/boa/doc/boa_interner/index.html +[parser]: https://boajs.dev/boa/doc/boa_parser/index.html +[profiler]: https://boajs.dev/boa/doc/boa_profiler/index.html +[icu]: https://boajs.dev/boa/doc/boa_icu_provider/index.html +[runtime]: https://boajs.dev/boa/doc/boa_runtime/index.html diff --git a/boa_ast/src/lib.rs b/boa_ast/src/lib.rs index d247fa04cb..30a1aed191 100644 --- a/boa_ast/src/lib.rs +++ b/boa_ast/src/lib.rs @@ -10,28 +10,9 @@ //! [`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. -//! - **`boa_icu_provider`** - Boa's ICU4X data provider. -//! //! [grammar]: https://tc39.es/ecma262/#sec-syntactic-grammar //! [early]: https://tc39.es/ecma262/#sec-static-semantic-rules -//! [boa-conformance]: https://boajs.dev/boa/test262/ -//! [boa-web]: https://boajs.dev/ -//! [boa-playground]: https://boajs.dev/boa/playground/ - +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_cli/src/main.rs b/boa_cli/src/main.rs index af45a025bf..b5be81642a 100644 --- a/boa_cli/src/main.rs +++ b/boa_cli/src/main.rs @@ -1,5 +1,6 @@ //! A ECMAScript REPL implementation based on boa_engine. - +//! +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_engine/src/lib.rs b/boa_engine/src/lib.rs index 985da500de..9a5c8d3699 100644 --- a/boa_engine/src/lib.rs +++ b/boa_engine/src/lib.rs @@ -1,16 +1,6 @@ //! Boa's **`boa_engine`** crate implements ECMAScript's standard library of builtin objects //! and an ECMAScript context, bytecompiler, and virtual machine for code execution. //! -//! # 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]. -//! -//! For information related to Web API features, please see [boa_runtime](runtime-docs). -//! //! # Example usage //! //! You can find multiple examples of the usage of Boa in the [`boa_examples`][examples] crate. In @@ -53,23 +43,10 @@ //! - **profiler** - Enables profiling with measureme (this is mostly internal). //! - **intl** - Enables `boa`'s [ECMA-402 Internationalization API][ecma-402] (`Intl` object) //! -//! # Boa Crates -//! - **`boa_ast`** - Boa's ECMAScript Abstract Syntax Tree. -//! - **`boa_engine`** - Boa's implementation of ECMAScript builtin objects and execution. -//! - **`boa_gc`** - Boa's garbage collector. -//! - **`boa_interner`** - Boa's string interner. -//! - **`boa_parser`** - Boa's lexer and parser. -//! - **`boa_profiler`** - Boa's code profiler. -//! - **`boa_unicode`** - Boa's Unicode identifier. -//! - **`boa_icu_provider`** - Boa's ICU4X data provider. -//! //! [ecma-402]: https://tc39.es/ecma402 -//! [boa-conformance]: https://boajs.dev/boa/test262/ -//! [boa-web]: https://boajs.dev/ -//! [boa-playground]: https://boajs.dev/boa/playground/ -//! [runtime-docs]: https://boajs.dev/boa/doc/boa_runtime/index.html //! [examples]: https://github.com/boa-dev/boa/tree/main/boa_examples - +//! +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_gc/src/lib.rs b/boa_gc/src/lib.rs index 941f003113..fb6e9b53fb 100644 --- a/boa_gc/src/lib.rs +++ b/boa_gc/src/lib.rs @@ -1,29 +1,10 @@ //! 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 +//! **`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_icu_provider`** - Boa's ICU4X data provider. -//! -//! [boa-conformance]: https://boajs.dev/boa/test262/ -//! [boa-web]: https://boajs.dev/ -//! [boa-playground]: https://boajs.dev/boa/playground/ - +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_icu_provider/src/lib.rs b/boa_icu_provider/src/lib.rs index 6bd11db554..ee9df26c88 100644 --- a/boa_icu_provider/src/lib.rs +++ b/boa_icu_provider/src/lib.rs @@ -14,7 +14,7 @@ //! [ICU4X guide]: https://github.com/unicode-org/icu4x/blob/main/docs/tutorials/data_management.md //! [`BufferProvider`]: icu_provider::BufferProvider //! [`AnyProvider`]: icu_provider::AnyProvider - +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_interner/src/lib.rs b/boa_interner/src/lib.rs index 3088b859e4..00fae2dce9 100644 --- a/boa_interner/src/lib.rs +++ b/boa_interner/src/lib.rs @@ -1,6 +1,7 @@ //! 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 @@ -9,26 +10,7 @@ //! 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_icu_provider`** - Boa's ICU4X data provider. -//! -//! [boa-conformance]: https://boajs.dev/boa/test262/ -//! [boa-web]: https://boajs.dev/ -//! [boa-playground]: https://boajs.dev/boa/playground/ - +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_macros/src/lib.rs b/boa_macros/src/lib.rs index 80c2985e05..a02198bbe7 100644 --- a/boa_macros/src/lib.rs +++ b/boa_macros/src/lib.rs @@ -1,5 +1,6 @@ //! Macros for the Boa JavaScript engine. - +//! +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_parser/src/lib.rs b/boa_parser/src/lib.rs index 2a03c371f6..01cc4c8763 100644 --- a/boa_parser/src/lib.rs +++ b/boa_parser/src/lib.rs @@ -1,33 +1,16 @@ //! 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. -//! - **`boa_icu_provider`** - Boa's ICU4X data provider. -//! //! [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://boajs.dev/boa/test262/ -//! [boa-web]: https://boajs.dev/ -//! [boa-playground]: https://boajs.dev/boa/playground/ - +//! +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_profiler/src/lib.rs b/boa_profiler/src/lib.rs index fe4859daf0..878f45aaae 100644 --- a/boa_profiler/src/lib.rs +++ b/boa_profiler/src/lib.rs @@ -1,30 +1,13 @@ //! 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. -//! - **`boa_icu_provider`** - Boa's ICU4X data provider. +//! This crate provides a code profiler for Boa. For more information, please +//! see Boa's page on [profiling][profiler-md]. //! //! [profiler-md]: https://github.com/boa-dev/boa/blob/main/docs/profiling.md -//! [boa-conformance]: https://boajs.dev/boa/test262/ -//! [boa-web]: https://boajs.dev/ -//! [boa-playground]: https://boajs.dev/boa/playground/ - +//! +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_runtime/src/lib.rs b/boa_runtime/src/lib.rs index 107f803794..bb7029054f 100644 --- a/boa_runtime/src/lib.rs +++ b/boa_runtime/src/lib.rs @@ -1,13 +1,5 @@ -//! Boa's **boa_runtime** crate contains an example runtime and basic runtime features and functionality for the `boa_engine` crate for -//! runtime implementors. -//! -//! # 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's **boa_runtime** crate contains an example runtime and basic runtime features and +//! functionality for the `boa_engine` crate for runtime implementors. //! //! # Example: Adding Web API's Console Object //! @@ -48,21 +40,7 @@ //! //! ``` //! -//! # Boa Crates -//! - **`boa_ast`** - Boa's ECMAScript Abstract Syntax Tree. -//! - **`boa_engine`** - Boa's implementation of ECMAScript builtin objects and execution. -//! - **`boa_gc`** - Boa's garbage collector. -//! - **`boa_interner`** - Boa's string interner. -//! - **`boa_parser`** - Boa's lexer and parser. -//! - **`boa_profiler`** - Boa's code profiler. -//! - **`boa_unicode`** - Boa's Unicode identifier. -//! - **`boa_icu_provider`** - Boa's ICU4X data provider. -//! -//! [ecma-402]: https://tc39.es/ecma402 -//! [boa-conformance]: https://boajs.dev/boa/test262/ -//! [boa-web]: https://boajs.dev/ -//! [boa-playground]: https://boajs.dev/boa/playground/ - +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_tester/src/main.rs b/boa_tester/src/main.rs index d9a0de470d..b95fe1e3bb 100644 --- a/boa_tester/src/main.rs +++ b/boa_tester/src/main.rs @@ -2,7 +2,8 @@ //! //! This crate will run the full ECMAScript test suite (Test262) and report compliance of the //! `boa` engine. - +//! +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_unicode/src/lib.rs b/boa_unicode/src/lib.rs index 1359003cc6..824370ae90 100644 --- a/boa_unicode/src/lib.rs +++ b/boa_unicode/src/lib.rs @@ -9,27 +9,9 @@ //! 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. -//! - **`boa_icu_provider`** - Boa's ICU4X data provider. -//! //! [uax31]: http://unicode.org/reports/tr31 -//! [boa-conformance]: https://boajs.dev/boa/test262/ -//! [boa-web]: https://boajs.dev/ -//! [boa-playground]: https://boajs.dev/boa/playground/ - +//! +#![doc = include_str!("../../ABOUT.md")] #![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" diff --git a/boa_wasm/src/lib.rs b/boa_wasm/src/lib.rs index cf5992c18c..fac3ab35ca 100644 --- a/boa_wasm/src/lib.rs +++ b/boa_wasm/src/lib.rs @@ -1,5 +1,6 @@ -//! A ECMAScript WASM implementation based on boa_engine. - +//! An ECMAScript WASM implementation based on boa_engine. +//! +#![doc = include_str!("../../ABOUT.md")] #![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"