feat(match-description): allow main description: string|boolean to override or disable main description separate from default

brettz9 · chiawendt · commit 314557c72b2e · 2019-06-26T18:52:23.000+08:00
feat(match-description): add `contexts` and `noDefaults` options for control on which contexts the rules apply
feat(match-description): report line number with `match-description`
feat(match-description): allow reporting multiple errors when main description validation fails
docs(match-description): indicate default uses 'u' flag and is not case-insensitive
testing(match-description): better Cyrillic checks (insist upper-case followed by lower-case and period)
diff --git a/.README/rules/match-description.md b/.README/rules/match-description.md
@@ -50,14 +50,39 @@ 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`:
 
-By default, only the main function description is linted.
+```js
+{
+  'jsdoc/match-description': ['error', {tags: {
+    'main description': '[A-Z].*\\.',
+    param: true,
+    returns: true
+  }}]
+}
+```
+
+There is no need to add `"main description": 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`.
+
+##### `contexts`
+
+Set this to a string or array of strings representing the AST context
+where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
+
+##### `noDefaults`
+
+By default, `contexts` will permit `ArrowFunctionExpression`,
+`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
+have `contexts` override these.
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A by default but see `tags` options|
 |Settings||
-|Options|`tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
+|Options|`contexts`, `noDefaults`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
 
 <!-- assertions matchDescription -->
diff --git a/README.md b/README.md
@@ -2299,15 +2299,42 @@ 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`:
 
-By default, only the main function description is linted.
+```js
+{
+  'jsdoc/match-description': ['error', {tags: {
+    'main description': '[A-Z].*\\.',
+    param: true,
+    returns: true
+  }}]
+}
+```
+
+There is no need to add `"main description": 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`.
+
+<a name="eslint-plugin-jsdoc-rules-match-description-options-1-contexts"></a>
+##### <code>contexts</code>
+
+Set this to a string or array of strings representing the AST context
+where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
+
+<a name="eslint-plugin-jsdoc-rules-match-description-options-1-nodefaults"></a>
+##### <code>noDefaults</code>
+
+By default, `contexts` will permit `ArrowFunctionExpression`,
+`FunctionDeclaration`, and `FunctionExpression`. Set this instead to `true` to
+have `contexts` override these.
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A by default but see `tags` options|
 |Settings||
-|Options|`tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
+|Options|`contexts`, `noDefaults`, `tags` (allows for 'param', 'arg', 'argument', 'returns', 'return'), `matchDescription`|
 
 The following patterns are considered problems:
 
@@ -2335,6 +2362,18 @@ function quux () {
 
 }
 // Options: [{"matchDescription":"[А-Я][А-я]+\\."}]
+<<<<<<< HEAD
+=======
+// Message: JSDoc description does not satisfy the regex pattern.
+
+/**
+ * тест.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"main description":"[А-Я][А-я]+\\.","param":true}}]
+>>>>>>> feat(match-description): allow `main description: string|boolean` to override or disable main description separate from default
 // Message: JSDoc description does not satisfy the regex pattern.
 
 /**
@@ -2356,6 +2395,28 @@ function quux (foo) {
 // Options: [{"tags":{"param":true}}]
 // Message: JSDoc description does not satisfy the regex pattern.
 
+/**
+ * Foo
+ *
+ * @param foo foo.
+ */
+function quux (foo) {
+
+}
+// Options: [{"tags":{"main description":"^[a-zA-Z]*$","param":true}}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
+/**
+ * Foo
+ *
+ * @param foo foo.
+ */
+function quux (foo) {
+
+}
+// Options: [{"tags":{"main description":false,"param":true}}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
 /**
  * Foo.
  *
@@ -2456,6 +2517,18 @@ function quux () {
 
 }
 // Options: [{"tags":{"param":"[А-Я][А-я]+\\."}}]
+<<<<<<< HEAD
+=======
+// Message: JSDoc description does not satisfy the regex pattern.
+
+/**
+ * foo.
+ */
+class quux {
+
+}
+// Options: [{"contexts":["ClassDeclaration"],"noDefaults":true}]
+>>>>>>> feat(match-description): allow `main description: string|boolean` to override or disable main description separate from default
 // Message: JSDoc description does not satisfy the regex pattern.
 ````
 
@@ -2585,6 +2658,30 @@ function quux () {
 function quux () {
 
 }
+
+/**
+ * foo.
+ */
+function quux () {
+
+}
+// Options: [{"tags":{"main description":false}}]
+
+/**
+ * foo.
+ */
+class quux {
+
+}
+// Message: JSDoc description does not satisfy the regex pattern.
+
+/**
+ * foo.
+ */
+class quux {
+
+}
+// Options: [{"tags":{"main description":true}}]
 ````
 
 
diff --git a/src/rules/matchDescription.js b/src/rules/matchDescription.js
@@ -12,8 +12,13 @@ export default iterateJsdoc(({
   const options = context.options[0] || {};
 
   const validateDescription = (description, tag) => {
+    const tagName = tag.tag;
+    const tagOptions = options.tags || {};
+    if (tagOptions[tagName] === false) {
+      return;
+    }
     const regex = new RegExp(
-      (tag && typeof options.tags[tag] === 'string' ? options.tags[tag] :
+      (typeof tagOptions[tagName] === 'string' ? tagOptions[tagName] :
         options.matchDescription
 
       // If supporting Node >= 10, we could loosen to this for the
@@ -23,16 +28,16 @@ export default iterateJsdoc(({
     );
 
     if (!regex.test(description)) {
-      report('JSDoc description does not satisfy the regex pattern.');
-
-      return true;
+      report('JSDoc description does not satisfy the regex pattern.', null, tag);
     }
-
-    return false;
   };
 
-  if (jsdoc.description && validateDescription(jsdoc.description)) {
-    return;
+  if (jsdoc.description) {
+    validateDescription(jsdoc.description, {
+      // Add one as description would typically be into block
+      line: jsdoc.line + 1,
+      tag: 'main description'
+    });
   }
 
   if (!options.tags || !Object.keys(options.tags).length) {
@@ -47,18 +52,36 @@ export default iterateJsdoc(({
   tags.some((tag) => {
     const description = _.trimStart(tag.description, '- ');
 
-    return validateDescription(description, tag.tag);
+    return validateDescription(description, tag);
   });
 }, {
+  contextDefaults: true,
   meta: {
     schema: [
       {
         additionalProperties: false,
         properties: {
+          contexts: {
+            oneOf: [
+              {
+                items: {
+                  type: 'string'
+                },
+                type: 'array'
+              },
+              {
+                type: 'string'
+              }
+            ]
+          },
           matchDescription: {
             format: 'regex',
             type: 'string'
           },
+          noDefaults: {
+            default: false,
+            type: 'boolean'
+          },
           tags: {
             patternProperties: {
               '.*': {
@@ -68,7 +91,6 @@ export default iterateJsdoc(({
                     type: 'string'
                   },
                   {
-                    enum: [true],
                     type: 'boolean'
                   }
                 ]
diff --git a/test/rules/assertions/matchDescription.js b/test/rules/assertions/matchDescription.js
