Merge pull request #205 from allthesignals/master

feat: implement a requireJSDoc compatible rule with working tests

Author: gajus

src/index.js

@@ -21,6 +21,7 @@ import requireReturnsCheck from './rules/requireReturnsCheck';
 import requireReturnsDescription from './rules/requireReturnsDescription';
 import requireReturnsType from './rules/requireReturnsType';
 import validTypes from './rules/validTypes';
+import requireJsdoc from './rules/requireJsdoc';
 
 export default {
   configs: {
@@ -39,6 +40,7 @@ export default {
         'jsdoc/require-description-complete-sentence': 'off',
         'jsdoc/require-example': 'off',
         'jsdoc/require-hyphen-before-param-description': 'off',
+        'jsdoc/require-jsdoc': 'warn',
         'jsdoc/require-param': 'warn',
         'jsdoc/require-param-description': 'warn',
         'jsdoc/require-param-name': 'warn',
@@ -65,6 +67,7 @@ export default {
     'require-description-complete-sentence': requireDescriptionCompleteSentence,
     'require-example': requireExample,
     'require-hyphen-before-param-description': requireHyphenBeforeParamDescription,
+    'require-jsdoc': requireJsdoc,
     'require-param': requireParam,
     'require-param-description': requireParamDescription,
     'require-param-name': requireParamName,

src/rules/requireJsdoc.js

@@ -0,0 +1,156 @@
+const OPTIONS_SCHEMA = {
+  additionalProperties: false,
+  properties: {
+    require: {
+      additionalProperties: false,
+      default: {},
+      properties: {
+        ArrowFunctionExpression: {
+          default: false,
+          type: 'boolean'
+        },
+        ClassDeclaration: {
+          default: false,
+          type: 'boolean'
+        },
+        FunctionDeclaration: {
+          default: true,
+          type: 'boolean'
+        },
+        FunctionExpression: {
+          default: false,
+          type: 'boolean'
+        },
+        MethodDefinition: {
+          default: false,
+          type: 'boolean'
+        }
+      },
+      type: 'object'
+    }
+  },
+  type: 'object'
+};
+
+const getOption = (context, key) => {
+  if (!context.options.length) {
+    return OPTIONS_SCHEMA.properties.require.properties[key].default;
+  }
+
+  if (!context.options[0] || !context.options[0].require) {
+    return OPTIONS_SCHEMA.properties.require.properties[key].default;
+  }
+
+  if (!context.options[0].require.hasOwnProperty(key)) {
+    return OPTIONS_SCHEMA.properties.require.properties[key].default;
+  }
+
+  return context.options[0].require[key];
+};
+
+const getOptions = (context) => {
+  return {
+    ArrowFunctionExpression: getOption(context, 'ArrowFunctionExpression'),
+    ClassDeclaration: getOption(context, 'ClassDeclaration'),
+    FunctionDeclaration: getOption(context, 'FunctionDeclaration'),
+    FunctionExpression: getOption(context, 'FunctionExpression'),
+    MethodDefinition: getOption(context, 'MethodDefinition')
+  };
+};
+
+const checkJsDoc = (context, node) => {
+  const jsDocNode = context.getSourceCode().getJSDocComment(node);
+
+  if (jsDocNode) {
+    return;
+  }
+
+  context.report({
+    messageId: 'missingJsDoc',
+    node
+  });
+};
+
+export default {
+  /**
+   * The entrypoint for the JSDoc rule.
+   *
+   * @param {*} context
+   *   a reference to the context which hold all important information
+   *   like settings and the sourcecode to check.
+   * @returns {*}
+   *   a list with parser callback function.
+   */
+  create (context) {
+    const options = getOptions(context);
+
+    return {
+      ArrowFunctionExpression: (node) => {
+        if (!options.ArrowFunctionExpression) {
+          return;
+        }
+
+        if (node.parent.type !== 'VariableDeclarator') {
+          return;
+        }
+
+        checkJsDoc(context, node);
+      },
+
+      ClassDeclaration: (node) => {
+        if (!options.ClassDeclaration) {
+          return;
+        }
+
+        checkJsDoc(context, node);
+      },
+
+      FunctionDeclaration: (node) => {
+        if (!options.FunctionDeclaration) {
+          return;
+        }
+
+        checkJsDoc(context, node);
+      },
+
+      FunctionExpression: (node) => {
+        if (options.MethodDefinition && node.parent.type === 'MethodDefinition') {
+          checkJsDoc(context, node);
+
+          return;
+        }
+
+        if (!options.FunctionExpression) {
+          return;
+        }
+
+        if (node.parent.type === 'VariableDeclarator') {
+          checkJsDoc(context, node);
+        }
+
+        if (node.parent.type === 'Property' && node === node.parent.value) {
+          checkJsDoc(context, node);
+        }
+      }
+    };
+  },
+
+  meta: {
+    doc: {
+      category: 'Stylistic Issues',
+      description: 'Require JSDoc comments',
+      recommended: 'true',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc'
+    },
+
+    messages: {
+      missingJsDoc: 'Missing JSDoc comment.'
+    },
+
+    schema: [
+      OPTIONS_SCHEMA
+    ],
+
+    type: 'suggestion'
+  }
+};