feat(require-description-complete-sentence): add new option `newlineB…

…eforeCapsAssumesBadSentenceEnd` which when `false` (the new default) will not assume caps after newlines is a bad sentence end. BREAKING CHANGE: To restore the old behavior, the new option `newlineBeforeCapsAssumesBadSentenceEnd` must be set to `true`. This was changed from the default to decrease the false positives when capitalized letters on newlines merely represent proper nouns, etc.
gajus · May 28, 2020 · 7d4c399 · 7d4c399
1 parent d8c4e87
commit 7d4c399
Show file tree

Hide file tree

Showing 3 changed files with 62 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -6348,6 +6348,7 @@ function quux () {
 function quux () {
 
 }
+// Options: [{"newlineBeforeCapsAssumesBadSentenceEnd":true}]
 // Message: A line of text is started with an uppercase character, but preceding line does not end the sentence.
 
 /**
@@ -6565,6 +6566,15 @@ function quux () {
 
  }
 // Message: Sentence should start with an uppercase character.
+
+/**
+ * Implements support for the
+ * Swahili voice synthesizer.
+ */
+function speak() {
+}
+// Options: [{"newlineBeforeCapsAssumesBadSentenceEnd":true}]
+// Message: A line of text is started with an uppercase character, but preceding line does not end the sentence.
 ````
 
 The following patterns are not considered problems:
@@ -6877,6 +6887,13 @@ function quux () {
 
 }
 // Options: [{"abbreviations":["etc","e.g.","i.e."]}]
+
+/**
+ * Implements support for the
+ * Swahili voice synthesizer.
+ */
+function speak() {
+}
 ````
 
 

diff --git a/src/rules/requireDescriptionCompleteSentence.js b/src/rules/requireDescriptionCompleteSentence.js
@@ -70,7 +70,10 @@ const capitalize = (str) => {
   return str.charAt(0).toUpperCase() + str.slice(1);
 };
 
-const validateDescription = (description, reportOrig, jsdocNode, abbreviationsRegex, sourceCode, tag) => {
+const validateDescription = (
+  description, reportOrig, jsdocNode, abbreviationsRegex,
+  sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd,
+) => {
   if (!description) {
     return false;
   }
@@ -131,7 +134,7 @@ const validateDescription = (description, reportOrig, jsdocNode, abbreviationsRe
       return true;
     }
 
-    if (!isNewLinePrecededByAPeriod(paragraphNoAbbreviations)) {
+    if (newlineBeforeCapsAssumesBadSentenceEnd && !isNewLinePrecededByAPeriod(paragraphNoAbbreviations)) {
       report('A line of text is started with an uppercase character, but preceding line does not end the sentence.', null, tag);
 
       return true;
@@ -152,6 +155,7 @@ export default iterateJsdoc(({
   const options = context.options[0] || {};
   const {
     abbreviations = [],
+    newlineBeforeCapsAssumesBadSentenceEnd = false,
   } = options;
 
   const abbreviationsRegex = abbreviations.length ?
@@ -163,14 +167,14 @@ export default iterateJsdoc(({
   if (!jsdoc.tags ||
     validateDescription(jsdoc.description, report, jsdocNode, abbreviationsRegex, sourceCode, {
       line: jsdoc.line + 1,
-    })
+    }, newlineBeforeCapsAssumesBadSentenceEnd)
   ) {
     return;
   }
 
   utils.forEachPreferredTag('description', (matchingJsdocTag) => {
     const description = `${matchingJsdocTag.name} ${matchingJsdocTag.description}`.trim();
-    validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, matchingJsdocTag);
+    validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, matchingJsdocTag, newlineBeforeCapsAssumesBadSentenceEnd);
   }, true);
 
   const {tagsWithNames} = utils.getTagsByType(jsdoc.tags);
@@ -186,13 +190,13 @@ export default iterateJsdoc(({
   tagsWithNames.some((tag) => {
     const description = _.trimStart(tag.description, '- ');
 
-    return validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, tag);
+    return validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);
   });
 
   tagsWithoutNames.some((tag) => {
     const description = `${tag.name} ${tag.description}`.trim();
 
-    return validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, tag);
+    return validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);
   });
 }, {
   iterateAllJsdocs: true,
@@ -208,6 +212,9 @@ export default iterateJsdoc(({
             },
             type: 'array',
           },
+          newlineBeforeCapsAssumesBadSentenceEnd: {
+            type: 'boolean',
+          },
           tags: {
             items: {
               type: 'string',

diff --git a/test/rules/assertions/requireDescriptionCompleteSentence.js b/test/rules/assertions/requireDescriptionCompleteSentence.js
@@ -210,6 +210,9 @@ export default {
           message: 'A line of text is started with an uppercase character, but preceding line does not end the sentence.',
         },
       ],
+      options: [{
+        newlineBeforeCapsAssumesBadSentenceEnd: true,
+      }],
     },
     {
       code: `
@@ -822,6 +825,25 @@ export default {
        }
        `,
     },
+    {
+      code: `
+      /**
+       * Implements support for the
+       * Swahili voice synthesizer.
+       */
+      function speak() {
+      }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'A line of text is started with an uppercase character, but preceding line does not end the sentence.',
+        },
+      ],
+      options: [{
+        newlineBeforeCapsAssumesBadSentenceEnd: true,
+      }],
+    },
   ],
   valid: [
     {
@@ -1280,5 +1302,15 @@ export default {
         abbreviations: ['etc', 'e.g.', 'i.e.'],
       }],
     },
+    {
+      code: `
+      /**
+       * Implements support for the
+       * Swahili voice synthesizer.
+       */
+      function speak() {
+      }
+      `,
+    },
   ],
 };