Skip to content

Comments

docs(rust): Add minimal documentation to example files in crates directory#12731

Merged
Boshen merged 5 commits intomainfrom
copilot/fix-b76e1a26-9aa9-47ca-9ef0-f6d2358244d6
Aug 2, 2025
Merged

docs(rust): Add minimal documentation to example files in crates directory#12731
Boshen merged 5 commits intomainfrom
copilot/fix-b76e1a26-9aa9-47ca-9ef0-f6d2358244d6

Conversation

Copy link
Contributor

Copilot AI commented Aug 1, 2025

This PR adds minimal documentation improvements to all example files across the Oxc crates to enhance their educational value without changing functionality.

Changes Made

  • Module-level documentation: Added comprehensive documentation blocks explaining the purpose and usage of each example
  • Function documentation: Added doc comments for main functions and helper functions
  • Inline comments: Added brief explanatory comments for key code sections
  • Usage instructions: Provided clear command-line usage examples and available options

Examples Enhanced

All example files across the following crates have been improved:

  • oxc_parser - Parser, TSX parser, and AST visitor examples
  • oxc_linter - Simple linter implementation
  • oxc_formatter - Code formatting example
  • oxc_semantic - Semantic analysis and CFG examples
  • oxc_codegen - Code generation and source map examples
  • oxc_minifier - Minification, DCE, and mangling examples
  • oxc_transformer - Code transformation example
  • oxc_isolated_declarations - TypeScript declaration generation
  • oxc_regular_expression - Regex parsing and visitor examples
  • oxc - Complete compiler pipeline example

Key Principles

  • Documentation-only changes: No new functionality or features added
  • Preserved behavior: All examples maintain their original functionality
  • Educational focus: Enhanced learning value for developers exploring Oxc internals
  • Consistent structure: Standardized documentation format across all examples

The examples now serve as both functional demonstrations and educational resources for developers working with Oxc.


💬 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
Copy link
Member

Boshen commented Aug 2, 2025

@copilot rebase then continue

Copy link
Contributor Author

Copilot AI commented Aug 2, 2025

@copilot rebase then continue

Rebased successfully and continued improving the remaining examples. Completed improvements for all examples across the crates directories including compiler, sourcemap, isolated_declarations, regex parsing/visitor, DCE, mangler, and CFG examples. All examples now feature comprehensive documentation, better error handling, educational comments, and consistent code organization. Commit: 24627da

Copilot AI changed the title [WIP] Refactor and improve all code in the examples sub-directory of crates directory. Refactor and improve all example files in the crates directory Aug 2, 2025
@github-actions github-actions bot added A-linter Area - Linter A-parser Area - Parser A-semantic Area - Semantic A-cli Area - CLI A-minifier Area - Minifier A-ast Area - AST A-transformer Area - Transformer / Transpiler A-codegen Area - Code Generation A-isolated-declarations Isolated Declarations A-editor Area - Editor and Language Server A-formatter Area - Formatter labels Aug 2, 2025
@Boshen Boshen force-pushed the copilot/fix-b76e1a26-9aa9-47ca-9ef0-f6d2358244d6 branch 2 times, most recently from bdc6c28 to 2dcec70 Compare August 2, 2025 12:21
@codspeed-hq
Copy link

codspeed-hq bot commented Aug 2, 2025

CodSpeed Instrumentation Performance Report

Merging #12731 will not alter performance

Comparing copilot/fix-b76e1a26-9aa9-47ca-9ef0-f6d2358244d6 (851b0a6) with main (1d910d5)

Summary

✅ 34 untouched benchmarks

@Boshen
Copy link
Member

Boshen commented Aug 2, 2025

@copilot just check failed, fix the compilation errors.

Copy link
Contributor Author

Copilot AI commented Aug 2, 2025

@copilot just check failed, fix the compilation errors.

Fixed the compilation errors. The issues were in two example files:

  1. isolated_declarations.rs - Fixed borrow checker errors by cloning diagnostics before calling .with_source_code()
  2. cfg.rs - Fixed move errors by capturing error counts before consuming vectors with .into_iter()

All examples now compile successfully. Commit: ba9e8a0

@Boshen Boshen changed the title Refactor and improve all example files in the crates directory refactor(rust): Refactor and improve all example files in the crates directory Aug 2, 2025
@github-actions github-actions bot added the C-cleanup Category - technical debt or refactoring. Solution not expected to change behavior label Aug 2, 2025
@Boshen
Copy link
Member

Boshen commented Aug 2, 2025

@copilot do not add new code. Only refactor and add documentation to these examples.

Copy link
Contributor Author

Copilot AI commented Aug 2, 2025

@copilot do not add new code. Only refactor and add documentation to these examples.

I've reverted all examples to their original state and made minimal documentation-only changes as requested. The changes now include only:

  • Module-level documentation explaining purpose and usage
  • Function documentation comments
  • Brief inline comments explaining key sections
  • No new functionality or code features added

All examples compile successfully and maintain their original behavior. Commit: 57450dd

Copilot AI changed the title refactor(rust): Refactor and improve all example files in the crates directory docs: Add minimal documentation to example files in crates directory Aug 2, 2025
Copilot AI and others added 3 commits August 2, 2025 21:22
Improve parser, linter, and formatter examples with better documentation and structure

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>

Improve semantic, minifier, and transformer examples with better documentation and structure

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>

Changes before error encountered

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>

Initial plan

Continue improving remaining examples: compiler, sourcemap, isolated_declarations, regex, dce, mangler, and cfg examples

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
…examples

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
@Boshen Boshen force-pushed the copilot/fix-b76e1a26-9aa9-47ca-9ef0-f6d2358244d6 branch from 57450dd to 2da4129 Compare August 2, 2025 13:23
Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
@Boshen Boshen force-pushed the copilot/fix-b76e1a26-9aa9-47ca-9ef0-f6d2358244d6 branch from 2da4129 to 1cd3155 Compare August 2, 2025 13:30
@Boshen
Copy link
Member

Boshen commented Aug 2, 2025

@copilot fix the reported cargo clippy issue for all the changed files.

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Aug 2, 2025

@copilot fix the reported cargo clippy issue for all the changed files.

Fixed clippy warnings in two example files by removing empty lines after doc comments. The issues were in linter.rs and parser.rs where there were empty lines between doc comments and function definitions. Commit: 851b0a6

@Boshen Boshen changed the title docs: Add minimal documentation to example files in crates directory docs(rust): Add minimal documentation to example files in crates directory Aug 2, 2025
@Boshen Boshen marked this pull request as ready for review August 2, 2025 13:57
@github-actions github-actions bot added the C-docs Category - Documentation. Related to user-facing or internal documentation label Aug 2, 2025
@Boshen Boshen merged commit 514322c into main Aug 2, 2025
25 of 26 checks passed
@Boshen Boshen deleted the copilot/fix-b76e1a26-9aa9-47ca-9ef0-f6d2358244d6 branch August 2, 2025 14:02
This was referenced Aug 3, 2025
camc314 added a commit that referenced this pull request Aug 6, 2025
## [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
## [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

Labels

A-ast Area - AST A-cli Area - CLI A-codegen Area - Code Generation A-editor Area - Editor and Language Server A-formatter Area - Formatter A-isolated-declarations Isolated Declarations A-linter Area - Linter A-minifier Area - Minifier A-parser Area - Parser A-semantic Area - Semantic A-transformer Area - Transformer / Transpiler C-cleanup Category - technical debt or refactoring. Solution not expected to change behavior C-docs Category - Documentation. Related to user-facing or internal documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants