Merge pull request gajus#312 from brettz9/require-description-complete-sentence-tag

require-description-complete-sentence explicit `@description` tag validation

Author: brettz9

.README/rules/require-description-complete-sentence.md

@@ -1,16 +1,18 @@
 ### `require-description-complete-sentence`
 
-Requires that block description and tag description are written in complete sentences, i.e.,
+Requires that block description, explicit `@description`, and `@param`/`@returns`
+tag descriptions are written in complete sentences, i.e.,
 
 * Description must start with an uppercase alphabetical character.
 * Paragraphs must start with an uppercase alphabetical character.
 * Sentences must end with a period.
-* Every line in a paragraph (except the first) which starts with an uppercase character must be preceded by a line ending with a period.
+* Every line in a paragraph (except the first) which starts with an uppercase
+  character must be preceded by a line ending with a period.
 
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`param`, `returns`|
-|Aliases|`arg`, `argument`, `return`|
+|Tags|`param`, `returns`, `description`|
+|Aliases|`arg`, `argument`, `return`, `desc`|
 
 <!-- assertions requireDescriptionCompleteSentence -->

README.md

@@ -3404,18 +3404,20 @@ function quux () {
 <a name="eslint-plugin-jsdoc-rules-require-description-complete-sentence"></a>
 ### <code>require-description-complete-sentence</code>
 
-Requires that block description and tag description are written in complete sentences, i.e.,
+Requires that block description, explicit `@description`, and `@param`/`@returns`
+tag descriptions are written in complete sentences, i.e.,
 
 * Description must start with an uppercase alphabetical character.
 * Paragraphs must start with an uppercase alphabetical character.
 * Sentences must end with a period.
-* Every line in a paragraph (except the first) which starts with an uppercase character must be preceded by a line ending with a period.
+* Every line in a paragraph (except the first) which starts with an uppercase
+  character must be preceded by a line ending with a period.
 
 |||
 |---|---|
 |Context|everywhere|
-|Tags|`param`, `returns`|
-|Aliases|`arg`, `argument`, `return`|
+|Tags|`param`, `returns`, `description`|
+|Aliases|`arg`, `argument`, `return`, `desc`|
 
 The following patterns are considered problems:
 
@@ -3428,6 +3430,14 @@ function quux () {
 }
 // Message: Sentence should start with an uppercase character.
 
+/**
+ * @description foo.
+ */
+function quux () {
+
+}
+// Message: Sentence should start with an uppercase character.
+
 /**
  * Foo)
  */
@@ -3670,6 +3680,13 @@ function quux () {
  */
 function quux () {
 
+}
+
+/**
+ * @description Foo.
+ */
+function quux () {
+
 }
 ````
 

src/rules/requireDescriptionCompleteSentence.js

@@ -111,14 +111,20 @@ export default iterateJsdoc(({
   sourceCode,
   jsdoc,
   report,
-  jsdocNode
+  jsdocNode,
+  utils
 }) => {
   if (!jsdoc.tags ||
     validateDescription(jsdoc.description, report, jsdocNode, sourceCode)
   ) {
     return;
   }
 
+  utils.forEachPreferredTag('description', (matchingJsdocTag, targetTagName) => {
+    const description = (matchingJsdocTag.name + ' ' + matchingJsdocTag.description).trim();
+    validateDescription(description, report, jsdocNode, sourceCode, targetTagName);
+  });
+
   const tags = jsdoc.tags.filter((tag) => {
     return ['param', 'arg', 'argument', 'returns', 'return'].includes(tag.tag);
   });

test/rules/assertions/requireDescriptionCompleteSentence.js

@@ -23,6 +23,29 @@ export default {
           }
       `
     },
+    {
+      code: `
+          /**
+           * @description foo.
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Sentence should start with an uppercase character.'
+        }
+      ],
+      output: `
+          /**
+           * @description Foo.
+           */
+          function quux () {
+
+          }
+      `
+    },
     {
       code: `
           /**
@@ -551,6 +574,16 @@ export default {
            */
           function quux () {
 
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           * @description Foo.
+           */
+          function quux () {
+
           }
       `
     }