Merge branch 'master' into add-more-type-checks-to-valid-types

brettz9 · brettz9 · commit efa0e68e7cee · 2019-07-06T18:36:35.000+08:00
* master:
  feat(match-description): allow `description` and `desc` tags to be matched for validation
  refactor: use template string when appropriate
diff --git a/.README/rules/match-description.md b/.README/rules/match-description.md
@@ -82,6 +82,6 @@ Overrides the default contexts (see below).
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A by default but see `tags` options|
 |Settings||
-|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `mainDescription`, `matchDescription`|
+|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return', 'description', 'desc'), `mainDescription`, `matchDescription`|
 
 <!-- assertions matchDescription -->
diff --git a/README.md b/README.md
@@ -2495,7 +2495,7 @@ Overrides the default contexts (see below).
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A by default but see `tags` options|
 |Settings||
-|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `mainDescription`, `matchDescription`|
+|Options|`contexts`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return', 'description', 'desc'), `mainDescription`, `matchDescription`|
 
 The following patterns are considered problems:
 
@@ -2571,6 +2571,17 @@ function quux (foo) {
 // Options: [{"tags":{"param":true}}]
 // Message: JSDoc description does not satisfy the regex pattern.
 
+/**
+ * Foo.
+ *
+ * @description foo foo.
+ */
+function quux (foo) {
+
+}
+// Options: [{"tags":{"description":true}}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
 /**
  * Foo
  *
@@ -2695,6 +2706,16 @@ function quux () {
 // Options: [{"tags":{"param":"[А-Я][А-я]+\\."}}]
 // Message: JSDoc description does not satisfy the regex pattern.
 
+/**
+ * @description notRet
+ * @returns Тест.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"description":"[А-Я][А-я]+\\."}}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
 /**
  * foo.
  */
@@ -2784,6 +2805,15 @@ function quux () {
 }
 // Options: [{"tags":{"returns":"[А-Я][А-я]+\\."}}]
 
+/**
+ * @param notRet
+ * @description Тест.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"description":"[А-Я][А-я]+\\."}}]
+
 /**
  * Foo
  * bar.
@@ -2800,6 +2830,14 @@ function quux () {
 }
 // Options: [{"tags":{"returns":true}}]
 
+/**
+ * @description Foo bar.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"description":true}}]
+
 /**
  * Foo. {@see Math.sin}.
  */
@@ -2921,6 +2959,14 @@ const q = {
 
 };
 // Options: [{"contexts":[]}]
+
+/**
+ * @description foo.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"param":true}}]
 ````
 
 
diff --git a/src/bin/readme-assertions.js b/src/bin/readme-assertions.js
@@ -30,15 +30,15 @@ const formatCodeSnippet = (setup) => {
   paragraphs.push(trimCode(setup.code));
 
   if (setup.settings) {
-    paragraphs.push('// Settings: ' + JSON.stringify(setup.settings));
+    paragraphs.push(`// Settings: ${JSON.stringify(setup.settings)}`);
   }
 
   if (setup.options) {
-    paragraphs.push('// Options: ' + JSON.stringify(setup.options));
+    paragraphs.push(`// Options: ${JSON.stringify(setup.options)}`);
   }
 
   if (setup.errors) {
-    paragraphs.push('// Message: ' + setup.errors[0].message);
+    paragraphs.push(`// Message: ${setup.errors[0].message}`);
   }
 
   return paragraphs.join('\n');
@@ -74,7 +74,7 @@ const updateDocuments = (assertions) => {
     const ruleAssertions = assertions[ruleName];
 
     if (!ruleAssertions) {
-      throw new Error('No assertions available for rule "' + ruleName + '".');
+      throw new Error(`No assertions available for rule "${ruleName}".`);
     }
 
     return 'The following patterns are considered problems:\n\n````js\n' + ruleAssertions.invalid.join('\n\n') +
diff --git a/src/exportParser.js b/src/exportParser.js
@@ -77,7 +77,7 @@ const getSymbol = function (node, globals, scope, opt) {
     }
     */
     /* istanbul ignore next */
-    debug('MemberExpression: Missing property ' + node.property.name);
+    debug(`MemberExpression: Missing property ${node.property.name}`);
 
     /* istanbul ignore next */
     return null;
diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -5,7 +5,7 @@ import getJSDocComment from './eslint/getJSDocComment';
 
 const parseComment = (commentNode, indent) => {
   // Preserve JSDoc block start/end indentation.
-  return commentParser(indent + '/*' + commentNode.value + indent + '*/', {
+  return commentParser(`${indent}/*${commentNode.value}${indent}*/`, {
     // @see https://github.com/yavorskiy/comment-parser/issues/21
     parsers: [
       commentParser.PARSERS.parse_tag,
diff --git a/src/jsdocUtils.js b/src/jsdocUtils.js
@@ -491,7 +491,7 @@ const hasReturnValue = (node, context, ignoreAsync) => {
     }
   }
   /* istanbul ignore next */
-  throw new Error('Unknown element ' + node.type);
+  throw new Error(`Unknown element ${node.type}`);
 };
 
 /** @param {string} tag */
diff --git a/src/rules/checkAlignment.js b/src/rules/checkAlignment.js
@@ -24,7 +24,7 @@ export default iterateJsdoc(({
         // Ignore the first line and all lines not starting with `*`
         const ignored = !index || line.split('*')[0].trim().length;
 
-        return ignored ? line : indent + ' ' + _.trimStart(line);
+        return ignored ? line : `${indent} ${_.trimStart(line)}`;
       })
       .join('\n');
 
diff --git a/src/rules/checkExamples.js b/src/rules/checkExamples.js
@@ -66,7 +66,7 @@ export default iterateJsdoc(({
   utils.forEachPreferredTag('example', (tag, targetTagName) => {
     // If a space is present, we should ignore it
     const initialTag = tag.source.match(
-      new RegExp('^@' + escapeRegexString(targetTagName) + ' ?', 'u')
+      new RegExp(`^@${escapeRegexString(targetTagName)} ?`, 'u')
     );
     const initialTagLength = initialTag[0].length;
     const firstLinePrefixLength = preTagSpaceLength + initialTagLength;
diff --git a/src/rules/checkParamNames.js b/src/rules/checkParamNames.js
@@ -13,7 +13,7 @@ const validateParameterNames = (targetTagName : string, functionParameterNames :
     if (paramTags.some((tg, idx) => {
       return tg.name === tag.name && idx !== index;
     })) {
-      report('Duplicate @' + targetTagName + ' "' + tag.name + '"');
+      report(`Duplicate @${targetTagName} "${tag.name}"`);
 
       return true;
     }
@@ -60,7 +60,7 @@ const validateParameterNamesDeep = (targetTagName : string, jsdocParameterNames
 
     if (isPropertyPath) {
       if (!lastRealParameter) {
-        report('@' + targetTagName + ' path declaration ("' + jsdocParameterName + '") appears before any real parameter.');
+        report(`@${targetTagName} path declaration ("${jsdocParameterName}") appears before any real parameter.`);
 
         return true;
       }
@@ -72,8 +72,10 @@ const validateParameterNamesDeep = (targetTagName : string, jsdocParameterNames
       }
 
       if (pathRootNodeName !== lastRealParameter) {
-        report('@' + targetTagName + ' path declaration ("' + jsdocParameterName + '") root node name ("' +
-          pathRootNodeName + '") does not match previous real parameter name ("' + lastRealParameter + '").');
+        report(
+          `@${targetTagName} path declaration ("${jsdocParameterName}") root node name ("${pathRootNodeName}") ` +
+          `does not match previous real parameter name ("${lastRealParameter}").`
+        );
 
         return true;
       }
diff --git a/src/rules/checkTagNames.js b/src/rules/checkTagNames.js
@@ -56,13 +56,13 @@ export default iterateJsdoc(({
 
       if (preferredTagName !== tagName) {
         report(message, (fixer) => {
-          const replacement = sourceCode.getText(jsdocNode).replace('@' + tagName, '@' + preferredTagName);
+          const replacement = sourceCode.getText(jsdocNode).replace(`@${tagName}`, `@${preferredTagName}`);
 
           return fixer.replaceText(jsdocNode, replacement);
         }, jsdocTag);
       }
     } else {
-      report('Invalid JSDoc tag name "' + tagName + '".', null, jsdocTag);
+      report(`Invalid JSDoc tag name "${tagName}".`, null, jsdocTag);
     }
   });
 }, {
diff --git a/src/rules/checkTypes.js b/src/rules/checkTypes.js
@@ -191,18 +191,19 @@ export default iterateJsdoc(({
           return fixer.replaceText(
             jsdocNode,
             sourceCode.getText(jsdocNode).replace(
-              '{' + jsdocTag.type + '}', '{' + fixedType + '}'
+              `{${jsdocTag.type}}`,
+              `{${fixedType}}`
             )
           );
         };
 
-        const tagValue = jsdocTag.name ? ' "' + jsdocTag.name + '"' : '';
+        const tagValue = jsdocTag.name ? ` "${jsdocTag.name}"` : '';
 
         report(
           message ||
-            'Invalid JSDoc @' + tagName + tagValue + ' type "' + badType +
-              (preferredType ? '"; prefer: "' + preferredType : '') +
-              '".',
+            `Invalid JSDoc @${tagName}${tagValue} type "${badType}"` +
+            (preferredType ? '; ' : '.') +
+            (preferredType ? `prefer: "${preferredType}".` : ''),
           preferredType ? fix : null,
           jsdocTag,
           message ? {
diff --git a/src/rules/matchDescription.js b/src/rules/matchDescription.js
@@ -53,9 +53,19 @@ export default iterateJsdoc(({
     return;
   }
 
+  const hasOptionTag = (tagName) => {
+    return Boolean(options.tags[tagName]);
+  };
+
+  utils.forEachPreferredTag('description', (matchingJsdocTag, targetTagName) => {
+    const description = (matchingJsdocTag.name + ' ' + matchingJsdocTag.description).trim();
+    if (hasOptionTag(targetTagName)) {
+      validateDescription(description, matchingJsdocTag);
+    }
+  });
+
   const tags = utils.filterTags(({tag}) => {
-    return tagsWithDescriptions.includes(tag) &&
-      {}.hasOwnProperty.call(options.tags, tag) && options.tags[tag];
+    return tagsWithDescriptions.includes(tag) && hasOptionTag(tag);
   });
 
   tags.some((tag) => {
diff --git a/src/rules/newlineAfterDescription.js b/src/rules/newlineAfterDescription.js
@@ -35,7 +35,7 @@ export default iterateJsdoc(({
         });
 
         // Add the new line
-        sourceLines.splice(lastDescriptionLine + 1, 0, indent + ' *');
+        sourceLines.splice(lastDescriptionLine + 1, 0, `${indent} *`);
 
         return fixer.replaceText(jsdocNode, sourceLines.join('\n'));
       });
diff --git a/src/rules/noUndefinedTypes.js b/src/rules/noUndefinedTypes.js
@@ -123,7 +123,7 @@ export default iterateJsdoc(({
     traverse(parsedType, ({type, name}) => {
       if (type === 'NAME') {
         if (!allDefinedTypes.includes(name)) {
-          report('The type \'' + name + '\' is undefined.', null, tag);
+          report(`The type '${name}' is undefined.`, null, tag);
         } else if (!_.includes(extraTypes, name)) {
           context.markVariableAsUsed(name);
         }
diff --git a/src/rules/requireDescription.js b/src/rules/requireDescription.js
@@ -20,16 +20,16 @@ export default iterateJsdoc(({
   });
 
   if (!functionExamples.length) {
-    report('Missing JSDoc @' + targetTagName + ' declaration.');
+    report(`Missing JSDoc @${targetTagName} declaration.`);
 
     return;
   }
 
   functionExamples.forEach((example) => {
-    const exampleContent = _.compact((example.name + ' ' + example.description).trim().split('\n'));
+    const exampleContent = _.compact(`${example.name} ${example.description}`.trim().split('\n'));
 
     if (!exampleContent.length) {
-      report('Missing JSDoc @' + targetTagName + ' description.');
+      report(`Missing JSDoc @${targetTagName} description.`);
     }
   });
 }, {
diff --git a/src/rules/requireDescriptionCompleteSentence.js b/src/rules/requireDescriptionCompleteSentence.js
@@ -19,7 +19,7 @@ const extractSentences = (text) => {
 
     // Re-add the dot.
     .map((sentence) => {
-      return sentence + '.';
+      return `${sentence}.`;
     });
 };
 
@@ -63,7 +63,7 @@ const validateDescription = (description, report, jsdocNode, sourceCode, tag) =>
       if (!/[.:?!]$/.test(paragraph)) {
         const line = _.last(paragraph.split('\n'));
 
-        text = text.replace(new RegExp(_.escapeRegExp(line) + '$', 'm'), line + '.');
+        text = text.replace(new RegExp(`${_.escapeRegExp(line)}$`, 'm'), `${line}.`);
       }
 
       for (const sentence of sentences.filter((sentence_) => {
@@ -72,7 +72,7 @@ const validateDescription = (description, report, jsdocNode, sourceCode, tag) =>
         const beginning = sentence.split('\n')[0];
 
         if (tag) {
-          const reg = new RegExp('(@' + _.escapeRegExp(tag) + '.*)' + _.escapeRegExp(beginning));
+          const reg = new RegExp(`(@${_.escapeRegExp(tag)}.*)${_.escapeRegExp(beginning)}`);
 
           text = text.replace(reg, ($0, $1) => {
             return $1 + capitalize(beginning);
@@ -121,7 +121,7 @@ export default iterateJsdoc(({
   }
 
   utils.forEachPreferredTag('description', (matchingJsdocTag, targetTagName) => {
-    const description = (matchingJsdocTag.name + ' ' + matchingJsdocTag.description).trim();
+    const description = `${matchingJsdocTag.name} ${matchingJsdocTag.description}`.trim();
     validateDescription(description, report, jsdocNode, sourceCode, targetTagName);
   });
 
diff --git a/src/rules/requireExample.js b/src/rules/requireExample.js
@@ -28,16 +28,16 @@ export default iterateJsdoc(({
   }
 
   if (!functionExamples.length) {
-    report('Missing JSDoc @' + targetTagName + ' declaration.');
+    report(`Missing JSDoc @${targetTagName} declaration.`);
 
     return;
   }
 
   functionExamples.forEach((example) => {
-    const exampleContent = _.compact((example.name + ' ' + example.description).trim().split('\n'));
+    const exampleContent = _.compact(`${example.name} ${example.description}`.trim().split('\n'));
 
     if (!exampleContent.length) {
-      report('Missing JSDoc @' + targetTagName + ' description.');
+      report(`Missing JSDoc @${targetTagName} description.`);
     }
   });
 }, {
diff --git a/src/rules/requireHyphenBeforeParamDescription.js b/src/rules/requireHyphenBeforeParamDescription.js
@@ -22,7 +22,7 @@ export default iterateJsdoc(({
 
     if (always) {
       if (!jsdocTag.description.startsWith('-')) {
-        report('There must be a hyphen before @' + targetTagName + ' description.', (fixer) => {
+        report(`There must be a hyphen before @${targetTagName} description.`, (fixer) => {
           const lineIndex = jsdocTag.line;
           const sourceLines = sourceCode.getText(jsdocNode).split('\n');
 
@@ -39,7 +39,7 @@ export default iterateJsdoc(({
         }, jsdocTag);
       }
     } else if (jsdocTag.description.startsWith('-')) {
-      report('There must be no hyphen before @' + targetTagName + ' description.', (fixer) => {
+      report(`There must be no hyphen before @${targetTagName} description.`, (fixer) => {
         const [unwantedPart] = /-\s*/.exec(jsdocTag.description);
 
         const replacement = sourceCode
diff --git a/src/rules/requireParam.js b/src/rules/requireParam.js
@@ -24,7 +24,7 @@ export default iterateJsdoc(({
     const jsdocParameterName = jsdocParameterNames[index];
 
     if (!jsdocParameterName) {
-      report('Missing JSDoc @' + utils.getPreferredTagName('param') + ' "' + functionParameterName + '" declaration.');
+      report(`Missing JSDoc @${utils.getPreferredTagName('param')} "${functionParameterName}" declaration.`);
 
       return true;
     }
diff --git a/src/rules/requireParamDescription.js b/src/rules/requireParamDescription.js
@@ -6,7 +6,11 @@ export default iterateJsdoc(({
 }) => {
   utils.forEachPreferredTag('param', (jsdocParameter, targetTagName) => {
     if (!jsdocParameter.description) {
-      report('Missing JSDoc @' + targetTagName + ' "' + jsdocParameter.name + '" description.', null, jsdocParameter);
+      report(
+        `Missing JSDoc @${targetTagName} "${jsdocParameter.name}" description.`,
+        null,
+        jsdocParameter
+      );
     }
   });
 }, {
diff --git a/src/rules/requireParamName.js b/src/rules/requireParamName.js
diff --git a/src/rules/requireParamType.js b/src/rules/requireParamType.js
diff --git a/src/rules/requireReturns.js b/src/rules/requireReturns.js
diff --git a/src/rules/requireReturnsCheck.js b/src/rules/requireReturnsCheck.js
diff --git a/src/rules/requireReturnsDescription.js b/src/rules/requireReturnsDescription.js
diff --git a/src/rules/requireReturnsType.js b/src/rules/requireReturnsType.js
diff --git a/src/rules/validTypes.js b/src/rules/validTypes.js
diff --git a/test/rules/assertions/checkTagNames.js b/test/rules/assertions/checkTagNames.js
diff --git a/test/rules/assertions/matchDescription.js b/test/rules/assertions/matchDescription.js
diff --git a/test/rules/index.js b/test/rules/index.js

Original file line number	Diff line number	Diff line change
`@@ -30,15 +30,15 @@ const formatCodeSnippet = (setup) => {`
`30`	`30`	`paragraphs.push(trimCode(setup.code));`
`31`	`31`
`32`	`32`	`if (setup.settings) {`
`33`		`- paragraphs.push('// Settings: ' + JSON.stringify(setup.settings));`
	`33`	+ paragraphs.push(`// Settings: ${JSON.stringify(setup.settings)}`);
`34`	`34`	`}`
`35`	`35`
`36`	`36`	`if (setup.options) {`
`37`		`- paragraphs.push('// Options: ' + JSON.stringify(setup.options));`
	`37`	+ paragraphs.push(`// Options: ${JSON.stringify(setup.options)}`);
`38`	`38`	`}`
`39`	`39`
`40`	`40`	`if (setup.errors) {`
`41`		`- paragraphs.push('// Message: ' + setup.errors[0].message);`
	`41`	+ paragraphs.push(`// Message: ${setup.errors[0].message}`);
`42`	`42`	`}`
`43`	`43`
`44`	`44`	`return paragraphs.join('\n');`
`@@ -74,7 +74,7 @@ const updateDocuments = (assertions) => {`
`74`	`74`	`const ruleAssertions = assertions[ruleName];`
`75`	`75`
`76`	`76`	`if (!ruleAssertions) {`
`77`		`- throw new Error('No assertions available for rule "' + ruleName + '".');`
	`77`	+ throw new Error(`No assertions available for rule "${ruleName}".`);
`78`	`78`	`}`
`79`	`79`
`80`	`80`	return 'The following patterns are considered problems:\n\n````js\n' + ruleAssertions.invalid.join('\n\n') +
Original file line number	Diff line number	Diff line change
`@@ -77,7 +77,7 @@ const getSymbol = function (node, globals, scope, opt) {`
`77`	`77`	`}`
`78`	`78`	`*/`
`79`	`79`	`/* istanbul ignore next */`
`80`		`- debug('MemberExpression: Missing property ' + node.property.name);`
	`80`	+ debug(`MemberExpression: Missing property ${node.property.name}`);
`81`	`81`
`82`	`82`	`/* istanbul ignore next */`
`83`	`83`	`return null;`
Original file line number	Diff line number	Diff line change
`@@ -491,7 +491,7 @@ const hasReturnValue = (node, context, ignoreAsync) => {`
`491`	`491`	`}`
`492`	`492`	`}`
`493`	`493`	`/* istanbul ignore next */`
`494`		`- throw new Error('Unknown element ' + node.type);`
	`494`	+ throw new Error(`Unknown element ${node.type}`);
`495`	`495`	`};`
`496`	`496`
`497`	`497`	`/** @param {string} tag */`
Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ const validateParameterNames = (targetTagName : string, functionParameterNames :`
`13`	`13`	`if (paramTags.some((tg, idx) => {`
`14`	`14`	`return tg.name === tag.name && idx !== index;`
`15`	`15`	`})) {`
`16`		`- report('Duplicate @' + targetTagName + ' "' + tag.name + '"');`
	`16`	+ report(`Duplicate @${targetTagName} "${tag.name}"`);
`17`	`17`
`18`	`18`	`return true;`
`19`	`19`	`}`
`@@ -60,7 +60,7 @@ const validateParameterNamesDeep = (targetTagName : string, jsdocParameterNames`
`60`	`60`
`61`	`61`	`if (isPropertyPath) {`
`62`	`62`	`if (!lastRealParameter) {`
`63`		`- report('@' + targetTagName + ' path declaration ("' + jsdocParameterName + '") appears before any real parameter.');`
	`63`	+ report(`@${targetTagName} path declaration ("${jsdocParameterName}") appears before any real parameter.`);
`64`	`64`
`65`	`65`	`return true;`
`66`	`66`	`}`
`@@ -72,8 +72,10 @@ const validateParameterNamesDeep = (targetTagName : string, jsdocParameterNames`
`72`	`72`	`}`
`73`	`73`
`74`	`74`	`if (pathRootNodeName !== lastRealParameter) {`
`75`		`- report('@' + targetTagName + ' path declaration ("' + jsdocParameterName + '") root node name ("' +`
`76`		`- pathRootNodeName + '") does not match previous real parameter name ("' + lastRealParameter + '").');`
	`75`	`+ report(`
	`76`	+ `@${targetTagName} path declaration ("${jsdocParameterName}") root node name ("${pathRootNodeName}") ` +
	`77`	+ `does not match previous real parameter name ("${lastRealParameter}").`
	`78`	`+ );`
`77`	`79`
`78`	`80`	`return true;`
`79`	`81`	`}`
Original file line number	Diff line number	Diff line change
`@@ -56,13 +56,13 @@ export default iterateJsdoc(({`
`56`	`56`
`57`	`57`	`if (preferredTagName !== tagName) {`
`58`	`58`	`report(message, (fixer) => {`
`59`		`- const replacement = sourceCode.getText(jsdocNode).replace('@' + tagName, '@' + preferredTagName);`
	`59`	+ const replacement = sourceCode.getText(jsdocNode).replace(`@${tagName}`, `@${preferredTagName}`);
`60`	`60`
`61`	`61`	`return fixer.replaceText(jsdocNode, replacement);`
`62`	`62`	`}, jsdocTag);`
`63`	`63`	`}`
`64`	`64`	`} else {`
`65`		`- report('Invalid JSDoc tag name "' + tagName + '".', null, jsdocTag);`
	`65`	+ report(`Invalid JSDoc tag name "${tagName}".`, null, jsdocTag);
`66`	`66`	`}`
`67`	`67`	`});`
`68`	`68`	`}, {`