Skip to content

docs(rust): Add comprehensive README.md documentation for all Rust crates #12706

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 5 commits into from
Aug 1, 2025
Merged

docs(rust): Add comprehensive README.md documentation for all Rust crates #12706

merged 5 commits into from
Aug 1, 2025

Conversation

Copy link
Contributor

Copilot AI commented Aug 1, 2025 •
edited
Loading

This PR adds comprehensive README.md files for all 20 Rust crates in the crates/ directory that were missing documentation, ensuring every crate now has clear documentation about its purpose and usage.

What was added

Created README.md files for the following crates:

  • oxc_allocator - High-performance bump allocator for AST nodes
  • oxc_ast - Abstract Syntax Tree definitions for JavaScript/TypeScript/JSX
  • oxc_ast_macros - Procedural macros for AST code generation
  • oxc_ast_visit - Visitor pattern implementations for AST traversal
  • oxc_cfg - Control Flow Graph construction and analysis
  • oxc_codegen - Code generation from AST back to source code
  • oxc_data_structures - Common data structures used across oxc
  • oxc_diagnostics - Error reporting and diagnostic utilities
  • oxc_estree - ESTree compatibility layer for serialization
  • oxc_isolated_declarations - TypeScript isolated declarations generator
  • oxc_linter - High-performance ESLint-compatible linter
  • oxc_macros - Macros for declaring lint rules
  • oxc_mangler - Variable name mangling for minification
  • oxc_napi - Node.js native API bindings
  • oxc_parser - JavaScript/TypeScript parser with full language support
  • oxc_semantic - Comprehensive semantic analysis and symbol resolution
  • oxc_span - Source position utilities and span management
  • oxc_syntax - Common JavaScript/TypeScript syntax definitions
  • oxc_transformer_plugins - Specialized transformation plugins
  • oxc_traverse - Advanced AST traversal with parent context

Documentation structure

Each README.md follows a consistent structure:

  • Title and brief description: Clear statement of the crate's purpose
  • Overview: Detailed explanation of what the crate does
  • Key features: Bullet points highlighting main capabilities
  • Architecture details: For complex crates, includes design principles and implementation notes

Benefits

  • Developer onboarding: New contributors can quickly understand each crate's role
  • API discovery: Clear documentation helps developers use oxc as a library
  • Architecture documentation: Explains the overall design and relationships between components
  • Consistency: All crates now have uniform documentation standards

The documentation covers the full spectrum from low-level utilities (allocator, spans) to high-level tools (parser, linter, semantic analysis) with appropriate technical depth for each audience.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

@graphite-app
Copy link
Contributor

graphite-app bot commented Aug 1, 2025

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

  • 0-merge - adds this PR to the back of the merge queue
  • hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

@Boshen
Add comprehensive README.md files for all missing oxc crates
594f783 
Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
Copilot AI changed the title [WIP] Add or improve README.md for all Rust crates in the crates directory. These README.md should have concise explaination on the purpose of the crate. Add architecture docs if necessary. Add comprehensive README.md documentation for all Rust crates Aug 1, 2025
Copilot AI requested a review from Boshen August 1, 2025 08:13
Copilot finished work on behalf of Boshen August 1, 2025 08:13
@github-actions github-actions bot added A-linter Area - Linter A-parser Area - Parser A-semantic Area - Semantic A-ast Area - AST A-codegen Area - Code Generation A-cfg Area - Control Flow Graph A-isolated-declarations Isolated Declarations labels Aug 1, 2025
@Boshen
Copy link
Member

Boshen commented Aug 1, 2025

@copilot remove code examples from these READMEs.

@Boshen
Remove code examples from all README files as requested
eee06e5 
Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Aug 1, 2025

@copilot remove code examples from these READMEs.

I've removed all code examples from the README files as requested. The changes preserve the documentation structure (overview, key features, architecture) while removing the usage sections with Rust code blocks. Commit: eee06e5

Copilot finished work on behalf of Boshen August 1, 2025 08:49
@Boshen Boshen changed the title Add comprehensive README.md documentation for all Rust crates docs(rust): Add comprehensive README.md documentation for all Rust crates Aug 1, 2025
@github-actions github-actions bot added the C-docs Category - Documentation. Related to user-facing or internal documentation label Aug 1, 2025
@Boshen Boshen marked this pull request as ready for review August 1, 2025 10:12
@Boshen Boshen merged commit de1de35 into main Aug 1, 2025
3 checks passed
@Boshen Boshen deleted the copilot/fix-4e5c837d-13b8-4bad-9dcc-cf8d88c05a27 branch August 1, 2025 10:13
This was referenced Aug 3, 2025
Merged
Merged
camc314 added a commit that referenced this pull request Aug 6, 2025
@oxc-bot @camc314
release(oxlint): v1.10.0 (#12846)
5f74a0b 
## [1.10.0] - 2025-08-06

### 🚀 Features

- 44ac5a1 linter: Add eslint/no-unassigned-vars rule (#11365) (yefan)
- ce6eeee linter: Add `eslint/prefer-destructuring` rule (#12721)
(yefan)
- 9b35600 linter/jsx-a11y: Add support for mapped attributes in label
association checks (#12805) (camc314)
- 5475075 vscode/language_server: Add `tsConfigPath` option (#12484)
(Sysix)
- a754f7a linter: Support `countVoidThis` option in `max-params` rule
(#12604) (yefan)

### 🐛 Bug Fixes

- 2c1dab6 linter/no-unassigned-vars: False positive with variables in
for loop (#12833) (camc314)
- 5a24574 linter/func-style: Fix more false positives (#12828) (camc314)
- 33a7320 linter/no-throw-literal: Fix unconditional recursion in
`could_be_error` (#12819) (camc314)
- a3aec6a linter/explicit-module-boundary-types: Debug assertion fail
with top level return (#12820) (camc314)
- 6efe457 linter/no-empty-function: Respect allow options for functions
and arrow functions (#12814) (camc314)
- 1c21c46 linter/new-cap: Fix panic with computed member expr (#12804)
(camc314)
- 45206dd linter: Apply fix span offset after fixing the section source
text (#12758) (Sysix)
- 1e97e35 linter/unicorn/prefer-structured-clone: Update Default
implementation for `PreferStructuredCloneConfig` (#12791) (camc314)
- d382159 linter/unicorn/prefer-object-from-entries: Update Default
implementation for `PreferObjectFromEntriesConfig` (#12790) (camc314)
- b07d29c linter/typescript/no-this-alias: Update Default implementation
for `NoThisAliasConfig` (#12789) (camc314)
- 0db34ab linter/react/jsx-filename-case: Update Default implementation
for `JsxFilenameExtensionConfig` (#12788) (camc314)
- ff84eff linter/jest/prefer-lowercase-title: Update Default
implementation for `PreferLowercaseTitleConfig` (#12787) (camc314)
- 5175c6d linter/jest/no-large-snapshots: Update Default implementation
for `NoLargeSnapshotsConfig` (#12786) (camc314)
- 0eaebcd linter/jest/no-deprecated-functions: Update Default
implementation for `JestConfig` (#12785) (camc314)
- 4265db7 linter/import/no-anonymous-default-export: Update Default
implementation for `NoAnonymousDefaultExport` config (#12784) (camc314)
- 6a360e3 linter/import/extensions: Update Default implementation for
ExtensionsConfig (#12783) (camc314)
- 42c8f29 linter: Default options for `eslint/no-else-return` (#12762)
(Sysix)
- 4eac511 linter: Default options for `eslint/no-unneeded-ternary`
(#12761) (Sysix)
- 9c01dbf linter: Default options for `eslint/new-cap` (#12760) (Sysix)
- b25406f linter/explicit-function-return-types: Update default values
in ExplicitFunctionReturnTypeConfig (#12718) (camc314)
- ce5876d parser: Validate inner expression of type assertions in
assignment targets (#12614) (camc314)
- 5383331 linter/explicit-mod-boundary-types: False positive with jsx
elements (#12678) (camc314)
- d0e99b5 linter/explicit-mod-boundary-types: False positive with call
expressions (#12677) (camc314)
- 525137e linter: Add missing options to no-inner-declarations (#12661)
(camc314)
- fc4a327 linter: No-unused-vars false positive with class property
initializers (#12660) (camc314)
- 6af8631 linter/no-unused-vars: False positive with chain expression
(#12609) (camc314)
- 744ef52 linter: Correct `array-type` handling of `default:
'array-simple'` (#12607) (yefan)

### 🚜 Refactor

- 3f37ed1 linter: Replace `lazy_static` with `std::sync::LazyLock`
(#12822) (Copilot)
- 69fd08d semantic: Improve unused label tracking and add debug
assertions (#12812) (camc314)
- 030e397 linter: Simplify parsing CLI args (#12802) (overlookmotel)
- c0e224a linter: Store `ExternalRuleId` in `OxlintOverrides` not raw
names (#12502) (camc314)
- 61587e4 linter: Correct comment (#12792) (overlookmotel)
- 5adcb98 linter: Use `u32` to keep track of last fixed source text
position (#12696) (Sysix)
- 77acc11 linter, transformer: Use `Scoping::symbol_is_unused` (#12666)
(overlookmotel)
- ecf1cff language_server: Simplify offset adjustment by using
`Message.move_offset` (#12647) (Sysix)
- 7695393 linter: Simplify offset adjustment by using
`Message.move_offset` (#12595) (Sysix)
- b36dc92 linter: Refactor large arrays to reduce binary size (#12603)
(Boshen)
- 3b9f1f0 linter: Update iter_outer_expressions to take AstNodes
reference (#12583) (camc314)

### 📚 Documentation

- e760fd4 linter: Complete linter rules documentation with missing "Why
is this bad?" sections (#12757) (Copilot)
- 514322c rust: Add minimal documentation to example files in crates
directory (#12731) (Copilot)
- 1d910d5 linter: Fix typescript/consistent-type-imports rule options to
match TypeScript ESLint (#12707) (Copilot)
- 45e2fe8 rust: Fix typos and grammar mistakes in Rust documentation
comments (#12715) (Copilot)
- 7660a88 linter: Improve linter rule documentation with "Why is this
bad?" sections and enhanced examples (#12711) (Copilot)
- de1de35 rust: Add comprehensive README.md documentation for all Rust
crates (#12706) (Copilot)

### ⚡ Performance

- 09ae2a9 linter: Eliminate unnecessary Iterator::collect() allocations
(#12776) (Copilot)
- 693673b linter: Reduce iterations when collecting directories for
nested configs (#12329) (overlookmotel)

### 🎨 Styling

- cacbd1e linter/no-empty-function: Order match arms consistently
(#12815) (camc314)
- c15da81 codegen, formatter, linter, minifier, transformer: Re-order
imports (#12725) (Copilot)

### 🧪 Testing

- 3957fcc linter/no-undef: Add test case for `TSImportType` (#12800)
(camc314)
- d8ccff7 oxlint: Add `Tester::test_fix` mehod (#12754) (Sysix)
- c6bfb8a linter: Add rule configuration consistency test (#12744)
(camc314)
- 2ceb835 linter: Fix offset for partical source texts (#12594) (Sysix)

Co-authored-by: camc314 <18101008+camc314@users.noreply.github.com>
taearls pushed a commit to taearls/oxc that referenced this pull request Aug 12, 2025
@oxc-bot @camc314 @taearls
release(oxlint): v1.10.0 (oxc-project#12846)
8ea20f5 
## [1.10.0] - 2025-08-06

### 🚀 Features

- 44ac5a1 linter: Add eslint/no-unassigned-vars rule (oxc-project#11365) (yefan)
- ce6eeee linter: Add `eslint/prefer-destructuring` rule (oxc-project#12721)
(yefan)
- 9b35600 linter/jsx-a11y: Add support for mapped attributes in label
association checks (oxc-project#12805) (camc314)
- 5475075 vscode/language_server: Add `tsConfigPath` option (oxc-project#12484)
(Sysix)
- a754f7a linter: Support `countVoidThis` option in `max-params` rule
(oxc-project#12604) (yefan)

### 🐛 Bug Fixes

- 2c1dab6 linter/no-unassigned-vars: False positive with variables in
for loop (oxc-project#12833) (camc314)
- 5a24574 linter/func-style: Fix more false positives (oxc-project#12828) (camc314)
- 33a7320 linter/no-throw-literal: Fix unconditional recursion in
`could_be_error` (oxc-project#12819) (camc314)
- a3aec6a linter/explicit-module-boundary-types: Debug assertion fail
with top level return (oxc-project#12820) (camc314)
- 6efe457 linter/no-empty-function: Respect allow options for functions
and arrow functions (oxc-project#12814) (camc314)
- 1c21c46 linter/new-cap: Fix panic with computed member expr (oxc-project#12804)
(camc314)
- 45206dd linter: Apply fix span offset after fixing the section source
text (oxc-project#12758) (Sysix)
- 1e97e35 linter/unicorn/prefer-structured-clone: Update Default
implementation for `PreferStructuredCloneConfig` (oxc-project#12791) (camc314)
- d382159 linter/unicorn/prefer-object-from-entries: Update Default
implementation for `PreferObjectFromEntriesConfig` (oxc-project#12790) (camc314)
- b07d29c linter/typescript/no-this-alias: Update Default implementation
for `NoThisAliasConfig` (oxc-project#12789) (camc314)
- 0db34ab linter/react/jsx-filename-case: Update Default implementation
for `JsxFilenameExtensionConfig` (oxc-project#12788) (camc314)
- ff84eff linter/jest/prefer-lowercase-title: Update Default
implementation for `PreferLowercaseTitleConfig` (oxc-project#12787) (camc314)
- 5175c6d linter/jest/no-large-snapshots: Update Default implementation
for `NoLargeSnapshotsConfig` (oxc-project#12786) (camc314)
- 0eaebcd linter/jest/no-deprecated-functions: Update Default
implementation for `JestConfig` (oxc-project#12785) (camc314)
- 4265db7 linter/import/no-anonymous-default-export: Update Default
implementation for `NoAnonymousDefaultExport` config (oxc-project#12784) (camc314)
- 6a360e3 linter/import/extensions: Update Default implementation for
ExtensionsConfig (oxc-project#12783) (camc314)
- 42c8f29 linter: Default options for `eslint/no-else-return` (oxc-project#12762)
(Sysix)
- 4eac511 linter: Default options for `eslint/no-unneeded-ternary`
(oxc-project#12761) (Sysix)
- 9c01dbf linter: Default options for `eslint/new-cap` (oxc-project#12760) (Sysix)
- b25406f linter/explicit-function-return-types: Update default values
in ExplicitFunctionReturnTypeConfig (oxc-project#12718) (camc314)
- ce5876d parser: Validate inner expression of type assertions in
assignment targets (oxc-project#12614) (camc314)
- 5383331 linter/explicit-mod-boundary-types: False positive with jsx
elements (oxc-project#12678) (camc314)
- d0e99b5 linter/explicit-mod-boundary-types: False positive with call
expressions (oxc-project#12677) (camc314)
- 525137e linter: Add missing options to no-inner-declarations (oxc-project#12661)
(camc314)
- fc4a327 linter: No-unused-vars false positive with class property
initializers (oxc-project#12660) (camc314)
- 6af8631 linter/no-unused-vars: False positive with chain expression
(oxc-project#12609) (camc314)
- 744ef52 linter: Correct `array-type` handling of `default:
'array-simple'` (oxc-project#12607) (yefan)

### 🚜 Refactor

- 3f37ed1 linter: Replace `lazy_static` with `std::sync::LazyLock`
(oxc-project#12822) (Copilot)
- 69fd08d semantic: Improve unused label tracking and add debug
assertions (oxc-project#12812) (camc314)
- 030e397 linter: Simplify parsing CLI args (oxc-project#12802) (overlookmotel)
- c0e224a linter: Store `ExternalRuleId` in `OxlintOverrides` not raw
names (oxc-project#12502) (camc314)
- 61587e4 linter: Correct comment (oxc-project#12792) (overlookmotel)
- 5adcb98 linter: Use `u32` to keep track of last fixed source text
position (oxc-project#12696) (Sysix)
- 77acc11 linter, transformer: Use `Scoping::symbol_is_unused` (oxc-project#12666)
(overlookmotel)
- ecf1cff language_server: Simplify offset adjustment by using
`Message.move_offset` (oxc-project#12647) (Sysix)
- 7695393 linter: Simplify offset adjustment by using
`Message.move_offset` (oxc-project#12595) (Sysix)
- b36dc92 linter: Refactor large arrays to reduce binary size (oxc-project#12603)
(Boshen)
- 3b9f1f0 linter: Update iter_outer_expressions to take AstNodes
reference (oxc-project#12583) (camc314)

### 📚 Documentation

- e760fd4 linter: Complete linter rules documentation with missing "Why
is this bad?" sections (oxc-project#12757) (Copilot)
- 514322c rust: Add minimal documentation to example files in crates
directory (oxc-project#12731) (Copilot)
- 1d910d5 linter: Fix typescript/consistent-type-imports rule options to
match TypeScript ESLint (oxc-project#12707) (Copilot)
- 45e2fe8 rust: Fix typos and grammar mistakes in Rust documentation
comments (oxc-project#12715) (Copilot)
- 7660a88 linter: Improve linter rule documentation with "Why is this
bad?" sections and enhanced examples (oxc-project#12711) (Copilot)
- de1de35 rust: Add comprehensive README.md documentation for all Rust
crates (oxc-project#12706) (Copilot)

### ⚡ Performance

- 09ae2a9 linter: Eliminate unnecessary Iterator::collect() allocations
(oxc-project#12776) (Copilot)
- 693673b linter: Reduce iterations when collecting directories for
nested configs (oxc-project#12329) (overlookmotel)

### 🎨 Styling

- cacbd1e linter/no-empty-function: Order match arms consistently
(oxc-project#12815) (camc314)
- c15da81 codegen, formatter, linter, minifier, transformer: Re-order
imports (oxc-project#12725) (Copilot)

### 🧪 Testing

- 3957fcc linter/no-undef: Add test case for `TSImportType` (oxc-project#12800)
(camc314)
- d8ccff7 oxlint: Add `Tester::test_fix` mehod (oxc-project#12754) (Sysix)
- c6bfb8a linter: Add rule configuration consistency test (oxc-project#12744)
(camc314)
- 2ceb835 linter: Fix offset for partical source texts (oxc-project#12594) (Sysix)

Co-authored-by: camc314 <18101008+camc314@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Boshen Boshen Awaiting requested review from Boshen

@overlookmotel overlookmotel Awaiting requested review from overlookmotel overlookmotel is a code owner

@Dunqing Dunqing Awaiting requested review from Dunqing Dunqing is a code owner

@camc314 camc314 Awaiting requested review from camc314 camc314 is a code owner

Assignees

@Boshen Boshen

Copilot code review Copilot

Labels

A-ast Area - AST A-cfg Area - Control Flow Graph A-codegen Area - Code Generation A-isolated-declarations Isolated Declarations A-linter Area - Linter A-parser Area - Parser A-semantic Area - Semantic C-docs Category - Documentation. Related to user-facing or internal documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Boshen