fix(match-description); preserve newlines (except trailling ones) f…

…or purposes of regex matching; fixes part of gajus#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

@@ -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`

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 () {
+
+}
 ````
 
 

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) {

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;
     }
 

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,
+        },
+      }],
+    },
   ],
 };

test/rules/assertions/requireDescription.js

@@ -832,5 +832,16 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           * Multi
+           * line
+           */
+          function quux () {
+
+          }
+      `,
+    },
   ],
 };