Skip to content

Commit ebe5186

Browse files
SulimanAbdulrazzaqbrettz9
authored andcommitted
fix(require-jsdoc, convert-to-jsdoc-comments): throw a clear error for a comment in the contexts setting
These rules cannot apply the `comment` property of a context object, so silently ignoring it would change what they report. Throw an error that names the property and the fix instead of a TypeError, and drop the example that relied on the property being ignored.
1 parent f5ba20b commit ebe5186

8 files changed

Lines changed: 32 additions & 26 deletions

File tree

‎.README/settings.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -372,4 +372,8 @@ default contexts, including for function rules, so if, for example, you exclude
372372
`FunctionDeclaration` here, rules like `require-param` will not check
373373
function declarations.
374374

375+
A context object's `comment` property is not supported by `require-jsdoc` or
376+
`convert-to-jsdoc-comments`; these rules throw if the setting contains one, so
377+
give them their own `contexts` option to override the setting.
378+
375379
See the ["AST and Selectors"](./advanced.md#ast-and-selectors) section for more on this format.

‎docs/rules/check-param-names.md‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1360,8 +1360,5 @@ const emit = defineEmits<{
13601360
*/
13611361
submitField: [index: number];
13621362
}>();
1363-
1364-
/** @typedef {string} Foo */
1365-
// Settings: {"jsdoc":{"contexts":["any"]}}
13661363
````
13671364

‎docs/rules/require-jsdoc.md‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2237,10 +2237,5 @@ const obj = {
22372237
export default wrap(function () {
22382238
});
22392239
// "jsdoc/require-jsdoc": ["error"|"warn", {"publicOnly":true,"require":{"FunctionExpression":true}}]
2240-
2241-
/** Doc */
2242-
function quux () {
2243-
}
2244-
// Settings: {"jsdoc":{"contexts":[{"comment":"JsdocBlock","context":"FunctionDeclaration"}]}}
22452240
````
22462241

‎docs/settings.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -404,4 +404,8 @@ default contexts, including for function rules, so if, for example, you exclude
404404
`FunctionDeclaration` here, rules like `require-param` will not check
405405
function declarations.
406406

407+
A context object's `comment` property is not supported by `require-jsdoc` or
408+
`convert-to-jsdoc-comments`; these rules throw if the setting contains one, so
409+
give them their own `contexts` option to override the setting.
410+
407411
See the ["AST and Selectors"](./advanced.md#ast-and-selectors) section for more on this format.

‎src/jsdocUtils.js‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1707,7 +1707,15 @@ const getContextObject = (contexts, checkJsdoc, handler, convertAny) => {
17071707
lastIndex: idx,
17081708
selector: prop.context,
17091709
};
1710-
if (prop.comment && handler) {
1710+
if (prop.comment && !handler) {
1711+
throw new Error(
1712+
'The `comment` property of a `contexts` entry (e.g., one from ' +
1713+
'`settings.jsdoc.contexts`) is not supported by this rule; give the ' +
1714+
'rule its own `contexts` option instead.',
1715+
);
1716+
}
1717+
1718+
if (prop.comment) {
17111719
property = /** @type {string} */ (prop.context);
17121720
value = checkJsdoc.bind(
17131721
null,

‎test/jsdocUtils.js‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,20 @@ describe('jsdocUtils', () => {
9999
});
100100
});
101101
});
102+
describe('getContextObject()', () => {
103+
context('Context with `comment` and no handler', () => {
104+
it('should throw', () => {
105+
expect(() => {
106+
jsdocUtils.getContextObject([
107+
{
108+
comment: 'JsdocBlock',
109+
context: 'FunctionDeclaration',
110+
},
111+
], () => {});
112+
}).to.throw('The `comment` property of a `contexts` entry');
113+
});
114+
});
115+
});
102116
describe('mayBeUndefinedTypeTag()', () => {
103117
context('Missing tag', () => {
104118
it('should return `false` with a missing tag', () => {

‎test/rules/assertions/checkParamNames.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2468,6 +2468,7 @@ export default /** @type {import('../index.js').TestCases} */ ({
24682468
code: `
24692469
/** @typedef {string} Foo */
24702470
`,
2471+
ignoreReadme: true,
24712472
settings: {
24722473
jsdoc: {
24732474
contexts: [

‎test/rules/assertions/requireJsdoc.js‎

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7017,22 +7017,5 @@ function quux (foo) {
70177017
},
70187018
],
70197019
},
7020-
{
7021-
code: `
7022-
/** Doc */
7023-
function quux () {
7024-
}
7025-
`,
7026-
settings: {
7027-
jsdoc: {
7028-
contexts: [
7029-
{
7030-
comment: 'JsdocBlock',
7031-
context: 'FunctionDeclaration',
7032-
},
7033-
],
7034-
},
7035-
},
7036-
},
70377020
],
70387021
});

0 commit comments

Comments
 (0)