feat(match-description, require-description, require-example): allow "any" for contexts; fixes #325

Author: brettz9

.README/rules/match-description.md

@@ -88,7 +88,8 @@ it by setting it to `false`.
 
 Set this to an array of strings representing the AST context
 where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
-Overrides the default contexts (see below).
+Overrides the default contexts (see below). Set to `"any"` if you want
+the rule to apply to any jsdoc block throughout your files.
 
 |||
 |---|---|

.README/rules/require-description.md

@@ -14,7 +14,8 @@ An options object may have any of the following properties:
 
 - `contexts` - Set to an array of strings representing the AST context
   where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6
-  classes). Overrides the default contexts (see below).
+  classes). Overrides the default contexts (see below).  Set to `"any"` if
+  you want the rule to apply to any jsdoc block throughout your files.
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
     document block avoids the need for a `@description`. Defaults to an
     empty array.

.README/rules/require-example.md

@@ -24,7 +24,8 @@ Defaults to `false`.
 
 Set this to an array of strings representing the AST context
 where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
-Overrides the default contexts (see below).
+Overrides the default contexts (see below). Set to `"any"` if you want
+the rule to apply to any jsdoc block throughout your files.
 
 #### Fixer
 

README.md

@@ -3973,7 +3973,8 @@ it by setting it to `false`.
 
 Set this to an array of strings representing the AST context
 where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
-Overrides the default contexts (see below).
+Overrides the default contexts (see below). Set to `"any"` if you want
+the rule to apply to any jsdoc block throughout your files.
 
 |||
 |---|---|
@@ -3995,6 +3996,18 @@ const q = class {
 // Options: [{"contexts":["ClassExpression"]}]
 // Message: JSDoc description does not satisfy the regex pattern.
 
+/**
+ * foo.
+ */
+// Options: [{"contexts":["any"]}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
+/**
+ * foo.
+ */
+// Options: [{"contexts":["any"]}]
+// Message: JSDoc description does not satisfy the regex pattern.
+
 /**
  * foo.
  */
@@ -4305,6 +4318,17 @@ function quux (foo) {
 The following patterns are not considered problems:
 
 ````js
+/**
+ *
+ */
+
+/**
+ *
+ */
+ function quux () {
+
+ }
+
 /**
  * @param foo - Foo.
  */
@@ -5952,7 +5976,8 @@ An options object may have any of the following properties:
 
 - `contexts` - Set to an array of strings representing the AST context
   where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6
-  classes). Overrides the default contexts (see below).
+  classes). Overrides the default contexts (see below).  Set to `"any"` if
+  you want the rule to apply to any jsdoc block throughout your files.
 - `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the
     document block avoids the need for a `@description`. Defaults to an
     empty array.
@@ -6007,6 +6032,12 @@ class quux {
 // Options: [{"contexts":["ClassDeclaration"],"descriptionStyle":"tag"}]
 // Message: Missing JSDoc @description declaration.
 
+/**
+ *
+ */
+// Options: [{"contexts":["any"],"descriptionStyle":"tag"}]
+// Message: Missing JSDoc @description declaration.
+
 /**
  *
  */
@@ -6103,6 +6134,10 @@ function quux () {
 The following patterns are not considered problems:
 
 ````js
+/**
+ *
+ */
+
 /**
  * @description
  * // arbitrary description content
@@ -6253,7 +6288,8 @@ Defaults to `false`.
 
 Set this to an array of strings representing the AST context
 where you wish the rule to be applied (e.g., `ClassDeclaration` for ES6 classes).
-Overrides the default contexts (see below).
+Overrides the default contexts (see below). Set to `"any"` if you want
+the rule to apply to any jsdoc block throughout your files.
 
 <a name="eslint-plugin-jsdoc-rules-require-example-fixer"></a>
 #### Fixer
@@ -6322,6 +6358,12 @@ class quux {
 // Options: [{"contexts":["ClassDeclaration"]}]
 // Message: Missing JSDoc @example declaration.
 
+/**
+ *
+ */
+// Options: [{"contexts":["any"]}]
+// Message: Missing JSDoc @example declaration.
+
 /**
  *
  */
@@ -6334,6 +6376,10 @@ function quux () {
 The following patterns are not considered problems:
 
 ````js
+/**
+ *
+ */
+
 /**
  * @example
  * // arbitrary example content
@@ -7092,6 +7138,10 @@ const myObject = {
 The following patterns are not considered problems:
 
 ````js
+/**
+ *
+ */
+
 var array = [1,2,3];
 array.forEach(function() {});
 

src/iterateJsdoc.js

@@ -584,11 +584,18 @@ export default function iterateJsdoc (iterator, ruleConfig) {
      *   a list with parser callback function.
      */
     create (context) {
-      const sourceCode = context.getSourceCode();
+      let contexts;
+      if (ruleConfig.contextDefaults) {
+        contexts = jsdocUtils.enforcedContexts(context, ruleConfig.contextDefaults);
+        if (contexts.includes('any')) {
+          return iterateAllJsdocs(iterator, ruleConfig).create(context);
+        }
+      }
 
+      const sourceCode = context.getSourceCode();
       const settings = getSettings(context);
-
       const {lines} = sourceCode;
+
       const checkJsdoc = (node) => {
         const jsdocNode = getJSDocComment(sourceCode, node, settings);
 
@@ -603,8 +610,6 @@ export default function iterateJsdoc (iterator, ruleConfig) {
       };
 
       if (ruleConfig.contextDefaults) {
-        const contexts = jsdocUtils.enforcedContexts(context, ruleConfig.contextDefaults);
-
         return jsdocUtils.getContextObject(contexts, checkJsdoc);
       }
 

src/rules/requireJsdoc.js

@@ -120,11 +120,10 @@ export default {
     warnRemovedSettings(context, 'require-jsdoc');
 
     const sourceCode = context.getSourceCode();
+    const settings = getSettings(context);
 
     const {require: requireOption, publicOnly, exemptEmptyFunctions} = getOptions(context);
 
-    const settings = getSettings(context);
-
     const checkJsDoc = (node) => {
       const jsDocNode = getJSDocComment(sourceCode, node, settings);
 

test/rules/assertions/matchDescription.js

@@ -23,6 +23,46 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           * foo.
+           */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'JSDoc description does not satisfy the regex pattern.',
+        },
+      ],
+      options: [
+        {
+          contexts: [
+            'any',
+          ],
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           * foo.
+           */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'JSDoc description does not satisfy the regex pattern.',
+        },
+      ],
+      options: [
+        {
+          contexts: [
+            'any',
+          ],
+        },
+      ],
+    },
     {
       code: `
           /**
@@ -734,6 +774,23 @@ export default {
     },
   ],
   valid: [
+    {
+      code: `
+          /**
+           *
+           */
+      `,
+    },
+    {
+      code: `
+          /**
+           *
+           */
+           function quux () {
+
+           }
+      `,
+    },
     {
       code: `
           /**

test/rules/assertions/requireDescription.js

@@ -81,6 +81,24 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           *
+           */
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @description declaration.',
+        },
+      ],
+      options: [
+        {
+          contexts: ['any'],
+          descriptionStyle: 'tag',
+        },
+      ],
+    },
     {
       code: `
           /**
@@ -319,6 +337,13 @@ export default {
     },
   ],
   valid: [
+    {
+      code: `
+          /**
+           *
+           */
+      `,
+    },
     {
       code: `
           /**

test/rules/assertions/requireExample.js

@@ -112,6 +112,23 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           *
+           */
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @example declaration.',
+        },
+      ],
+      options: [
+        {
+          contexts: ['any'],
+        },
+      ],
+    },
     {
       code: `
           /**
@@ -134,6 +151,13 @@ export default {
     },
   ],
   valid: [
+    {
+      code: `
+          /**
+           *
+           */
+      `,
+    },
     {
       code: `
           /**

test/rules/assertions/requireJsdoc.js

@@ -1142,6 +1142,12 @@ export default {
     },
   ],
   valid: [{
+    code: `
+        /**
+         *
+         */
+    `,
+  }, {
     code: `
       var array = [1,2,3];
       array.forEach(function() {});