Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

feat(require-jsdoc): add on-by-default skipInterveningOverloadedDeclarations option #1452

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
brettz9 wants to merge 7 commits into gajus:main
base: main
Choose a base branch
Loading
from brettz9:exempt-intervening-overloaded-functions
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion .README/rules/require-jsdoc.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,14 +113,30 @@ apply to any context; see `contexts` for line counts per context.
An optional message to add to the inserted JSDoc block. Defaults to the
empty string.

### `skipInterveningOverloadedDeclarations`

If `true`, will skip above uncommented overloaded functions to check
for a comment block (e.g., at the top of a set of overloaded functions).

If `false`, will force each overloaded function to be checked for a
comment block.

Defaults to `true`.

### `exemptOverloadedImplementations`

If set to `true` will avoid checking an overloaded function's implementation.

Defaults to `false`.

## Context and settings

|||
|---|---|
|Context|`ArrowFunctionExpression`, `ClassDeclaration`, `ClassExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
|Tags|N/A|
|Recommended|true|
|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`, `fixerMessage`|
|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`, `fixerMessage`, `skipInterveningOverloadedDeclarations`|

## Failing examples

Expand Down
2 changes: 1 addition & 1 deletion .README/rules/require-template.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Checks to see that `@template` tags are present for any detected type
parameters.

Currently checks `ClassDeclaration`, `FunctionDeclaration`,
Currently checks `ClassDeclaration`, `FunctionDeclaration`, `TSDeclareFunction`,
`TSInterfaceDeclaration` or `TSTypeAliasDeclaration` such as:

```ts
Expand Down
144 changes: 143 additions & 1 deletion docs/rules/require-jsdoc.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@
* [`enableFixer`](#user-content-require-jsdoc-options-enablefixer)
* [`minLineCount`](#user-content-require-jsdoc-options-minlinecount)
* [`fixerMessage`](#user-content-require-jsdoc-options-fixermessage)
* [`skipInterveningOverloadedDeclarations`](#user-content-require-jsdoc-options-skipinterveningoverloadeddeclarations)
* [`exemptOverloadedImplementations`](#user-content-require-jsdoc-options-exemptoverloadedimplementations)
* [Context and settings](#user-content-require-jsdoc-context-and-settings)
* [Failing examples](#user-content-require-jsdoc-failing-examples)
* [Passing examples](#user-content-require-jsdoc-passing-examples)
Expand Down Expand Up @@ -157,6 +159,26 @@ apply to any context; see `contexts` for line counts per context.
An optional message to add to the inserted JSDoc block. Defaults to the
empty string.

<a name="user-content-require-jsdoc-options-skipinterveningoverloadeddeclarations"></a>
<a name="require-jsdoc-options-skipinterveningoverloadeddeclarations"></a>
### <code>skipInterveningOverloadedDeclarations</code>

If `true`, will skip above uncommented overloaded functions to check
for a comment block (e.g., at the top of a set of overloaded functions).

If `false`, will force each overloaded function to be checked for a
comment block.

Defaults to `true`.

<a name="user-content-require-jsdoc-options-exemptoverloadedimplementations"></a>
<a name="require-jsdoc-options-exemptoverloadedimplementations"></a>
### <code>exemptOverloadedImplementations</code>

If set to `true` will avoid checking an overloaded function's implementation.

Defaults to `false`.

<a name="user-content-require-jsdoc-context-and-settings"></a>
<a name="require-jsdoc-context-and-settings"></a>
## Context and settings
Expand All @@ -166,7 +188,7 @@ empty string.
|Context|`ArrowFunctionExpression`, `ClassDeclaration`, `ClassExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
|Tags|N/A|
|Recommended|true|
|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`, `fixerMessage`|
|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`, `fixerMessage`, `skipInterveningOverloadedDeclarations`|

<a name="user-content-require-jsdoc-failing-examples"></a>
<a name="require-jsdoc-failing-examples"></a>
Expand Down Expand Up @@ -1041,6 +1063,56 @@ export class B implements A, B {
}
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["MethodDefinition"]}]
// Message: Missing JSDoc comment.

/**
* Test function with param.
* @param foo - Test param.
*/
function myFunction(foo: string): void;
/**
* Test function without param.
*/
function myFunction(): void;
function myFunction(foo?: string) {}
// "jsdoc/require-jsdoc": ["error"|"warn", {"skipInterveningOverloadedDeclarations":false}]
// Message: Missing JSDoc comment.

/**
* Test function without param.
*/
function myFunction(): void;
/**
* Test function with param.
* @param foo - Test param.
*/
function myFunction(foo: string): void;
function myFunction(foo?: string) {}
// "jsdoc/require-jsdoc": ["error"|"warn", {"skipInterveningOverloadedDeclarations":false}]
// Message: Missing JSDoc comment.

/**
* Test function with param.
* @param foo - Test param.
*/
function myFunction(foo: string): void;
function myFunction(): void;
/**
* Function implementation
* @param foo
*/
function myFunction(foo?: string) {}
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSDeclareFunction"],"exemptOverloadedImplementations":false,"skipInterveningOverloadedDeclarations":false}]
// Message: Missing JSDoc comment.

/**
* Test function with param.
* @param foo - Test param.
*/
function myFunction(foo: string): void;
function myFunction(): void;
function myFunction(foo?: string) {}
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSDeclareFunction"],"exemptOverloadedImplementations":true,"skipInterveningOverloadedDeclarations":false}]
// Message: Missing JSDoc comment.
````


Expand Down Expand Up @@ -1944,6 +2016,30 @@ export function arrayMap<Target, Source extends Array<unknown>>(data: Source, ca
export function arrayMap<Target, Source extends AnyArrayType>(data: Source, callback: MapCallback<Target, Source>): AnyArrayType<Target> {
return data.map(callback);
}
// "jsdoc/require-jsdoc": ["error"|"warn", {"skipInterveningOverloadedDeclarations":true}]

/**
* Array map function with overload for NonEmptyArray
* @example
* const data = [{value: 'value'}] as const;
* const result1: NonEmptyReadonlyArray<'value'> = arrayMap(data, (value) => value.value); // pick type from data
* const result2: NonEmptyReadonlyArray<'value'> = arrayMap<'value', typeof data>(data, (value) => value.value); // enforce output type
* @template Target - The type of the array to map to
* @template Source - The type of the array to map from
* @param {Source} data - The array to map
* @param {MapCallback<Target, Source>} callback - Callback function to map data from the array
* @returns {AnyArrayType<Target>} Mapped array
* @since v0.2.0
*/
export function arrayMap<Target, Source extends NonEmptyArray<unknown> | NonEmptyReadonlyArray<unknown>>(
data: Source,
callback: MapCallback<Target, Source>,
): NonEmptyArray<Target>;
export function arrayMap<Target, Source extends Array<unknown>>(data: Source, callback: MapCallback<Target, Source>): Array<Target>;
export function arrayMap<Target, Source extends AnyArrayType>(data: Source, callback: MapCallback<Target, Source>): AnyArrayType<Target> {
return data.map(callback);
}
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSDeclareFunction"],"exemptOverloadedImplementations":false,"skipInterveningOverloadedDeclarations":true}]

export interface A {
a: string;
Expand All @@ -1960,5 +2056,51 @@ export class B implements A {
}
}
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["MethodDefinition"]}]

/**
* Test function with param.
* @param foo - Test param.
*/
function myFunction(foo: string): void;
/**
* Test function without param.
*/
function myFunction(): void;
function myFunction(foo?: string) {}

/**
* Test function with param.
* @param foo - Test param.
*/
function myFunction(foo: string): void;
/**
* Test function without param.
*/
function myFunction(): void;
function myFunction(foo?: string) {}
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSDeclareFunction"],"exemptOverloadedImplementations":true,"skipInterveningOverloadedDeclarations":false}]

/**
* Test function with param.
* @param foo - Test param.
*/
export function myFunction(foo: string): void;
/**
* Test function without param.
*/
export function myFunction(): void;
export function myFunction(foo?: string) {}
// "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["TSDeclareFunction"],"exemptOverloadedImplementations":true,"skipInterveningOverloadedDeclarations":false}]

/**
*
*/
const quux = () => {
/**
*
*/
function myFunction(foo?: string) {}
};
// "jsdoc/require-jsdoc": ["error"|"warn", {"exemptOverloadedImplementations":true,"require":{"ArrowFunctionExpression":true}}]
````

11 changes: 11 additions & 0 deletions docs/rules/require-param.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1842,5 +1842,16 @@ const inner = (c: number, d: string): void => {
*/
function quux (a, b) {}
// "jsdoc/require-param": ["error"|"warn", {"ignoreWhenAllParamsMissing":true}]

/**
* Test function with param.
* @param foo - Test param.
*/
function myFunction(foo: string): void;
/**
* Test function without param.
*/
function myFunction(): void;
function myFunction(foo?: string) {}
````

14 changes: 13 additions & 1 deletion docs/rules/require-template.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Checks to see that `@template` tags are present for any detected type
parameters.

Currently checks `ClassDeclaration`, `FunctionDeclaration`,
Currently checks `ClassDeclaration`, `FunctionDeclaration`, `TSDeclareFunction`,
`TSInterfaceDeclaration` or `TSTypeAliasDeclaration` such as:

```ts
Expand Down Expand Up @@ -221,6 +221,18 @@ export default class <NumType> {
* @returns {[D, V | undefined]}
*/
// Message: Missing @template D

/**
* @param bar
* @param baz
* @returns
*/
function foo<T>(bar: T, baz: number): T;
function foo<T>(bar: T, baz: boolean): T;
function foo<T>(bar: T, baz: number | boolean): T {
return bar;
}
// Message: Missing @template T
````


Expand Down
26 changes: 13 additions & 13 deletions package.json
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"url": "http://gajus.com"
},
"dependencies": {
"@es-joy/jsdoccomment": "~0.53.0",
"@es-joy/jsdoccomment": "~0.56.0",
"are-docs-informative": "^0.0.2",
"comment-parser": "1.4.1",
"debug": "^4.4.1",
Expand All @@ -19,8 +19,8 @@
"description": "JSDoc linting rules for ESLint.",
"devDependencies": {
"@babel/cli": "^7.28.3",
"@babel/core": "^7.28.3",
"@babel/eslint-parser": "^7.28.0",
"@babel/core": "^7.28.4",
"@babel/eslint-parser": "^7.28.4",
"@babel/node": "^7.28.0",
"@babel/plugin-syntax-class-properties": "^7.12.13",
"@babel/plugin-transform-flow-strip-types": "^7.27.1",
Expand All @@ -29,7 +29,7 @@
"@es-joy/jsdoc-eslint-parser": "^0.22.0",
"@hkdobrev/run-if-changed": "^0.6.3",
"@semantic-release/commit-analyzer": "^13.0.1",
"@semantic-release/github": "^11.0.4",
"@semantic-release/github": "^11.0.5",
"@semantic-release/npm": "^12.0.2",
"@types/chai": "^5.2.2",
"@types/debug": "^4.1.12",
Expand All @@ -39,34 +39,34 @@
"@types/json-schema": "^7.0.15",
"@types/lodash.defaultsdeep": "^4.6.9",
"@types/mocha": "^10.0.10",
"@types/node": "^24.3.0",
"@types/semver": "^7.7.0",
"@types/node": "^24.3.1",
"@types/semver": "^7.7.1",
"@types/spdx-expression-parse": "^3.0.5",
"@typescript-eslint/types": "^8.41.0",
"@typescript-eslint/types": "^8.42.0",
"babel-plugin-add-module-exports": "^1.0.4",
"babel-plugin-istanbul": "^7.0.0",
"babel-plugin-istanbul": "^7.0.1",
"babel-plugin-transform-import-meta": "^2.3.3",
"c8": "^10.1.3",
"camelcase": "^8.0.0",
"chai": "^6.0.1",
"decamelize": "^6.0.1",
"eslint": "9.34.0",
"eslint": "9.35.0",
"eslint-config-canonical": "~45.0.0",
"gitdown": "^4.1.1",
"glob": "^11.0.3",
"globals": "^16.3.0",
"husky": "^9.1.7",
"jsdoc-type-pratt-parser": "^4.8.0",
"jsdoc-type-pratt-parser": "^5.1.0",
"json-schema": "^0.4.0",
"lint-staged": "^16.1.5",
"lint-staged": "^16.1.6",
"lodash.defaultsdeep": "^4.6.1",
"mocha": "^11.7.1",
"mocha": "^11.7.2",
"open-editor": "^5.1.0",
"replace": "^1.2.2",
"rimraf": "^6.0.1",
"semantic-release": "^24.2.7",
"typescript": "5.9.2",
"typescript-eslint": "^8.41.0"
"typescript-eslint": "^8.42.0"
},
"engines": {
"node": ">=20.11.0"
Expand Down
Loading
Loading

AltStyle によって変換されたページ (->オリジナル) /