Skip to content

Add documentation examples#141

Merged
Xvezda merged 1 commit into
masterfrom
feature/docs
Jun 24, 2025
Merged

Add documentation examples#141
Xvezda merged 1 commit into
masterfrom
feature/docs

Conversation

@Xvezda
Copy link
Copy Markdown
Owner

@Xvezda Xvezda commented Jun 24, 2025

No description provided.

Copilot AI review requested due to automatic review settings June 24, 2025 07:45
@Xvezda Xvezda merged commit 1749daf into master Jun 24, 2025
1 check passed
@Xvezda Xvezda deleted the feature/docs branch June 24, 2025 07:46
Copy link
Copy Markdown
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 illustrative TypeScript examples for the useBaseTypeOfLiteral and preferUnionType options in two rule documentation files.

  • Introduce examples showing base vs. literal type usage under useBaseTypeOfLiteral.
  • Demonstrate union vs. separate @throws tags under preferUnionType.

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File Description
docs/rules/no-undocumented-throws.md Added TS examples for useBaseTypeOfLiteral and preferUnionType.
docs/rules/check-throws-tag-type.md Added TS examples for useBaseTypeOfLiteral and preferUnionType.

Comment on lines +18 to +68
```ts
// useBaseTypeOfLiteral: true
/**
* @throws {string}
*/
function test() {
throw 'foo';
}

// useBaseTypeOfLiteral: false
/**
* @throws {'foo'}
*/
function test() {
throw 'foo';
}
```

### `preferUnionType`

Default: `true`

When more than one exception can be thrown, the types are added as a union type in the comment.
If set to `false`, each exception is written on its own line.

```ts
// preferUnionType: true
/**
* @throws {FooError | BarError}
*/
function test() {
if (Math.random() < 0.5) {
throw new FooError();
} else {
throw new BarError();
}
}

// preferUnionType: false
/**
* @throws {FooError}
* @throws {BarError}
*/
function test() {
if (Math.random() < 0.5) {
throw new FooError();
} else {
throw new BarError();
}
}
```
Copy link

Copilot AI Jun 24, 2025

Choose a reason for hiding this comment

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

[nitpick] These examples are identical to those in check-throws-tag-type.md. Consider consolidating shared examples or adding a cross-reference to avoid documentation drift.

Suggested change
```ts
// useBaseTypeOfLiteral: true
/**
* @throws {string}
*/
function test() {
throw 'foo';
}
// useBaseTypeOfLiteral: false
/**
* @throws {'foo'}
*/
function test() {
throw 'foo';
}
```
### `preferUnionType`
Default: `true`
When more than one exception can be thrown, the types are added as a union type in the comment.
If set to `false`, each exception is written on its own line.
```ts
// preferUnionType: true
/**
* @throws {FooError | BarError}
*/
function test() {
if (Math.random() < 0.5) {
throw new FooError();
} else {
throw new BarError();
}
}
// preferUnionType: false
/**
* @throws {FooError}
* @throws {BarError}
*/
function test() {
if (Math.random() < 0.5) {
throw new FooError();
} else {
throw new BarError();
}
}
```
For examples of how to use the `useBaseTypeOfLiteral` and `preferUnionType` options, refer to the documentation for the `check-throws-tag-type` rule [here](./check-throws-tag-type.md#examples).

Copilot uses AI. Check for mistakes.
When a literal value is thrown, document its base type rather than the literal type.
For example, for `throw "foo"`, insert `@throws {string}` instead of `@throws {"foo"}`.

```ts
Copy link

Copilot AI Jun 24, 2025

Choose a reason for hiding this comment

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

[nitpick] These examples mirror those in no-undocumented-throws.md. To improve maintainability, you might centralize these snippets or link between the two rule docs.

Copilot uses AI. Check for mistakes.
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.

2 participants