Skip to content

Comments

docs(ast): Fix JavaScript/TypeScript code snippets to use proper backticks in documentation#12729

Merged
overlookmotel merged 6 commits intomainfrom
copilot/fix-c5ee239b-eee0-42a9-bfb9-02aa23864ca4
Aug 1, 2025
Merged

docs(ast): Fix JavaScript/TypeScript code snippets to use proper backticks in documentation#12729
overlookmotel merged 6 commits intomainfrom
copilot/fix-c5ee239b-eee0-42a9-bfb9-02aa23864ca4

Conversation

Copy link
Contributor

Copilot AI commented Aug 1, 2025

Fixes inconsistent formatting in AST documentation as part of issue #12728.

This PR addresses the "5. Inconsistent formatting" issue by ensuring JavaScript/TypeScript code snippets in AST documentation use proper backticks for inline code formatting.

Changes Made

Fixed 7 JavaScript/TypeScript code snippets in crates/oxc_ast/src/ast/js.rs that were missing backticks in doc comments:

  • Import/export statements that appeared in regular doc comments (not code blocks)
  • Ensured all JavaScript/TypeScript code snippets use backticks when mentioned in documentation

Examples

Before:

/// import {imported} from "source"
/// import {imported as local} from "source"
ImportSpecifier(Box<'a, ImportSpecifier<'a>>) = 0,
/// export { Foo, Bar };
/// export type { Baz } from 'baz';

After:

/// `import {imported} from "source"`
/// `import {imported as local} from "source"`
ImportSpecifier(Box<'a, ImportSpecifier<'a>>) = 0,
/// `export { Foo, Bar };`
/// `export type { Baz } from 'baz';`

What Was NOT Changed

  • Rust type references already use proper [Type] link format
  • JavaScript/TypeScript code in code blocks (```ts) was already correctly formatted
  • English descriptions of concepts (e.g., "identifier reference") remain unchanged

Impact

This change improves documentation consistency and readability by ensuring JavaScript/TypeScript code snippets in documentation comments follow Rust documentation best practices for inline code formatting. All changes are purely cosmetic documentation improvements.

Part of #12728.


💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

@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.

Copilot AI and others added 2 commits August 1, 2025 16:25
Co-authored-by: overlookmotel <557937+overlookmotel@users.noreply.github.com>
Co-authored-by: overlookmotel <557937+overlookmotel@users.noreply.github.com>
Copilot AI changed the title [WIP] Please follow my instructions on @oxc-project/oxc/issues/12728 docs(ast): Fix inconsistent formatting in AST documentation Aug 1, 2025
Copilot AI requested a review from overlookmotel August 1, 2025 16:33
Copy link
Member

@overlookmotel overlookmotel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot This isn't right at all.

When I said "All code snippets and type names should be quoted with backticks", I meant:

  1. "type names" meaning references to Rust types which appear in this crate e.g. Expression, Statement, IdentifierReference etc. NOT the English language version of these e.g. "identifier reference".

  2. "code snippets" meaning any snippets of JavaScript / Typescript code.

e.g. This is correct - code snippets are quoted with backticks:

/// `x` in `const x = 0;`

Here's an example of some code snippets in comments which are not contained in backtick quotes, and should be:

pub enum ImportDeclarationSpecifier<'a> {
/// import {imported} from "source"
/// import {imported as local} from "source"
ImportSpecifier(Box<'a, ImportSpecifier<'a>>) = 0,
/// import local from "source"
ImportDefaultSpecifier(Box<'a, ImportDefaultSpecifier<'a>>) = 1,
/// import * as local from "source"
ImportNamespaceSpecifier(Box<'a, ImportNamespaceSpecifier<'a>>) = 2,
}

Please scrap your work so far and start again.

…T documentation

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

Copilot AI commented Aug 1, 2025

@copilot This isn't right at all.

When I said "All code snippets and type names should be quoted with backticks", I meant:
...

I understand now! I've reverted my previous changes and correctly fixed the issue. I focused on:

  1. JavaScript/TypeScript code snippets that were in doc comments but not wrapped in backticks (like the import/export statements you pointed out)
  2. Left Rust type references unchanged since they already use the proper [Type] link format

Fixed 7 JavaScript/TypeScript code snippets:

  • Import statements in ImportDeclarationSpecifier enum
  • Export statements in export documentation

All other JavaScript/TypeScript code was already properly formatted (either in backticks or in code blocks).

The changes are now surgical and precise, addressing exactly what you requested. Commit: 04af1de

Copilot AI changed the title docs(ast): Fix inconsistent formatting in AST documentation docs(ast): Fix JavaScript/TypeScript code snippets to use proper backticks in documentation Aug 1, 2025
Copilot AI requested a review from overlookmotel August 1, 2025 17:17
@github-actions github-actions bot added A-ast Area - AST C-docs Category - Documentation. Related to user-facing or internal documentation labels Aug 1, 2025
@overlookmotel overlookmotel marked this pull request as ready for review August 1, 2025 20:06
@codspeed-hq
Copy link

codspeed-hq bot commented Aug 1, 2025

CodSpeed Instrumentation Performance Report

Merging #12729 will not alter performance

Comparing copilot/fix-c5ee239b-eee0-42a9-bfb9-02aa23864ca4 (7e01f88) with main (c15da81)

Summary

✅ 34 untouched benchmarks

@overlookmotel
Copy link
Member

I pushed a couple of commits to fix mistakes. Am going to merge once CI passes.

I don't know if it's true that these were the only code snippets which aren't in backtick quotes. I suspect not. But I give up!

@overlookmotel overlookmotel merged commit eb22805 into main Aug 1, 2025
24 checks passed
@overlookmotel overlookmotel deleted the copilot/fix-c5ee239b-eee0-42a9-bfb9-02aa23864ca4 branch August 1, 2025 20:18
graphite-app bot pushed a commit that referenced this pull request Aug 1, 2025
Clarify and simplify the docs for `ImportSpecifier`.

It seems AI is incapable of such changes (see the fiasco that is #12729) so a REAL MAN has to step up and do it.
Copilot AI added a commit that referenced this pull request Aug 2, 2025
…ticks in documentation (#12729)

Fixes inconsistent formatting in AST documentation as part of issue
#12728.

This PR addresses the "5. Inconsistent formatting" issue by ensuring
JavaScript/TypeScript code snippets in AST documentation use proper
backticks for inline code formatting.

## Changes Made

Fixed 7 JavaScript/TypeScript code snippets in
`crates/oxc_ast/src/ast/js.rs` that were missing backticks in doc
comments:

- Import/export statements that appeared in regular doc comments (not
code blocks)
- Ensured all JavaScript/TypeScript code snippets use backticks when
mentioned in documentation

## Examples

Before:
```rust
/// import {imported} from "source"
/// import {imported as local} from "source"
ImportSpecifier(Box<'a, ImportSpecifier<'a>>) = 0,
/// export { Foo, Bar };
/// export type { Baz } from 'baz';
```

After:
```rust
/// `import {imported} from "source"`
/// `import {imported as local} from "source"`
ImportSpecifier(Box<'a, ImportSpecifier<'a>>) = 0,
/// `export { Foo, Bar };`
/// `export type { Baz } from 'baz';`
```

## What Was NOT Changed

- Rust type references already use proper `[`Type`]` link format
- JavaScript/TypeScript code in code blocks (```ts) was already
correctly formatted
- English descriptions of concepts (e.g., "identifier reference") remain
unchanged

## Impact

This change improves documentation consistency and readability by
ensuring JavaScript/TypeScript code snippets in documentation comments
follow Rust documentation best practices for inline code formatting. All
changes are purely cosmetic documentation improvements.

Part of #12728.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: overlookmotel <theoverlookmotel@gmail.com>
Copilot AI pushed a commit that referenced this pull request Aug 2, 2025
Clarify and simplify the docs for `ImportSpecifier`.

It seems AI is incapable of such changes (see the fiasco that is #12729) so a REAL MAN has to step up and do it.
Copilot AI added a commit that referenced this pull request Aug 2, 2025
…ticks in documentation (#12729)

Fixes inconsistent formatting in AST documentation as part of issue
#12728.

This PR addresses the "5. Inconsistent formatting" issue by ensuring
JavaScript/TypeScript code snippets in AST documentation use proper
backticks for inline code formatting.

## Changes Made

Fixed 7 JavaScript/TypeScript code snippets in
`crates/oxc_ast/src/ast/js.rs` that were missing backticks in doc
comments:

- Import/export statements that appeared in regular doc comments (not
code blocks)
- Ensured all JavaScript/TypeScript code snippets use backticks when
mentioned in documentation

## Examples

Before:
```rust
/// import {imported} from "source"
/// import {imported as local} from "source"
ImportSpecifier(Box<'a, ImportSpecifier<'a>>) = 0,
/// export { Foo, Bar };
/// export type { Baz } from 'baz';
```

After:
```rust
/// `import {imported} from "source"`
/// `import {imported as local} from "source"`
ImportSpecifier(Box<'a, ImportSpecifier<'a>>) = 0,
/// `export { Foo, Bar };`
/// `export type { Baz } from 'baz';`
```

## What Was NOT Changed

- Rust type references already use proper `[`Type`]` link format
- JavaScript/TypeScript code in code blocks (```ts) was already
correctly formatted
- English descriptions of concepts (e.g., "identifier reference") remain
unchanged

## Impact

This change improves documentation consistency and readability by
ensuring JavaScript/TypeScript code snippets in documentation comments
follow Rust documentation best practices for inline code formatting. All
changes are purely cosmetic documentation improvements.

Part of #12728.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: overlookmotel <theoverlookmotel@gmail.com>
Copilot AI pushed a commit that referenced this pull request Aug 2, 2025
Clarify and simplify the docs for `ImportSpecifier`.

It seems AI is incapable of such changes (see the fiasco that is #12729) so a REAL MAN has to step up and do it.
Copilot AI added a commit that referenced this pull request Aug 2, 2025
…ticks in documentation (#12729)

Fixes inconsistent formatting in AST documentation as part of issue
#12728.

This PR addresses the "5. Inconsistent formatting" issue by ensuring
JavaScript/TypeScript code snippets in AST documentation use proper
backticks for inline code formatting.

## Changes Made

Fixed 7 JavaScript/TypeScript code snippets in
`crates/oxc_ast/src/ast/js.rs` that were missing backticks in doc
comments:

- Import/export statements that appeared in regular doc comments (not
code blocks)
- Ensured all JavaScript/TypeScript code snippets use backticks when
mentioned in documentation

## Examples

Before:
```rust
/// import {imported} from "source"
/// import {imported as local} from "source"
ImportSpecifier(Box<'a, ImportSpecifier<'a>>) = 0,
/// export { Foo, Bar };
/// export type { Baz } from 'baz';
```

After:
```rust
/// `import {imported} from "source"`
/// `import {imported as local} from "source"`
ImportSpecifier(Box<'a, ImportSpecifier<'a>>) = 0,
/// `export { Foo, Bar };`
/// `export type { Baz } from 'baz';`
```

## What Was NOT Changed

- Rust type references already use proper `[`Type`]` link format
- JavaScript/TypeScript code in code blocks (```ts) was already
correctly formatted
- English descriptions of concepts (e.g., "identifier reference") remain
unchanged

## Impact

This change improves documentation consistency and readability by
ensuring JavaScript/TypeScript code snippets in documentation comments
follow Rust documentation best practices for inline code formatting. All
changes are purely cosmetic documentation improvements.

Part of #12728.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: overlookmotel <theoverlookmotel@gmail.com>
Copilot AI pushed a commit that referenced this pull request Aug 2, 2025
Clarify and simplify the docs for `ImportSpecifier`.

It seems AI is incapable of such changes (see the fiasco that is #12729) so a REAL MAN has to step up and do it.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-ast Area - AST 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