From 74bbe387069b574a1a1600353c7cff0c5efa60ce Mon Sep 17 00:00:00 2001
From: Brett Zamir <brettz9@yahoo.com>
Date: Tue, 16 Feb 2021 11:45:15 +0800
Subject: [PATCH] fix(`match-description`); preserve newlines (except trailling
 ones) for purposes of regex matching; fixes part of #692

Should now include fix for `comment-parser` update's dropping of newlines in jsdoc block `description`; still need to preserve newlines across rules in the `.description` of tags
---
 .README/rules/match-description.md          |  3 +++
 README.md                                   | 22 +++++++++++++++++++++
 src/rules/matchDescription.js               |  5 ++++-
 src/rules/requireDescription.js             |  3 ++-
 test/rules/assertions/matchDescription.js   | 22 +++++++++++++++++++++
 test/rules/assertions/requireDescription.js | 11 +++++++++++
 6 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/.README/rules/match-description.md b/.README/rules/match-description.md
index 34275ed1e..94cffe768 100644
--- a/.README/rules/match-description.md
+++ b/.README/rules/match-description.md
@@ -21,6 +21,9 @@ Note that `/` delimiters are optional, but necessary to add flags (besides
 Also note that the default or optional regular expressions is *not*
 case-insensitive unless one opts in to add the `i` flag.
 
+You can add the `s` flag if you want `.` to match newlines. Note, however,
+that the trailing newlines of a description will not be matched.
+
 #### Options
 
 ##### `matchDescription`
diff --git a/README.md b/README.md
index ff30426fd..0028eed3a 100644
--- a/README.md
+++ b/README.md
@@ -5959,6 +5959,9 @@ Note that `/` delimiters are optional, but necessary to add flags (besides
 Also note that the default or optional regular expressions is *not*
 case-insensitive unless one opts in to add the `i` flag.
 
+You can add the `s` flag if you want `.` to match newlines. Note, however,
+that the trailing newlines of a description will not be matched.
+
 <a name="eslint-plugin-jsdoc-rules-match-description-options-11"></a>
 #### Options
 
@@ -6694,6 +6697,17 @@ function quux (foo) {
 
 }
 // "jsdoc/match-description": ["error"|"warn", {"tags":{"template":true}}]
+
+/**
+ * Enable or disable plugin.
+ *
+ * When enabling with this function, the script will be attached to the `document` if:.
+ * - the script runs in browser context.
+ * - the `document` doesn't have the script already attached.
+ * - the `loadScript` option is set to `true`.
+ * @param enabled `true` to enable, `false` to disable. Default: `true`.
+ */
+// "jsdoc/match-description": ["error"|"warn", {"contexts":["any"],"mainDescription":"/^[A-Z`-].*\\.$/us","matchDescription":"^([A-Z`-].*(\\.|:)|-\\s.*)$","tags":{"param":true,"returns":true}}]
 ````
 
 
@@ -9095,6 +9109,14 @@ class TestClass {
   set Test(value) { }
 }
 // "jsdoc/require-description": ["error"|"warn", {"checkSetters":false}]
+
+/**
+ * Multi
+ * line
+ */
+function quux () {
+
+}
 ````
 
 
diff --git a/src/rules/matchDescription.js b/src/rules/matchDescription.js
index d133118db..775296ca2 100644
--- a/src/rules/matchDescription.js
+++ b/src/rules/matchDescription.js
@@ -43,7 +43,10 @@ export default iterateJsdoc(({
   };
 
   if (jsdoc.description) {
-    validateDescription(jsdoc.description);
+    const {description} = utils.getDescription();
+    validateDescription(
+      description.replace(/\n+$/, ''),
+    );
   }
 
   if (!options.tags || !Object.keys(options.tags).length) {
diff --git a/src/rules/requireDescription.js b/src/rules/requireDescription.js
index 2f15bb16e..214f52770 100644
--- a/src/rules/requireDescription.js
+++ b/src/rules/requireDescription.js
@@ -35,7 +35,8 @@ export default iterateJsdoc(({
   };
 
   if (descriptionStyle !== 'tag') {
-    if (checkDescription(jsdoc.description || '')) {
+    const {description} = utils.getDescription();
+    if (checkDescription(description || '')) {
       return;
     }
 
diff --git a/test/rules/assertions/matchDescription.js b/test/rules/assertions/matchDescription.js
index cb6a60b3b..03a943f63 100644
--- a/test/rules/assertions/matchDescription.js
+++ b/test/rules/assertions/matchDescription.js
@@ -1317,5 +1317,27 @@ export default {
         },
       ],
     },
+    {
+      code: `
+      /**
+       * Enable or disable plugin.
+       *
+       * When enabling with this function, the script will be attached to the \`document\` if:.
+       * - the script runs in browser context.
+       * - the \`document\` doesn't have the script already attached.
+       * - the \`loadScript\` option is set to \`true\`.
+       * @param enabled \`true\` to enable, \`false\` to disable. Default: \`true\`.
+       */
+      `,
+      options: [{
+        contexts: ['any'],
+        mainDescription: '/^[A-Z`-].*\\.$/us',
+        matchDescription: '^([A-Z`-].*(\\.|:)|-\\s.*)$',
+        tags: {
+          param: true,
+          returns: true,
+        },
+      }],
+    },
   ],
 };
diff --git a/test/rules/assertions/requireDescription.js b/test/rules/assertions/requireDescription.js
index 37bb24676..8a8d306e7 100644
--- a/test/rules/assertions/requireDescription.js
+++ b/test/rules/assertions/requireDescription.js
@@ -832,5 +832,16 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           * Multi
+           * line
+           */
+          function quux () {
+
+          }
+      `,
+    },
   ],
 };