feat: add require-description (#91)

* add rule require-description

* correct a typo

Author: ajelcocks

.README/README.md

@@ -18,6 +18,7 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
 | [`check-tag-names`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-tag-names) | N/A ~ [`checkAnnotations`](https://github.com/jscs-dev/jscs-jsdoc#checkannotations) |
 | [`check-types`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-types) | [`checkTypes`](https://github.com/jscs-dev/jscs-jsdoc#checktypes) |
 | [`newline-after-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-newline-after-description) | [`requireNewlineAfterDescription`](https://github.com/jscs-dev/jscs-jsdoc#requirenewlineafterdescription) and [`disallowNewlineAfterDescription`](https://github.com/jscs-dev/jscs-jsdoc#disallownewlineafterdescription) |
+| [`require-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-description) | N/A |
 | [`require-description-complete-sentence`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-description-complete-sentence) | [`requireDescriptionCompleteSentence`](https://github.com/jscs-dev/jscs-jsdoc#requiredescriptioncompletesentence) |
 | [`require-example`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-example) | N/A |
 | [`require-hyphen-before-param-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-hyphen-before-param-description) | [`requireHyphenBeforeDescription`](https://github.com/jscs-dev/jscs-jsdoc#requirehyphenbeforedescription) |
@@ -72,6 +73,7 @@ Finally, enable all of the rules that you would like to use.
         "jsdoc/check-types": 1,
         "jsdoc/newline-after-description": 1,
         "jsdoc/no-undefined-types": 1,
+        "jsdoc/require-description": 1,
         "jsdoc/require-description-complete-sentence": 1,
         "jsdoc/require-example": 1,
         "jsdoc/require-hyphen-before-param-description": 1,
@@ -146,6 +148,7 @@ Use `settings.jsdoc.allowOverrideWithoutParam` to indicate whether the `@overrid
 {"gitdown": "include", "file": "./rules/check-types.md"}
 {"gitdown": "include", "file": "./rules/newline-after-description.md"}
 {"gitdown": "include", "file": "./rules/no-undefined-types.md"}
+{"gitdown": "include", "file": "./rules/require-description.md"}
 {"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"}
 {"gitdown": "include", "file": "./rules/require-example.md"}
 {"gitdown": "include", "file": "./rules/require-hyphen-before-param-description.md"}

.README/rules/require-description.md

@@ -0,0 +1,13 @@
+### `require-description`
+
+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.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|`class`, `example`|
+
+<!-- assertions requireDescription -->

src/index.js

@@ -5,6 +5,7 @@ import checkTypes from './rules/checkTypes';
 import newlineAfterDescription from './rules/newlineAfterDescription';
 import noUndefinedTypes from './rules/noUndefinedTypes';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence';
+import requireDescription from './rules/requireDescription';
 import requireExample from './rules/requireExample';
 import requireHyphenBeforeParamDescription from './rules/requireHyphenBeforeParamDescription';
 import requireParamName from './rules/requireParamName';
@@ -24,6 +25,7 @@ export default {
         'jsdoc/check-types': 'warn',
         'jsdoc/newline-after-description': 'warn',
         'jsdoc/no-undefined-types': 'warn',
+        'jsdoc/require-description': 'off',
         'jsdoc/require-description-complete-sentence': 'off',
         'jsdoc/require-example': 'off',
         'jsdoc/require-hyphen-before-param-description': 'off',
@@ -43,6 +45,7 @@ export default {
     'check-types': checkTypes,
     'newline-after-description': newlineAfterDescription,
     'no-undefined-types': noUndefinedTypes,
+    'require-description': requireDescription,
     'require-description-complete-sentence': requireDescriptionCompleteSentence,
     'require-example': requireExample,
     'require-hyphen-before-param-description': requireHyphenBeforeParamDescription,
@@ -60,6 +63,7 @@ export default {
     'check-types': 'off',
     'newline-after-description': 'off',
     'no-undefined-types': 'off',
+    'require-description': 'off',
     'require-description-complete-sentence': 'off',
     'require-example': 'off',
     'require-hyphen-before-param-description': 'off',

src/rules/requireDescription.js

@@ -0,0 +1,26 @@
+import _ from 'lodash';
+import iterateJsdoc from '../iterateJsdoc';
+
+export default iterateJsdoc(({
+  jsdoc,
+  report,
+  utils
+}) => {
+  const targetTagName = utils.getPreferredTagName('description');
+
+  const functionExamples = _.filter(jsdoc.tags, {
+    tag: targetTagName
+  });
+
+  if (_.isEmpty(functionExamples)) {
+    return report('Missing JSDoc @' + targetTagName + ' declaration.');
+  }
+
+  return _.forEach(functionExamples, (example) => {
+    const exampleContent = _.compact((example.name + ' ' + example.description).trim().split('\n'));
+
+    if (_.isEmpty(exampleContent)) {
+      report('Missing JSDoc @' + targetTagName + ' description.');
+    }
+  });
+});

test/rules/assertions/requireDescription.js

@@ -0,0 +1,74 @@
+/* eslint-disable no-restricted-syntax */
+
+export default {
+  invalid: [
+    {
+      code: `
+          /**
+           *
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @description declaration.'
+        }
+      ]
+    },
+    {
+      code: `
+          /**
+           * @description
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          message: 'Missing JSDoc @description description.'
+        }
+      ]
+    }
+  ],
+  valid: [
+    {
+      code: `
+          /**
+           * @description
+           * // arbitrary description content
+           */
+          function quux () {
+
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           * @description
+           * quux(); // does something useful
+           */
+          function quux () {
+
+          }
+      `
+    },
+    {
+      code: `
+          /**
+           * @description <caption>Valid usage</caption>
+           * quux(); // does something useful
+           *
+           * @description <caption>Invalid usage</caption>
+           * quux('random unwanted arg'); // results in an error
+           */
+          function quux () {
+
+          }
+      `
+    }
+  ]
+};

test/rules/index.js

@@ -12,6 +12,7 @@ _.forEach([
   'check-types',
   'newline-after-description',
   'no-undefined-types',
+  'require-description',
   'require-description-complete-sentence',
   'require-example',
   'require-hyphen-before-param-description',