Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: gajus/eslint-plugin-jsdoc
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v37.8.2
Choose a base ref
...
head repository: gajus/eslint-plugin-jsdoc
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: v37.9.0
Choose a head ref
  • 2 commits
  • 7 files changed
  • 1 contributor

Commits on Feb 10, 2022

  1. chore: restore Node versions; fixes #801 

    Also:
1. Adds `engine-strict` flag to identify problematic dev. projects for testing on older Node.
2. Adds legacy-peer-deps for older combos of overwriting no-saves
3. Sets `eslint-plugin-mocha` to older version (not supporting Node 12)
4. Changes tests slightly to adjust for different `eslint-config-canonical` behavior
    @brettz9
    brettz9 committed Feb 10, 2022
    Copy the full SHA
    a5ad499 View commit details

Commits on Feb 11, 2022

  1. feat(check-values): add checking of kind 

    Also, updates jsdoccomment and devDeps.
    @brettz9
    brettz9 committed Feb 11, 2022
    Copy the full SHA
    eb92080 View commit details
Showing with 149 additions and 43 deletions.
  1. +4 −1 .README/rules/check-values.md
  2. +18 −8 .travis.yml
  3. +36 −10 README.md
  4. +3 −3 package.json
  5. +35 −0 src/rules/checkValues.js
  6. +9 −21 test/rules/assertions/checkExamples.js
  7. +44 −0 test/rules/assertions/checkValues.js
5 changes: 4 additions & 1 deletion .README/rules/check-values.md
View file
Original file line number Diff line number Diff line change
@@ -13,6 +13,9 @@ This rule checks the values for a handful of tags:
5. `@variation` - If `numericOnlyVariation` is set, will checks that there
is a value present, and that it is an integer (otherwise, jsdoc allows any
value).
6. `@kind` - Insists that it be one of the allowed values: 'class',
'constant', 'event', 'external', 'file', 'function', 'member', 'mixin',
'module', 'namespace', 'typedef',

#### Options

@@ -47,7 +50,7 @@ Whether to enable validation that `@variation` must be a number. Defaults to
|||
|---|---|
|Context|everywhere|
|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`|
|Tags|`@version`, `@since`, `@kind`, `@license`, `@author`, `@variation`|
|Recommended|true|
|Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`|
|Settings|`tagNamePreference`|
26 changes: 18 additions & 8 deletions .travis.yml
View file
Original file line number Diff line number Diff line change
@@ -2,28 +2,38 @@ os: linux
dist: xenial
language: node_js
node_js:
- "12.22.0"
- "14.17.0"
- "16"
# - "14.14.0"
# - "12.20.0"
install:
- echo "Avoid Travis's npm auto-install"
- npm install --legacy-peer-deps
before_script: >
node_version=$(node -v);
if [ ${ESLINT} = "7" ]; then
npm install --no-save "eslint@${ESLINT}" eslint-config-canonical@24.4.4
if [ ${node_version:1:2} = "16" ]; then
npm install --legacy-peer-deps --engine-strict --no-save "eslint@${ESLINT}" eslint-config-canonical@32.1.0 eslint-plugin-mocha@9
else
npm install --legacy-peer-deps --no-save "eslint@${ESLINT}" eslint-config-canonical@32.1.0 eslint-plugin-mocha@9
fi
else
npm install --no-save "eslint@${ESLINT}"
npm run lint
if [ ${node_version:1:2} = "16" ]; then
npm install --engine-strict --no-save "eslint@${ESLINT}"
npm run lint
else
npm install --legacy-peer-deps --no-save "eslint@${ESLINT}" eslint-config-canonical@32.1.0 eslint-plugin-mocha@9
fi
fi
notifications:
email: false
script:
- npm run test
- npm run build
env:
jobs:
- ESLINT=8
- ESLINT=7
- ESLINT=8
after_success:
- export NODE_ENV=production
- npm run build
46 changes: 36 additions & 10 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1259,33 +1259,33 @@ function quux () {}
// Message: @example error (semi): Missing semicolon.

/**
* @example const i = 5;
* quux2()
* @example const j = 5;
* quux2();
*/
function quux2 () {

}
// "jsdoc/check-examples": ["error"|"warn", {"matchingFileName":"../../jsdocUtils.js"}]
// Message: @example warning (id-length): Identifier name 'i' is too short (< 2).
// Message: @example warning (id-length): Identifier name 'j' is too short (< 2).

/**
* @example const i = 5;
* quux2()
* @example const k = 5;
* quux2();
*/
function quux2 () {

}
// "jsdoc/check-examples": ["error"|"warn", {"configFile":".eslintrc.json","matchingFileName":"../../jsdocUtils.js"}]
// Message: @example warning (id-length): Identifier name 'i' is too short (< 2).
// Message: @example warning (id-length): Identifier name 'k' is too short (< 2).

/**
* @example const i = 5;
* quux2()
* @example const m = 5;
* quux2();
*/
function quux2 () {

}
// Message: @example warning (id-length): Identifier name 'i' is too short (< 2).
// Message: @example warning (id-length): Identifier name 'm' is too short (< 2).

/**
* @example const i = 5;
@@ -5818,6 +5818,9 @@ This rule checks the values for a handful of tags:
5. `@variation` - If `numericOnlyVariation` is set, will checks that there
is a value present, and that it is an integer (otherwise, jsdoc allows any
value).
6. `@kind` - Insists that it be one of the allowed values: 'class',
'constant', 'event', 'external', 'file', 'function', 'member', 'mixin',
'module', 'namespace', 'typedef',

<a name="eslint-plugin-jsdoc-rules-check-values-options-8"></a>
#### Options
@@ -5857,7 +5860,7 @@ Whether to enable validation that `@variation` must be a number. Defaults to
|||
|---|---|
|Context|everywhere|
|Tags|`@version`, `@since`, `@license`, `@author`, `@variation`|
|Tags|`@version`, `@since`, `@kind`, `@license`, `@author`, `@variation`|
|Recommended|true|
|Options|`allowedAuthors`, `allowedLicenses`, `licensePattern`|
|Settings|`tagNamePreference`|
@@ -5881,6 +5884,22 @@ function quux (foo) {
}
// Message: Invalid JSDoc @version: "3.1".

/**
* @kind
*/
function quux (foo) {

}
// Message: Missing JSDoc @kind value.

/**
* @kind -3
*/
function quux (foo) {

}
// Message: Invalid JSDoc @kind: "-3"; must be one of: class, constant, event, external, file, function, member, mixin, module, namespace, typedef.

/**
* @variation -3
*/
@@ -6108,6 +6127,13 @@ function quux (foo) {
* @license MIT
*/
'use strict';
/**
* @kind function
*/
function quux (foo) {
}
````
6 changes: 3 additions & 3 deletions package.json
View file
Original file line number Diff line number Diff line change
@@ -5,7 +5,7 @@
"url": "http://gajus.com"
},
"dependencies": {
"@es-joy/jsdoccomment": "~0.18.0",
"@es-joy/jsdoccomment": "~0.19.0",
"comment-parser": "1.3.0",
"debug": "^4.3.3",
"escape-string-regexp": "^4.0.0",
@@ -17,15 +17,15 @@
"description": "JSDoc linting rules for ESLint.",
"devDependencies": {
"@babel/cli": "^7.17.0",
"@babel/core": "^7.17.0",
"@babel/core": "^7.17.2",
"@babel/eslint-parser": "^7.17.0",
"@babel/node": "^7.16.8",
"@babel/plugin-syntax-class-properties": "^7.12.13",
"@babel/plugin-transform-flow-strip-types": "^7.16.7",
"@babel/preset-env": "^7.16.11",
"@babel/register": "^7.17.0",
"@hkdobrev/run-if-changed": "^0.3.1",
"@typescript-eslint/parser": "^5.10.2",
"@typescript-eslint/parser": "^5.11.0",
"babel-plugin-add-module-exports": "^1.0.4",
"babel-plugin-istanbul": "^6.1.1",
"camelcase": "^6.3.0",
35 changes: 35 additions & 0 deletions src/rules/checkValues.js
View file
Original file line number Diff line number Diff line change
@@ -2,6 +2,20 @@ import semver from 'semver';
import spdxExpressionParse from 'spdx-expression-parse';
import iterateJsdoc from '../iterateJsdoc';

const allowedKinds = new Set([
'class',
'constant',
'event',
'external',
'file',
'function',
'member',
'mixin',
'module',
'namespace',
'typedef',
]);

export default iterateJsdoc(({
utils,
report,
@@ -31,6 +45,27 @@ export default iterateJsdoc(({
);
}
});

utils.forEachPreferredTag('kind', (jsdocParameter, targetTagName) => {
const kind = utils.getTagDescription(jsdocParameter).trim();
if (!kind) {
report(
`Missing JSDoc @${targetTagName} value.`,
null,
jsdocParameter,
);
} else if (!allowedKinds.has(kind)) {
report(
`Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}"; ` +
`must be one of: ${[
...allowedKinds,
].join(', ')}.`,
null,
jsdocParameter,
);
}
});

if (numericOnlyVariation) {
utils.forEachPreferredTag('variation', (jsdocParameter, targetTagName) => {
const variation = utils.getTagDescription(jsdocParameter).trim();
30 changes: 9 additions & 21 deletions test/rules/assertions/checkExamples.js
View file
Original file line number Diff line number Diff line change
@@ -364,8 +364,8 @@ export default {
{
code: `
/**
* @example const i = 5;
* quux2()
* @example const j = 5;
* quux2();
*/
function quux2 () {
@@ -374,11 +374,7 @@ export default {
errors: [
{
line: 3,
message: '@example warning (id-length): Identifier name \'i\' is too short (< 2).',
},
{
line: 4,
message: '@example error (semi): Missing semicolon.',
message: '@example warning (id-length): Identifier name \'j\' is too short (< 2).',
},
],
options: [
@@ -390,8 +386,8 @@ export default {
{
code: `
/**
* @example const i = 5;
* quux2()
* @example const k = 5;
* quux2();
*/
function quux2 () {
@@ -400,11 +396,7 @@ export default {
errors: [
{
line: 3,
message: '@example warning (id-length): Identifier name \'i\' is too short (< 2).',
},
{
line: 4,
message: '@example error (semi): Missing semicolon.',
message: '@example warning (id-length): Identifier name \'k\' is too short (< 2).',
},
],
options: [
@@ -417,8 +409,8 @@ export default {
{
code: `
/**
* @example const i = 5;
* quux2()
* @example const m = 5;
* quux2();
*/
function quux2 () {
@@ -427,11 +419,7 @@ export default {
errors: [
{
line: 3,
message: '@example warning (id-length): Identifier name \'i\' is too short (< 2).',
},
{
line: 4,
message: '@example error (semi): Missing semicolon.',
message: '@example warning (id-length): Identifier name \'m\' is too short (< 2).',
},
],
filename: 'test/rules/data/jsdocUtils.js',
44 changes: 44 additions & 0 deletions test/rules/assertions/checkValues.js
View file
Original file line number Diff line number Diff line change
@@ -32,6 +32,40 @@ export default {
},
],
},
{
code: `
/**
* @kind
*/
function quux (foo) {
}
`,
errors: [
{
line: 3,
message: 'Missing JSDoc @kind value.',
},
],
},
{
code: `
/**
* @kind -3
*/
function quux (foo) {
}
`,
errors: [
{
line: 3,
message: 'Invalid JSDoc @kind: "-3"; must be one of: class, ' +
'constant, event, external, file, function, member, mixin, ' +
'module, namespace, typedef.',
},
],
},
{
code: `
/**
@@ -458,5 +492,15 @@ export default {
'use strict';
`,
},
{
code: `
/**
* @kind function
*/
function quux (foo) {
}
`,
},
],
};