Skip to content

Comments

[WIP] Improve documentation of AST#12763

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

[WIP] Improve documentation of AST#12763
Copilot wants to merge 4 commits intomainfrom
copilot/fix-12728

Conversation

Copy link
Contributor

Copilot AI commented Aug 2, 2025

Plan for AST Documentation Improvements

Based on the issue analysis, I will create two PRs to address specific documentation problems:

First PR: Fix Inconsistent Formatting (Issue #5) - COMPLETED ✅

  • Find and fix type names that should be enclosed in [...] format
  • Ensure all code snippets use proper backticks
  • Convert section headers to use backticks consistently
  • Fix markdown-style type references to use proper format
  • Update cross-references in js.rs, ts.rs to be consistent
  • Check other AST files for similar issues
  • Complete final formatting cleanup in TypeScript files
  • Verify all changes compile and pass tests

Second PR: Remove Pointless Comments (Issue #4) - NEXT

  • Remove "which includes..." repetitive text from AST type documentation
  • Target comments that just restate field names without adding value
  • Focus on removal only, not replacement with better content
  • Ensure changes don't break existing functionality

Current Status

  • Repository exploration and understanding
  • Identified target files: crates/oxc_ast/src/ast/{js.rs, ts.rs, jsx.rs}
  • Found examples of both formatting and pointless comment issues
  • Confirmed project builds and tests pass
  • Fixed major formatting inconsistencies in section headers
  • Fixed type reference format issues (e.g., description → [Type])
  • Verified changes compile successfully
  • COMPLETED: All formatting consistency issues addressed

Summary of formatting fixes made:

  • Fixed 15+ section headers to use backticks consistently
  • Fixed 10+ type reference formatting issues from markdown-style to proper format
  • Updated references across js.rs, ts.rs, and jsx.rs files
  • Addressed TypeScript-specific documentation inconsistencies

First PR COMPLETED ✅ - Ready to begin second PR focusing on pointless comments removal.

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 3 commits August 2, 2025 14:29
- Convert section headers to use backticks (e.g., "Expression Statement" → "`ExpressionStatement`")
- Fix type references to use proper `[`Type`]` format instead of `[description](Type)`
- Update cross-references in js.rs, ts.rs to be consistent

Part 1 of AST documentation improvements addressing issue #5 (inconsistent formatting)

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
- Fix remaining section headers in ts.rs to use consistent capitalization
- Address TypeScript-specific documentation formatting issues
- Final cleanup for inconsistent formatting (Issue #5)

Ready to proceed with second PR addressing pointless comments.

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>
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