Switch "main description" on tags to its own option as mainDescription

Author: brettz9

.README/rules/match-description.md

@@ -51,19 +51,21 @@ tag should be linted with the `matchDescription` value (or the default).
 ```
 
 If you wish to override the main function description without changing the
-default `mainDescription`, you may use `tags` with `main description`:
+default `match-description`, you may use `mainDescription`:
 
 ```js
 {
-  'jsdoc/match-description': ['error', {tags: {
-    'main description': '[A-Z].*\\.',
-    param: true,
-    returns: true
-  }}]
+  'jsdoc/match-description': ['error', {
+    mainDescription: '[A-Z].*\\.',
+    tags: {
+      param: true,
+      returns: true
+    }
+  }]
 }
 ```
 
-There is no need to add `"main description": true`, as by default, the main
+There is no need to add `mainDescription: true`, as by default, the main
 function (and only the main function) is linted, though you may disable checking
 it by setting it to `false`.
 

README.md

@@ -2333,19 +2333,21 @@ tag should be linted with the `matchDescription` value (or the default).
 ```
 
 If you wish to override the main function description without changing the
-default `mainDescription`, you may use `tags` with `main description`:
+default `match-description`, you may use `mainDescription`:
 
 ```js
 {
-  'jsdoc/match-description': ['error', {tags: {
-    'main description': '[A-Z].*\\.',
-    param: true,
-    returns: true
-  }}]
+  'jsdoc/match-description': ['error', {
+    mainDescription: '[A-Z].*\\.',
+    tags: {
+      param: true,
+      returns: true
+    }
+  }]
 }
 ```
 
-There is no need to add `"main description": true`, as by default, the main
+There is no need to add `mainDescription: true`, as by default, the main
 function (and only the main function) is linted, though you may disable checking
 it by setting it to `false`.
 
@@ -2405,8 +2407,12 @@ function quux () {
 function quux () {
 
 }
+<<<<<<< HEAD
 // Options: [{"tags":{"main description":"[А-Я][А-я]+\\.","param":true}}]
 >>>>>>> feat(match-description): allow `main description: string|boolean` to override or disable main description separate from default
+=======
+// Options: [{"mainDescription":"[А-Я][А-я]+\\.","tags":{"param":true}}]
+>>>>>>> Switch "main description" on `tags` to its own option as `mainDescription`
 // Message: JSDoc description does not satisfy the regex pattern.
 
 /**
@@ -2436,7 +2442,7 @@ function quux (foo) {
 function quux (foo) {
 
 }
-// Options: [{"tags":{"main description":"^[a-zA-Z]*$","param":true}}]
+// Options: [{"mainDescription":"^[a-zA-Z]*$","tags":{"param":true}}]
 // Message: JSDoc description does not satisfy the regex pattern.
 
 /**
@@ -2447,7 +2453,7 @@ function quux (foo) {
 function quux (foo) {
 
 }
-// Options: [{"tags":{"main description":false,"param":true}}]
+// Options: [{"mainDescription":false,"tags":{"param":true}}]
 // Message: JSDoc description does not satisfy the regex pattern.
 
 /**
@@ -2725,7 +2731,7 @@ function quux () {
 function quux () {
 
 }
-// Options: [{"tags":{"main description":false}}]
+// Options: [{"mainDescription":false}]
 
 /**
  * foo.
@@ -2741,7 +2747,7 @@ class quux {
 class quux {
 
 }
-// Options: [{"tags":{"main description":true}}]
+// Options: [{"mainDescription":true}]
 
 class MyClass {
   /**

src/rules/matchDescription.js

@@ -3,6 +3,16 @@ import iterateJsdoc from '../iterateJsdoc';
 
 const tagsWithDescriptions = ['param', 'arg', 'argument', 'returns', 'return'];
 
+// If supporting Node >= 10, we could loosen the default to this for the
+//   initial letter: \\p{Upper}
+const matchDescriptionDefault = '^[A-Z`\\d_][\\s\\S]*[.?!`]$';
+
+const stringOrDefault = (value, userDefault) => {
+  return typeof value === 'string' ?
+    value :
+    userDefault || matchDescriptionDefault;
+};
+
 export default iterateJsdoc(({
   jsdoc,
   report,
@@ -12,32 +22,31 @@ export default iterateJsdoc(({
   const options = context.options[0] || {};
 
   const validateDescription = (description, tag) => {
-    const tagName = tag.tag;
-    const tagOptions = options.tags || {};
-    if (tagOptions[tagName] === false) {
+    if (!tag && options.mainDescription === false) {
       return;
     }
-    const regex = new RegExp(
-      (typeof tagOptions[tagName] === 'string' ? tagOptions[tagName] :
-        options.matchDescription
 
-      // If supporting Node >= 10, we could loosen to this for the
-      //   initial letter: \\p{Upper}
-      ) || '^[A-Z`\\d_][\\s\\S]*[.?!`]$',
+    let tagValue = options.mainDescription;
+    if (tag) {
+      const tagName = tag.tag;
+      tagValue = options.tags[tagName];
+    }
+
+    const regex = new RegExp(
+      stringOrDefault(tagValue, options.matchDescription),
       'u'
     );
 
     if (!regex.test(description)) {
-      report('JSDoc description does not satisfy the regex pattern.', null, tag);
+      report('JSDoc description does not satisfy the regex pattern.', null, tag || {
+        // Add one as description would typically be into block
+        line: jsdoc.line + 1
+      });
     }
   };
 
   if (jsdoc.description) {
-    validateDescription(jsdoc.description, {
-      // Add one as description would typically be into block
-      line: jsdoc.line + 1,
-      tag: 'main description'
-    });
+    validateDescription(jsdoc.description);
   }
 
   if (!options.tags || !Object.keys(options.tags).length) {
@@ -74,6 +83,17 @@ export default iterateJsdoc(({
               }
             ]
           },
+          mainDescription: {
+            oneOf: [
+              {
+                format: 'regex',
+                type: 'string'
+              },
+              {
+                type: 'boolean'
+              }
+            ]
+          },
           matchDescription: {
             format: 'regex',
             type: 'string'
@@ -91,6 +111,7 @@ export default iterateJsdoc(({
                     type: 'string'
                   },
                   {
+                    enum: [true],
                     type: 'boolean'
                   }
                 ]

test/rules/assertions/matchDescription.js

@@ -51,6 +51,28 @@ export default {
         matchDescription: '[\u0410-\u042F][\u0410-\u044F]+\\.'
       }]
     },
+    {
+      code: `
+          /**
+           * Abc.
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'JSDoc description does not satisfy the regex pattern.'
+        }
+      ],
+      options: [{
+        mainDescription: '[\u0410-\u042F][\u0410-\u044F]+\\.',
+        tags: {
+          param: true
+        }
+      }]
+    },
     {
       code: `
           /**
@@ -111,8 +133,8 @@ export default {
       ],
       options: [
         {
+          mainDescription: '^[a-zA-Z]*$',
           tags: {
-            'main description': '^[a-zA-Z]*$',
             param: true
           }
         }
@@ -137,8 +159,8 @@ export default {
       ],
       options: [
         {
+          mainDescription: false,
           tags: {
-            'main description': false,
             param: true
           }
         }
@@ -669,9 +691,7 @@ export default {
           }
       `,
       options: [
-        {tags: {
-          'main description': false
-        }}
+        {mainDescription: false}
       ]
     },
     {
@@ -694,9 +714,7 @@ export default {
           }
       `,
       options: [
-        {tags: {
-          'main description': true
-        }}
+        {mainDescription: true}
       ]
     },
     {