Merge pull request #242 from brettz9/require-description

`require-description` in additional contexts

Author: brettz9

.README/rules/require-description.md

@@ -5,10 +5,19 @@ Requires that all functions have a description.
 * All functions must have a `@description` tag.
 * Every description tag must have a non-empty description that explains the purpose of the method.
 
+#### Options
+
+- `contexts` - Set 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|`description`|
 |Aliases|`desc`|
+|Options|`contexts`, `noDefaults`|
 
 <!-- assertions requireDescription -->

README.md

@@ -2192,11 +2192,21 @@ Requires that all functions have a description.
 * All functions must have a `@description` tag.
 * Every description tag must have a non-empty description that explains the purpose of the method.
 
+<a name="eslint-plugin-jsdoc-rules-require-description-options"></a>
+#### Options
+
+- `contexts` - Set 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|`description`|
 |Aliases|`desc`|
+|Options|`contexts`, `noDefaults`|
 
 The following patterns are considered problems:
 
@@ -2209,6 +2219,33 @@ function quux () {
 }
 // Message: Missing JSDoc @description declaration.
 
+/**
+ *
+ */
+class quux {
+
+}
+// Options: [{"contexts":"ClassDeclaration"}]
+// Message: Missing JSDoc @description declaration.
+
+/**
+ *
+ */
+class quux {
+
+}
+// Options: [{"contexts":"ClassDeclaration","noDefaults":true}]
+// Message: Missing JSDoc @description declaration.
+
+/**
+ *
+ */
+class quux {
+
+}
+// Options: [{"contexts":["ClassDeclaration"]}]
+// Message: Missing JSDoc @description declaration.
+
 /**
  * @description
  */
@@ -2247,6 +2284,21 @@ function quux () {
 function quux () {
 
 }
+
+/**
+ *
+ */
+class quux {
+
+}
+
+/**
+ *
+ */
+function quux () {
+
+}
+// Options: [{"noDefaults":true}]
 ````
 
 

src/iterateJsdoc.js

@@ -371,16 +371,19 @@ export default (iterator, opts = {}) => {
         });
       };
 
+      let contexts = opts.returns;
       if (typeof opts.returns === 'function') {
-        return opts.returns(context, sourceCode, checkJsdoc);
+        contexts = opts.returns(context, sourceCode, checkJsdoc);
       }
 
-      if (Array.isArray(opts.returns)) {
-        return opts.returns.reduce((obj, prop) => {
+      if (Array.isArray(contexts)) {
+        return contexts.reduce((obj, prop) => {
           obj[prop] = checkJsdoc;
 
           return obj;
         }, {});
+      } else if (contexts) {
+        return contexts;
       }
 
       return {

src/rules/requireDescription.js

@@ -25,4 +25,23 @@ export default iterateJsdoc(({
       report('Missing JSDoc @' + targetTagName + ' description.');
     }
   });
+}, {
+  returns (context) {
+    const defaultContexts = [
+      'ArrowFunctionExpression',
+      'FunctionDeclaration',
+      'FunctionExpression'
+    ];
+
+    const {
+      noDefaults,
+      contexts: ctxts = []
+    } = context.options[0] || {};
+
+    const contexts = typeof ctxts === 'string' ? [ctxts] : ctxts;
+
+    return noDefaults ?
+      contexts :
+      [...new Set([...defaultContexts, ...contexts])];
+  }
 });

test/rules/assertions/requireDescription.js

@@ -15,6 +15,67 @@ export default {
         }
       ]
     },
+    {
+      code: `
+          /**
+           *
+           */
+          class quux {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @description declaration.'
+        }
+      ],
+      options: [
+        {
+          contexts: 'ClassDeclaration'
+        }
+      ]
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          class quux {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @description declaration.'
+        }
+      ],
+      options: [
+        {
+          contexts: 'ClassDeclaration',
+          noDefaults: true
+        }
+      ]
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          class quux {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @description declaration.'
+        }
+      ],
+      options: [
+        {
+          contexts: ['ClassDeclaration']
+        }
+      ]
+    },
     {
       code: `
           /**
@@ -67,6 +128,31 @@ export default {
 
           }
       `
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          class quux {
+
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           *
+           */
+          function quux () {
+
+          }
+      `,
+      options: [
+        {
+          noDefaults: true
+        }
+      ]
     }
   ]
 };