Skip to content

Comments

Fix AST documentation formatting and remove pointless comments#12767

Closed
Copilot wants to merge 3 commits intomainfrom
copilot/fix-12728
Closed

Fix AST documentation formatting and remove pointless comments#12767
Copilot wants to merge 3 commits intomainfrom
copilot/fix-12728

Conversation

Copy link
Contributor

Copilot AI commented Aug 2, 2025

This PR addresses two specific documentation issues in the oxc_ast crate as outlined in the issue:

Fixed Issue #5: Inconsistent formatting

Problem: Type names and references were inconsistently formatted in doc comments.

Solution: Standardized all type references to use proper Rust doc formatting:

  • Fixed markdown-style links: [variable declarations](VariableDeclaration)[VariableDeclaration]
  • Added backticks to unformatted type names: Empty StatementEmptyStatement
  • Standardized 20+ statement and expression type comments for consistency

Examples of changes:

// Before
/// A single variable declaration in a list of [variable declarations](VariableDeclaration).
/// Empty Statement
/// Catch Clause in a [`try/catch` statement](TryStatement).

// After  
/// A single variable declaration in a list of variable declarations ([`VariableDeclaration`]).
/// `EmptyStatement`
/// Catch Clause in a [`TryStatement`].

Fixed Issue #4: Pointless comments

Problem: Many doc comments contained redundant text that just repeated what the struct fields already showed.

Solution: Removed "includes..." patterns that added no value beyond the type definition itself:

// Before
/// `foo = 1` in `let foo; foo = 1;`
///
/// Represents an assignment expression, which includes an operator, a target, and an expression.

// After
/// `foo = 1` in `let foo; foo = 1;`

Removed patterns:

  • "which includes an operator and an argument"
  • "which includes a left expression, an operator, and a right expression"
  • "which includes a test, a consequent, and an alternate"
  • "which includes an operator, a target, and an expression"
  • "which includes a binding, and an optional init expression"
  • "which includes a name and a binding"

All meaningful documentation (examples, syntax explanations, links to specs) was preserved. Only redundant field descriptions were removed.

Impact: 11 lines of pointless documentation removed, 27 lines improved for consistency. Documentation is now cleaner and more useful while maintaining all essential information.

Fixes #12728.


💬 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 2, 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.

Copilot AI and others added 2 commits August 2, 2025 16:08
Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
Copilot AI changed the title [WIP] Improve documentation of AST Fix AST documentation formatting and remove pointless comments Aug 2, 2025
Copilot AI requested a review from Boshen August 2, 2025 16:16
@Boshen Boshen closed this Aug 3, 2025
@Boshen Boshen deleted the copilot/fix-12728 branch August 3, 2025 03:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve documentation of AST

2 participants