From ce5f54da34225f68b2e6d5f7be0afdaf411143dd Mon Sep 17 00:00:00 2001
From: Boshen <boshenc@gmail.com>
Date: Thu, 9 Nov 2023 17:11:18 +0800
Subject: [PATCH] update

---
 docs/contribute/formatter.md      |  3 +++
 docs/contribute/minifier.md       | 14 ++++++++++++++
 docs/contribute/parser.md         |  2 ++
 docs/contribute/performance.md    | 14 +++++++++++++-
 docs/contribute/resolver.md       |  5 +++++
 docs/contribute/rules.md          |  7 +++++++
 docs/contribute/transformer.md    |  3 +++
 docs/learn/architecture/parser.md | 23 ++++++++++++++++++++++
 docs/learn/references.md          |  7 +++++--
 docs/usage/linter.md              | 13 +++++++++++--
 docs/usage/parser.md              | 27 ++++++++++++++++++++++++++
 docs/usage/resolver.md            | 32 +++++++++++++++++++++++++++++++
 docusaurus.config.ts              |  3 ++-
 sidebars.ts                       |  2 +-
 14 files changed, 148 insertions(+), 7 deletions(-)
 create mode 100644 docs/usage/parser.md

diff --git a/docs/contribute/formatter.md b/docs/contribute/formatter.md
index 55431629bf..0a10977090 100644
--- a/docs/contribute/formatter.md
+++ b/docs/contribute/formatter.md
@@ -4,3 +4,6 @@ title: Formatter
 ---
 
 # Formatter
+
+While [prettier] has established itself as the de facto code formatter for JavaScript, there is a significant demand in the developer community for a less opinionated alternative. Recognizing this need, our ambition is to undertake research and development to create a new JavaScript formatter that offers increased flexibility and customization options.
+Unfortunately we are currently lacking the resources to do so.
diff --git a/docs/contribute/minifier.md b/docs/contribute/minifier.md
index 5570895c0a..35df7f9113 100644
--- a/docs/contribute/minifier.md
+++ b/docs/contribute/minifier.md
@@ -4,3 +4,17 @@ title: Minifier
 ---
 
 # Minifier
+
+JavaScript minification plays a crucial role in optimizing website performance as it reduces the amount of data sent to users,
+resulting in faster page loads.
+This holds tremendous economic value, particularly for e-commerce websites, where every second can equate to millions of dollars.
+
+However, existing minifiers typically require a trade-off between compression quality and speed.
+You have to choose between the slowest for the best compression or the fastest for less compression.
+But what if we could develop a faster minifier without compromising on compression?
+
+We are actively working on a prototype that aims to achieve this goal,
+by porting all test cases from well-known minifiers such as [google-closure-compiler], [terser], [esbuild], and [tdewolff-minify].
+
+Preliminary results indicate that we are on track to achieve our objectives.
+With the Oxc minifier, you can expect faster minification times without sacrificing compression quality.
diff --git a/docs/contribute/parser.md b/docs/contribute/parser.md
index 0020666b35..52e43b7bed 100644
--- a/docs/contribute/parser.md
+++ b/docs/contribute/parser.md
@@ -5,6 +5,8 @@ title: Parser
 
 # Parser
 
+We aim to be the fastest Rust-based ready-for-production parser.
+
 ## Conformance Tests
 
 ```bash
diff --git a/docs/contribute/performance.md b/docs/contribute/performance.md
index 0c11857621..8dab9f50d6 100644
--- a/docs/contribute/performance.md
+++ b/docs/contribute/performance.md
@@ -5,7 +5,19 @@ title: Performance
 
 # Performance Tuning
 
-## Mac Xcode Instruments
+## Compile Time
+
+While Rust has gained a reputation for its comparatively slower compilation speed,
+we have dedicated significant effort to fine-tune the Rust compilation speed.
+Our aim is to minimize any impact on your development workflow,
+ensuring that developing your own Oxc based tools remains a smooth and efficient experience.
+
+This is demonstrated by our [CI runs](https://github.com/web-infra-dev/oxc/actions/workflows/ci.yml?query=branch%3Amain),
+where warm runs complete in 5 minutes.
+
+## Profile
+
+### Mac Xcode Instruments
 
 Mac Xcode instruments can be used to produce a CPU profile.
 
diff --git a/docs/contribute/resolver.md b/docs/contribute/resolver.md
index 03914ccbea..65325219e4 100644
--- a/docs/contribute/resolver.md
+++ b/docs/contribute/resolver.md
@@ -4,3 +4,8 @@ title: Resolver
 ---
 
 # Resolver
+
+Module resolution plays a crucial role in JavaScript tooling, especially for tasks like multi-file analysis or bundling. However, it can often become a performance bottleneck.
+To address this, we are actively working on porting [enhanced-resolve].
+
+[eslint-plugin-import] will be our first application for the resolver, since it is currently a performance and complexity blocker for a lot of projects.
diff --git a/docs/contribute/rules.md b/docs/contribute/rules.md
index 71df2ea3e2..66402885d0 100644
--- a/docs/contribute/rules.md
+++ b/docs/contribute/rules.md
@@ -3,6 +3,13 @@ id: rules
 title: Rules
 ---
 
+- Check out some of the [good first issues](https://github.com/web-infra-dev/oxc/contribute) or ask us on [Discord][discord-url].
 - We welcome any form of contributions
 - We prefer smaller PRs to get things merged quickly
 - We recommend submitting stacked PRs via https://graphite.dev
+- APIs should be simple and well-documented.
+- All performance issues (runtime and compilation speed) are considered as bugs in this project.
+- Third-party dependencies should be minimal.
+- Monitor code coverage for unused code. Aim for 99% code coverage.
+- Embrace data-oriented design.
+- Prefer smaller PRs. Try [graphite.dev](https://graphite.dev).
diff --git a/docs/contribute/transformer.md b/docs/contribute/transformer.md
index cc3533f0a6..50fdba0f61 100644
--- a/docs/contribute/transformer.md
+++ b/docs/contribute/transformer.md
@@ -4,3 +4,6 @@ title: Transformer
 ---
 
 # Transformer
+
+A transformer is responsible for turning higher versions of ECMAScript to a lower version that can be used in older browsers.
+We are currently focusing on an esnext to es2015 transpiler. See the [umbrella issue](https://github.com/web-infra-dev/oxc/issues/974) for details.
diff --git a/docs/learn/architecture/parser.md b/docs/learn/architecture/parser.md
index a329c20819..7c74b86843 100644
--- a/docs/learn/architecture/parser.md
+++ b/docs/learn/architecture/parser.md
@@ -4,3 +4,26 @@ title: Parser
 ---
 
 # Parser
+
+Oxc maintains its own AST and parser, which is by far the fastest and most conformant JavaScript and TypeScript (including JSX and TSX) parser written in Rust.
+
+As the parser often represents a key performance bottleneck in JavaScript tooling,
+any minor improvements can have a cascading effect on our downstream tools.
+By developing our parser, we have the opportunity to explore and implement well-researched performance techniques.
+
+While many existing JavaScript tools rely on [estree] as their AST specification,
+a notable drawback is its abundance of ambiguous nodes.
+This ambiguity often leads to confusion during development with [estree].
+
+The Oxc AST differs slightly from the [estree] AST by removing ambiguous nodes and introducing distinct types.
+For example, instead of using a generic [estree] `Identifier`,
+the Oxc AST provides specific types such as `BindingIdentifier`, `IdentifierReference`, and `IdentifierName`.
+
+This clear distinction greatly enhances the development experience by aligning more closely with the ECMAScript specification.
+
+## How is it so fast
+
+- AST is allocated in a [memory arena](https://crates.io/crates/bumpalo) for fast AST memory allocation and deallocation
+- Short strings are inlined by [CompactString](https://crates.io/crates/compact_str)
+- No other heap allocations are done except the above two
+- Scope binding, symbol resolution and some syntax errors are not done in the parser, they are delegated to the semantic analyzer
diff --git a/docs/learn/references.md b/docs/learn/references.md
index f38ff45f30..c9b76cbd9b 100644
--- a/docs/learn/references.md
+++ b/docs/learn/references.md
@@ -3,9 +3,12 @@ id: references
 title: References
 ---
 
----
+## 📚 Learning Resources
 
-## title: References
+- My small tutorial on [how to write a JavaScript Parser in Rust](https://oxc-project.github.io/javascript-parser-in-rust)
+- My small article [Pursuit of Performance on Building a JavaScript Compiler](https://rustmagazine.org/issue-3/javascript-compiler/)
+- [Crafting Interpreters](https://craftinginterpreters.com)
+- [Andrew Kelley - Practical DOD](https://vimeo.com/649009599)
 
 ## Parsers (in active development)
 
diff --git a/docs/usage/linter.md b/docs/usage/linter.md
index bc54a0ce99..531772a0ce 100644
--- a/docs/usage/linter.md
+++ b/docs/usage/linter.md
@@ -7,17 +7,26 @@ title: Linter
 
 ## Features
 
-- Runs 50 -100 times faster than ESLint ([Benchmark](https://github.com/oxc-project/bench-javascript-linter)).
+- Runs 50 -100 times faster than ESLint, , and scales with the number of CPU cores ([Benchmark](https://github.com/oxc-project/bench-javascript-linter)).
 - No configuration is required for default usage
 - Reports errors and useless code by default
+- Convention over configuration
+
+## Adoptions
+
+![npm](https://img.shields.io/npm/dw/oxlint)
+
+- A 5M LOC typescript codebase previously running ESLint parallelized across 48 workers in CI taking 75 mins (12m wall time), it is now 8 seconds on a single worker. ([Source](https://twitter.com/boshen_c/status/1714827365136929029))
 
 ## Usage
 
+Install [oxlint](https://www.npmjs.com/package/oxlint) or via `npx`:
+
 ```bash
 npx oxlint@latest
 ```
 
-You may also use `yarn dlx`, `pnpm dlx`, `bunx` or `deno run` because `oxlint` is published to [npm](https://www.npmjs.com/package/oxlint).
+You may also use `yarn dlx`, `pnpm dlx`, `bunx` or `deno run` because `oxlint` is published to npm.
 
 ### Commands
 
diff --git a/docs/usage/parser.md b/docs/usage/parser.md
new file mode 100644
index 0000000000..0259622f57
--- /dev/null
+++ b/docs/usage/parser.md
@@ -0,0 +1,27 @@
+---
+id: parser
+title: Parser
+---
+
+# Parser
+
+## Features
+
+- 2x faster then swc parser
+- by far the fastest and most conformant JavaScript and TypeScript (including JSX and TSX) parser written in Rust
+
+[Benchmark](https://github.com/oxc-project/bench-javascript-parser-written-in-rust)
+
+## Usage in Rust
+
+- The umbrella crate [oxc][docs-oxc-url] exports all public crates from this repository.
+- The AST and parser crates [oxc_ast][docs-ast-url] and [oxc_parser][docs-parser-url] are production ready.
+
+## Usage in Node
+
+- Via napi: [@oxidation-compiler/napi][npm-napi]
+
+[docs-oxc-url]: https://docs.rs/oxc
+[docs-ast-url]: https://docs.rs/oxc_ast
+[docs-parser-url]: https://docs.rs/oxc_parser
+[npm-napi]: https://www.npmjs.com/package/@oxidation-compiler/napi
diff --git a/docs/usage/resolver.md b/docs/usage/resolver.md
index 03914ccbea..c9247e7c78 100644
--- a/docs/usage/resolver.md
+++ b/docs/usage/resolver.md
@@ -4,3 +4,35 @@ title: Resolver
 ---
 
 # Resolver
+
+Node.js Module Resolution.
+
+- Feature complete
+- All configuration options are aligned with enhanced-resolve
+
+## Rust Usage
+
+- https://docs.rs/oxc_resolver
+- https://crates.io/oxc_resolver
+
+## Example
+
+```rust
+use std::{env, path::PathBuf};
+
+use oxc_resolver::{ResolveOptions, Resolver};
+
+fn main() {
+    let path = env::args().nth(1).expect("require path");
+    let request = env::args().nth(2).expect("require request");
+    let path = PathBuf::from(path).canonicalize().unwrap();
+
+    println!("path: {path:?}");
+    println!("request: {request}");
+
+    match Resolver::new(ResolveOptions::default()).resolve(path, &request) {
+        Err(error) => println!("Error: {error}"),
+        Ok(resolution) => println!("Resolved: {}", resolution.full_path().to_string_lossy()),
+    }
+}
+```
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 6331be0612..7df23d63e5 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -4,7 +4,8 @@ import type * as Preset from '@docusaurus/preset-classic';
 
 const config: Config = {
   title: 'The JavaScript Oxidation Compiler',
-  tagline: 'A collection of JavaScript tooling written in Rust',
+  tagline:
+    'A collection of high-performance JavaScript tooling written in Rust',
   favicon:
     'https://raw.githubusercontent.com/oxc-project/oxc-assets/main/logo-round.png',
   url: 'https://oxc-project.github.io',
diff --git a/sidebars.ts b/sidebars.ts
index a41f60817c..5485009a31 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -1,7 +1,7 @@
 import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
 
 const sidebars: SidebarsConfig = {
-  usage: ['usage/linter', 'usage/resolver'],
+  usage: ['usage/linter', 'usage/parser', 'usage/resolver'],
   contribute: [
     'contribute/intro',
     'contribute/rules',