Skip to content

Commit

Permalink
fix: update jsdoccomment, comment-parser, debug
Browse files Browse the repository at this point in the history 
Causes adding of tags after single line description

Also:
- fix(`no-undefined-types`): only check genuine JSDoc blocks (begin with two and only two asterisks followed by whitespace)
- fix(`require-description-complete-sentence`): allow for newline
- fix(`require-example`, `require-property`, `sortTags`): ensures tag added only after description
- fix(`match-description`): allow for newline
- chore: update devDeps.
  • Loading branch information
@brettz9
brettz9 committed Mar 19, 2022
1 parent 3bade86 commit 63d18d2
Show file tree
Hide file tree
Showing 11 changed files with 63 additions and 15 deletions.
2 changes: 1 addition & 1 deletion .README/rules/match-description.md
View file
Expand Up @@ -6,7 +6,7 @@ The default is this basic expression to match English sentences (Support
for Unicode upper case may be added in a future version when it can be handled
by our supported Node versions):

``^([A-Z]|[`\\d_])[\\s\\S]*[.?!`]\\s*$``
``^\n?([A-Z`\\d_][\\s\\S]*[.?!`]\\s*)?$``

Applies to the jsdoc block description and `@description` (or `@desc`)
by default but the `tags` option (see below) may be used to match other tags.
Expand Down
10 changes: 9 additions & 1 deletion README.md
View file
Expand Up @@ -6608,7 +6608,7 @@ The default is this basic expression to match English sentences (Support
for Unicode upper case may be added in a future version when it can be handled
by our supported Node versions):

``^([A-Z]|[`\\d_])[\\s\\S]*[.?!`]\\s*$``
``^\n?([A-Z`\\d_][\\s\\S]*[.?!`]\\s*)?$``

Applies to the jsdoc block description and `@description` (or `@desc`)
by default but the `tags` option (see below) may be used to match other tags.
Expand Down Expand Up @@ -8528,6 +8528,8 @@ function quux () {

/* */

/** */

/* @custom */
// "jsdoc/no-bad-blocks": ["error"|"warn", {"ignore":["custom"]}]

Expand All @@ -8539,6 +8541,8 @@ function quux () {
function quux (foo) {

}

/***/
````


Expand Down Expand Up @@ -10049,6 +10053,10 @@ class Foo {

/****/

/* */

/*** */

/**
*
*/
Expand Down
14 changes: 7 additions & 7 deletions package.json
View file
Expand Up @@ -5,9 +5,9 @@
"url": "http://gajus.com"
},
"dependencies": {
"@es-joy/jsdoccomment": "~0.21.2",
"comment-parser": "1.3.0",
"debug": "^4.3.3",
"@es-joy/jsdoccomment": "~0.22.0",
"comment-parser": "1.3.1",
"debug": "^4.3.4",
"escape-string-regexp": "^4.0.0",
"esquery": "^1.4.0",
"regextras": "^0.8.0",
Expand All @@ -17,15 +17,15 @@
"description": "JSDoc linting rules for ESLint.",
"devDependencies": {
"@babel/cli": "^7.17.6",
"@babel/core": "^7.17.5",
"@babel/core": "^7.17.8",
"@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",
"@babel/register": "^7.17.7",
"@hkdobrev/run-if-changed": "^0.3.1",
"@typescript-eslint/parser": "^5.14.0",
"@typescript-eslint/parser": "^5.15.0",
"babel-plugin-add-module-exports": "^1.0.4",
"babel-plugin-istanbul": "^6.1.1",
"camelcase": "^6.3.0",
Expand All @@ -37,7 +37,7 @@
"gitdown": "^3.1.5",
"glob": "^7.2.0",
"husky": "^7.0.4",
"lint-staged": "^12.3.5",
"lint-staged": "^12.3.7",
"lodash.defaultsdeep": "^4.6.1",
"mocha": "^9.2.2",
"nyc": "^15.1.0",
Expand Down
10 changes: 7 additions & 3 deletions src/iterateJsdoc.js
View file
@@ -1,5 +1,3 @@
/* eslint-disable jsdoc/valid-types */

import {
getReducedASTNode,
getJSDocComment,
Expand Down Expand Up @@ -284,7 +282,13 @@ const getUtils = (

utils.addTag = (
targetTagName,
number = (jsdoc.tags[jsdoc.tags.length - 1]?.source[0]?.number ?? 0) + 1,
number = (jsdoc.tags[jsdoc.tags.length - 1]?.source[0]?.number ?? jsdoc.source.findIndex(({
tokens: {
tag,
},
}) => {
return tag;
}) - 1) + 1,
tokens = {},
) => {
jsdoc.source.splice(number, 0, {
Expand Down
2 changes: 1 addition & 1 deletion src/rules/matchDescription.js
View file
Expand Up @@ -2,7 +2,7 @@ import iterateJsdoc from '../iterateJsdoc';

// If supporting Node >= 10, we could loosen the default to this for the
// initial letter: \\p{Upper}
const matchDescriptionDefault = '^[A-Z`\\d_][\\s\\S]*[.?!`]\\s*$';
const matchDescriptionDefault = '^\n?([A-Z`\\d_][\\s\\S]*[.?!`]\\s*)?$';

const stringOrDefault = (value, userDefault) => {
return typeof value === 'string' ?
Expand Down
2 changes: 1 addition & 1 deletion src/rules/noUndefinedTypes.js
View file
Expand Up @@ -74,7 +74,7 @@ export default iterateJsdoc(({

const typedefDeclarations = context.getAllComments()
.filter((comment) => {
return comment.value.startsWith('*');
return (/^\*\s/u).test(comment.value);
})
.map((commentNode) => {
return parseComment(commentNode, '');
Expand Down
2 changes: 1 addition & 1 deletion src/rules/requireDescriptionCompleteSentence.js
View file
Expand Up @@ -74,7 +74,7 @@ const validateDescription = (
description, reportOrig, jsdocNode, abbreviationsRegex,
sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd,
) => {
if (!description) {
if (!description || (/^\n+$/u).test(description)) {
return false;
}

Expand Down
6 changes: 6 additions & 0 deletions test/rules/assertions/noBadBlocks.js
View file
Expand Up @@ -222,6 +222,9 @@ export default {
{
code: '/* */',
},
{
code: '/** */',
},
{
code: '/* @custom */',
options: [
Expand All @@ -244,5 +247,8 @@ export default {
}
`,
},
{
code: '/***/',
},
],
};
4 changes: 4 additions & 0 deletions test/rules/assertions/noUndefinedTypes.js
View file
Expand Up @@ -812,6 +812,10 @@ export default {
code: `
/****/
/* */
/*** */
/**
*
*/
Expand Down
8 changes: 8 additions & 0 deletions test/rules/assertions/requireExample.js
View file
Expand Up @@ -17,6 +17,7 @@ export default {
],
output: `
/**
*
* @example
*/
function quux () {
Expand Down Expand Up @@ -46,6 +47,7 @@ export default {
],
output: `
/**
*
* @example
*/
function quux (someParam) {
Expand All @@ -68,6 +70,7 @@ function quux () {
},
],
output: `/**
*
* @example
*/
function quux () {
Expand Down Expand Up @@ -157,6 +160,7 @@ function quux () {
],
output: `
/**
*
* @example
*/
class quux {
Expand Down Expand Up @@ -185,6 +189,7 @@ function quux () {
],
output: `
/**
*
* @example
*/
`,
Expand Down Expand Up @@ -212,6 +217,7 @@ function quux () {
],
output: `
/**
*
* @example
*/
function quux () {
Expand Down Expand Up @@ -241,6 +247,7 @@ function quux () {
output: `
class TestClass {
/**
*
* @example
*/
get Test() { }
Expand Down Expand Up @@ -291,6 +298,7 @@ function quux () {
output: `
class TestClass {
/**
*
* @example
*/
set Test(value) { }
Expand Down
18 changes: 18 additions & 0 deletions test/rules/assertions/requireParam.js
View file
Expand Up @@ -23,6 +23,7 @@ export default {
],
output: `
/**
*
* @param foo
*/
function quux (foo) {
Expand Down Expand Up @@ -54,6 +55,7 @@ export default {
],
output: `
/**
*
* @param foo
*/
function quux (foo) {
Expand Down Expand Up @@ -82,6 +84,7 @@ export default {
],
output: `
/**
*
* @param root0
* @param root0.foo
*/
Expand Down Expand Up @@ -209,6 +212,7 @@ export default {
],
output: `
/**
*
* @param root0
* @param root0.foo
*/
Expand Down Expand Up @@ -379,6 +383,7 @@ export default {
],
output: `
/**
*
* @param arg0
* @param arg0.foo
* @param arg1
Expand Down Expand Up @@ -425,6 +430,7 @@ export default {
],
output: `
/**
*
* @param arg
* @param arg.foo
* @param config0
Expand Down Expand Up @@ -472,6 +478,7 @@ export default {
],
output: `
/**
*
* @param arg
* @param arg.foo
*/
Expand Down Expand Up @@ -501,6 +508,7 @@ export default {
],
output: `
/**
*
* @param foo
* @param bar
*/
Expand Down Expand Up @@ -844,6 +852,7 @@ export default {
*/
class A {
/**
*
* @param foo
*/
quux (foo) {
Expand Down Expand Up @@ -883,6 +892,7 @@ export default {
*/
class A {
/**
*
* @param foo
*/
quux (foo) {
Expand Down Expand Up @@ -922,6 +932,7 @@ export default {
*/
class A {
/**
*
* @param foo
*/
quux (foo) {
Expand Down Expand Up @@ -961,6 +972,7 @@ export default {
*/
class A {
/**
*
* @param foo
*/
quux (foo) {
Expand Down Expand Up @@ -995,6 +1007,7 @@ export default {
*/
class A {
/**
*
* @param foo
*/
quux (foo) {
Expand Down Expand Up @@ -1083,6 +1096,7 @@ export default {
],
output: `
/**
*
* @param root0
* @param root0.bar
* @param root0.baz
Expand Down Expand Up @@ -1120,6 +1134,7 @@ export default {
],
output: `
/**
*
* @param foo
* @param root0
* @param root0.bar
Expand Down Expand Up @@ -1157,6 +1172,7 @@ export default {
],
output: `
/**
*
* @param root0
* @param root0."0"
* @param root0."1"
Expand Down Expand Up @@ -1189,6 +1205,7 @@ export default {
],
output: `
/**
*
* @param foo
*/
function quux (foo) {
Expand Down Expand Up @@ -1393,6 +1410,7 @@ export default {
declare class TestClass
{
/**
*
* @param id
*/
TestMethod(id);
Expand Down

2 comments on commit 63d18d2

@wojtekmaj
Copy link

Choose a reason for hiding this comment

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

What's the reason for pinning comment-parser version anyway?

@brettz9
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

There have been some subtle changes on occasion that might technically be fixed, but impact our approach. I track the project and frequently update eslint-plugin-jsdoc anyways.

Please sign in to comment.