Skip to content

docs(linter): Add config docs for typescript/ban-ts-comment rule#16287

Merged
graphite-app[bot] merged 1 commit intomainfrom
ban-ts-comment-docs
Dec 1, 2025
Merged

docs(linter): Add config docs for typescript/ban-ts-comment rule#16287
graphite-app[bot] merged 1 commit intomainfrom
ban-ts-comment-docs

Conversation

@connorshea
Copy link
Member

@connorshea connorshea commented Nov 30, 2025

Part of #14743.

Generated docs (with the change to doc_page.rs to actually pull the doc comment above each config object, see #16288):

## Configuration

This rule allows you to specify how different TypeScript directive comments should be handled.

For each directive (`@ts-expect-error`, `@ts-ignore`, `@ts-nocheck`, `@ts-check`), you can choose one of the following options:
- `true`: Disallow the directive entirely, preventing its use in the entire codebase.
- `false`: Allow the directive without any restrictions.
- `"allow-with-description"`: Allow the directive only if it is followed by a description explaining its use. The description must meet the minimum length specified by `minimumDescriptionLength`.
- `{ "descriptionFormat": "<regex>" }`: Allow the directive only if the description matches the specified regex pattern.

For example:
\```json
{
"ts-expect-error": "allow-with-description",
"ts-ignore": true,
"ts-nocheck": { "descriptionFormat": "^: TS\\d+ because .+$" },
"ts-check": false,
"minimumDescriptionLength": 3
}
\```

This rule accepts a configuration object with the following properties:

### minimumDescriptionLength

type: `integer`

default: `3`

Minimum description length required when using directives with `allow-with-description`.

### ts-check

How to handle the `@ts-check` directive.

### ts-expect-error

How to handle the `@ts-expect-error` directive.


### ts-ignore

How to handle the `@ts-ignore` directive.


### ts-nocheck

How to handle the `@ts-nocheck` directive.

@connorshea connorshea requested a review from camc314 as a code owner November 30, 2025 02:22
Copilot AI review requested due to automatic review settings November 30, 2025 02:22
@graphite-app
Copy link
Contributor

graphite-app bot commented Nov 30, 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.

@github-actions github-actions bot added A-linter Area - Linter C-docs Category - Documentation. Related to user-facing or internal documentation labels Nov 30, 2025
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR adds configuration documentation for the typescript/ban-ts-comment lint rule by adding struct-level and field-level doc comments, JsonSchema derives, and serde attributes to enable automatic schema generation. The PR also refactors the from_configuration method to be more concise and adds a test case for block comment support.

Key changes:

  • Added comprehensive documentation comments to BanTsCommentConfig struct explaining configuration options
  • Added JsonSchema derive and serde attributes (rename_all, rename) for schema generation
  • Refactored from_configuration method to extract config object once and reuse it
  • Added test case for /* @ts-ignore */ block comment syntax

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@codspeed-hq
Copy link

codspeed-hq bot commented Nov 30, 2025

CodSpeed Performance Report

Merging #16287 will not alter performance

Comparing ban-ts-comment-docs (ea596c2) with main (71271ee)

Summary

✅ 4 untouched
⏩ 41 skipped1

Footnotes

  1. 41 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

@camc314 camc314 added the 0-merge Merge with Graphite Merge Queue label Dec 1, 2025
@camc314 camc314 self-assigned this Dec 1, 2025
Copy link
Contributor

camc314 commented Dec 1, 2025

Merge activity

…16287)

Part of #14743.

Generated docs (with the change to `doc_page.rs` to actually pull the doc comment above each config object, see #16288):

```md
## Configuration

This rule allows you to specify how different TypeScript directive comments should be handled.

For each directive (`@ts-expect-error`, `@ts-ignore`, `@ts-nocheck`, `@ts-check`), you can choose one of the following options:
- `true`: Disallow the directive entirely, preventing its use in the entire codebase.
- `false`: Allow the directive without any restrictions.
- `"allow-with-description"`: Allow the directive only if it is followed by a description explaining its use. The description must meet the minimum length specified by `minimumDescriptionLength`.
- `{ "descriptionFormat": "<regex>" }`: Allow the directive only if the description matches the specified regex pattern.

For example:
\```json
{
"ts-expect-error": "allow-with-description",
"ts-ignore": true,
"ts-nocheck": { "descriptionFormat": "^: TS\\d+ because .+$" },
"ts-check": false,
"minimumDescriptionLength": 3
}
\```

This rule accepts a configuration object with the following properties:

### minimumDescriptionLength

type: `integer`

default: `3`

Minimum description length required when using directives with `allow-with-description`.

### ts-check

How to handle the `@ts-check` directive.

### ts-expect-error

How to handle the `@ts-expect-error` directive.

### ts-ignore

How to handle the `@ts-ignore` directive.

### ts-nocheck

How to handle the `@ts-nocheck` directive.
```
@graphite-app graphite-app bot force-pushed the ban-ts-comment-docs branch from ea596c2 to 7613957 Compare December 1, 2025 09:14
@graphite-app graphite-app bot merged commit 7613957 into main Dec 1, 2025
20 checks passed
@graphite-app graphite-app bot deleted the ban-ts-comment-docs branch December 1, 2025 09:19
@graphite-app graphite-app bot removed the 0-merge Merge with Graphite Merge Queue label Dec 1, 2025
graphite-app bot pushed a commit that referenced this pull request Dec 5, 2025
…nfig docs (#16288)

This is necessary for a proper config object explanation to be provided on some complex rules, and is just generally useful. I'm assuming we do not want this to show up on rules that only have the link to the original source, so I updated various rules accordingly.

For example, from #16287:

```md
## Configuration

This rule allows you to specify how different TypeScript directive comments should be handled.

For each directive (`@ts-expect-error`, `@ts-ignore`, `@ts-nocheck`, `@ts-check`), you can choose one of the following options:
- `true`: Disallow the directive entirely, preventing its use in the entire codebase.
- `false`: Allow the directive without any restrictions.
- `"allow-with-description"`: Allow the directive only if it is followed by a description explaining its use. The description must meet the minimum length specified by `minimumDescriptionLength`.
- `{ "descriptionFormat": "<regex>" }`: Allow the directive only if the description matches the specified regex pattern.

For example:
\```json
{
"ts-expect-error": "allow-with-description",
"ts-ignore": true,
"ts-nocheck": { "descriptionFormat": "^: TS\\d+ because .+$" },
"ts-check": false,
"minimumDescriptionLength": 3
}
\```

This rule accepts a configuration object with the following properties:

### minimumDescriptionLength

type: `integer`

default: `3`

Minimum description length required when using directives with `allow-with-description`.

### ts-check

How to handle the `@ts-check` directive.

### ts-expect-error

How to handle the `@ts-expect-error` directive.

### ts-ignore

How to handle the `@ts-ignore` directive.

### ts-nocheck

How to handle the `@ts-nocheck` directive.
```
taearls pushed a commit to taearls/oxc that referenced this pull request Dec 11, 2025
…xc-project#16287)

Part of oxc-project#14743.

Generated docs (with the change to `doc_page.rs` to actually pull the doc comment above each config object, see oxc-project#16288):

```md
## Configuration

This rule allows you to specify how different TypeScript directive comments should be handled.

For each directive (`@ts-expect-error`, `@ts-ignore`, `@ts-nocheck`, `@ts-check`), you can choose one of the following options:
- `true`: Disallow the directive entirely, preventing its use in the entire codebase.
- `false`: Allow the directive without any restrictions.
- `"allow-with-description"`: Allow the directive only if it is followed by a description explaining its use. The description must meet the minimum length specified by `minimumDescriptionLength`.
- `{ "descriptionFormat": "<regex>" }`: Allow the directive only if the description matches the specified regex pattern.

For example:
\```json
{
"ts-expect-error": "allow-with-description",
"ts-ignore": true,
"ts-nocheck": { "descriptionFormat": "^: TS\\d+ because .+$" },
"ts-check": false,
"minimumDescriptionLength": 3
}
\```

This rule accepts a configuration object with the following properties:

### minimumDescriptionLength

type: `integer`

default: `3`

Minimum description length required when using directives with `allow-with-description`.

### ts-check

How to handle the `@ts-check` directive.

### ts-expect-error

How to handle the `@ts-expect-error` directive.

### ts-ignore

How to handle the `@ts-ignore` directive.

### ts-nocheck

How to handle the `@ts-nocheck` directive.
```
taearls pushed a commit to taearls/oxc that referenced this pull request Dec 11, 2025
…nfig docs (oxc-project#16288)

This is necessary for a proper config object explanation to be provided on some complex rules, and is just generally useful. I'm assuming we do not want this to show up on rules that only have the link to the original source, so I updated various rules accordingly.

For example, from oxc-project#16287:

```md
## Configuration

This rule allows you to specify how different TypeScript directive comments should be handled.

For each directive (`@ts-expect-error`, `@ts-ignore`, `@ts-nocheck`, `@ts-check`), you can choose one of the following options:
- `true`: Disallow the directive entirely, preventing its use in the entire codebase.
- `false`: Allow the directive without any restrictions.
- `"allow-with-description"`: Allow the directive only if it is followed by a description explaining its use. The description must meet the minimum length specified by `minimumDescriptionLength`.
- `{ "descriptionFormat": "<regex>" }`: Allow the directive only if the description matches the specified regex pattern.

For example:
\```json
{
"ts-expect-error": "allow-with-description",
"ts-ignore": true,
"ts-nocheck": { "descriptionFormat": "^: TS\\d+ because .+$" },
"ts-check": false,
"minimumDescriptionLength": 3
}
\```

This rule accepts a configuration object with the following properties:

### minimumDescriptionLength

type: `integer`

default: `3`

Minimum description length required when using directives with `allow-with-description`.

### ts-check

How to handle the `@ts-check` directive.

### ts-expect-error

How to handle the `@ts-expect-error` directive.

### ts-ignore

How to handle the `@ts-ignore` directive.

### ts-nocheck

How to handle the `@ts-nocheck` directive.
```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-linter Area - Linter C-docs Category - Documentation. Related to user-facing or internal documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants