feat(require-example): add contexts array option (of AST types) to allow overriding enforced contexts (fixes #273)

Author: brettz9

.README/rules/require-example.md

@@ -7,20 +7,30 @@ Requires that all functions have examples.
 
 #### Options
 
-This rule has an object option:
+This rule has an object option.
 
-- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-  block avoids the need for an `@example`. Defaults to an empty array.
+##### `exemptedBy`
 
-- `avoidExampleOnConstructors` (default: false) - Set to `true` to avoid the
-  need for an example on a constructor (whether indicated as such by a
-  jsdoc tag or by being within an ES6 `class`).
+Array of tags (e.g., `['type']`) whose presence on the document
+block avoids the need for an `@example`. Defaults to an empty array.
+
+##### `avoidExampleOnConstructors`
+
+Set to `true` to avoid the need for an example on a constructor (whether
+indicated as such by a jsdoc tag or by being within an ES6 `class`).
+Defaults to `false`.
+
+##### `contexts`
+
+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).
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|`example`|
-|Options|`exemptedBy`, `avoidExampleOnConstructors`|
+|Options|`exemptedBy`, `avoidExampleOnConstructors`, `contexts`|
 |Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 <!-- assertions requireExample -->

README.md

@@ -4056,20 +4056,33 @@ Requires that all functions have examples.
 <a name="eslint-plugin-jsdoc-rules-require-example-options-7"></a>
 #### Options
 
-This rule has an object option:
+This rule has an object option.
 
-- `exemptedBy` - Array of tags (e.g., `['type']`) whose presence on the document
-  block avoids the need for an `@example`. Defaults to an empty array.
+<a name="eslint-plugin-jsdoc-rules-require-example-options-7-exemptedby"></a>
+##### <code>exemptedBy</code>
+
+Array of tags (e.g., `['type']`) whose presence on the document
+block avoids the need for an `@example`. Defaults to an empty array.
+
+<a name="eslint-plugin-jsdoc-rules-require-example-options-7-avoidexampleonconstructors"></a>
+##### <code>avoidExampleOnConstructors</code>
 
-- `avoidExampleOnConstructors` (default: false) - Set to `true` to avoid the
-  need for an example on a constructor (whether indicated as such by a
-  jsdoc tag or by being within an ES6 `class`).
+Set to `true` to avoid the need for an example on a constructor (whether
+indicated as such by a jsdoc tag or by being within an ES6 `class`).
+Defaults to `false`.
+
+<a name="eslint-plugin-jsdoc-rules-require-example-options-7-contexts-1"></a>
+##### <code>contexts</code>
+
+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).
 
 |||
 |---|---|
-|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|`example`|
-|Options|`exemptedBy`, `avoidExampleOnConstructors`|
+|Options|`exemptedBy`, `avoidExampleOnConstructors`, `contexts`|
 |Settings|`overrideReplacesDocs`, `augmentsExtendsReplacesDocs`, `implementsReplacesDocs`|
 
 The following patterns are considered problems:
@@ -4116,6 +4129,15 @@ function quux () {
 
 }
 // Message: Missing JSDoc @example description.
+
+/**
+ *
+ */
+class quux {
+
+}
+// Options: [{"contexts":["ClassDeclaration"]}]
+// Message: Missing JSDoc @example declaration.
 ````
 
 The following patterns are not considered problems:
@@ -4189,6 +4211,22 @@ function quux () {
 
 }
 // Options: [{"exemptedBy":["type"]}]
+
+/**
+ * @example Some example code
+ */
+class quux {
+
+}
+// Options: [{"contexts":["ClassDeclaration"]}]
+
+/**
+ *
+ */
+function quux () {
+
+}
+// Options: [{"contexts":["ClassDeclaration"]}]
 ````
 
 

src/rules/requireExample.js

@@ -46,6 +46,7 @@ export default iterateJsdoc(({
     }
   });
 }, {
+  contextDefaults: true,
   meta: {
     schema: [
       {
@@ -55,6 +56,12 @@ export default iterateJsdoc(({
             default: false,
             type: 'boolean'
           },
+          contexts: {
+            items: {
+              type: 'string'
+            },
+            type: 'array'
+          },
           exemptedBy: {
             items: {
               type: 'string'

test/rules/assertions/requireExample.js

@@ -83,6 +83,26 @@ export default {
           message: 'Missing JSDoc @example description.'
         }
       ]
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          class quux {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @example declaration.'
+        }
+      ],
+      options: [
+        {
+          contexts: ['ClassDeclaration']
+        }
+      ]
     }
   ],
   valid: [
@@ -188,6 +208,36 @@ export default {
           exemptedBy: ['type']
         }
       ]
+    },
+    {
+      code: `
+          /**
+           * @example Some example code
+           */
+          class quux {
+
+          }
+      `,
+      options: [
+        {
+          contexts: ['ClassDeclaration']
+        }
+      ]
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux () {
+
+          }
+      `,
+      options: [
+        {
+          contexts: ['ClassDeclaration']
+        }
+      ]
     }
   ]
 };