New: require-jsdoc rule (fixes #1842)

.eslintrc

@@ -74,6 +74,7 @@ rules:
     no-with: 2
     quotes: [2, "double"]
     radix: 2
+    require-jsdoc: 2
     semi: 2
     semi-spacing: [2, {before: false, after: true}]
     space-after-keywords: [2, "always"]

conf/eslint.json

@@ -163,6 +163,7 @@
         "quotes": [0, "double"],
         "radix": 0,
         "id-match": 0,
+        "require-jsdoc": 0,
         "require-yield": 0,
         "semi": 0,
         "semi-spacing": [0, {"before": false, "after": true}],

docs/rules/README.md

@@ -177,6 +177,7 @@ These rules are purely matters of style and are quite subjective.
 * [padded-blocks](padded-blocks.md) - enforce padding within blocks
 * [quote-props](quote-props.md) - require quotes around object literal property names
 * [quotes](quotes.md) - specify whether backticks, double or single quotes should be used
+* [require-jsdoc](require-jsdoc.md) - Require JSDoc comment
 * [semi-spacing](semi-spacing.md) - enforce spacing before and after semicolons
 * [semi](semi.md) - require or disallow use of semicolons instead of ASI
 * [sort-vars](sort-vars.md) - sort variables within the same declaration block

docs/rules/require-jsdoc.md

@@ -0,0 +1,56 @@
+# Require JSDoc comment (require-jsdoc)
+
+This rule generates warnings for nodes which do not have JSDoc comments. It considered a good practice to document the behavior of different nodes to help engineers understand the functionality of the node.
+Supported nodes:
+
+* `FunctionExpression`
+* `FunctionDeclaration`
+
+## Rule details
+
+The following patterns are considered warnings:
+
+```js
+/*eslint require-jsdoc: 2*/
+
+function foo() {       /*error Missing JSDoc comment.*/
+    return 10;
+}
+
+var foo = function() { /*error Missing JSDoc comment.*/
+    return 10;
+}
+```
+
+The following patterns are not considered warnings:
+
+```js
+/*eslint require-jsdoc: 2*/
+
+/**
+* It returns 10
+*/
+function foo() {
+    return 10;
+}
+
+/**
+* It returns 10
+*/
+var foo = function() {
+    return 10;
+}
+
+var array = [1,2,3];
+array.filter(function(item) {
+    return item > 2;
+});
+```
+
+## When not to use
+
+If you do not require node documentation, then you can leave this rule off.
+
+## Related Rules
+
+* [valid-jsdoc](valid-jsdoc.md)

lib/rules/require-jsdoc.js

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Rule to check for jsdoc presence.
+ * @author Gyandeep Singh
+ * @copyright 2015 Gyandeep Singh. All rights reserved.
+ */
+"use strict";
+
+module.exports = function(context) {
+    var source = context.getSourceCode();
+
+    /**
+     * Report the error message
+     * @param {ASTNode} node node to report
+     * @returns {void}
+     */
+    function report(node) {
+        context.report(node, "Missing JSDoc comment.");
+    }
+
+    /**
+     * Check if the jsdoc comment is present or not.
+     * @param {ASTNode} node node to examine
+     * @returns {void}
+     */
+    function checkJsDoc(node) {
+        var jsdocComment = source.getJSDocComment(node);
+
+        if (!jsdocComment) {
+            switch (node.type) {
+                case "FunctionExpression":
+                    if (node.parent.type !== "MemberExpression" && node.parent.type !== "CallExpression" ) {
+                        report(node);
+                    }
+                    break;
+
+                default:
+                    report(node);
+            }
+        }
+    }
+
+    return {
+        "FunctionExpression": checkJsDoc,
+        "FunctionDeclaration": checkJsDoc
+    };
+};
+
+module.exports.schema = [];

tests/lib/rules/require-jsdoc.js

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Test file for require-jsdoc rule
+ * @author Gyandeep Singh
+ * @copyright 2015 Gyandeep Singh. All rights reserved.
+ */
+"use strict";
+
+var rule = require("../../../lib/rules/require-jsdoc"),
+    RuleTester = require("../../../lib/testers/rule-tester");
+
+//------------------------------------------------------------------------------
+// Tests
+//------------------------------------------------------------------------------
+
+var ruleTester = new RuleTester();
+ruleTester.run("require-jsdoc", rule, {
+    valid: [
+        "var array = [1,2,3];\narray.forEach(function() {});",
+        "/**\n @class MyClass \n*/\nfunction MyClass() {}",
+        "/**\n Function doing something\n*/\nfunction myFunction() {}",
+        "/**\n Function doing something\n*/\nvar myFunction = function() {};",
+        "/**\n Function doing something\n*/\nObject.myFunction = function () {};",
+        "var obj = { \n /**\n Function doing something\n*/\n myFunction: function () {} };",
+
+        "/**\n @func myFunction \n*/\nfunction myFunction() {}",
+        "/**\n @method myFunction\n*/\nfunction myFunction() {}",
+        "/**\n @function myFunction\n*/\nfunction myFunction() {}",
+
+        "/**\n @func myFunction \n*/\nvar myFunction = function () {}",
+        "/**\n @method myFunction\n*/\nvar myFunction = function () {}",
+        "/**\n @function myFunction\n*/\nvar myFunction = function () {}",
+
+        "/**\n @func myFunction \n*/\nObject.myFunction = function() {}",
+        "/**\n @method myFunction\n*/\nObject.myFunction = function() {}",
+        "/**\n @function myFunction\n*/\nObject.myFunction = function() {}",
+        "(function(){})();",
+
+        "var object = {\n/**\n @func myFunction - Some function \n*/\nmyFunction: function() {} }",
+        "var object = {\n/**\n @method myFunction - Some function \n*/\nmyFunction: function() {} }",
+        "var object = {\n/**\n @function myFunction - Some function \n*/\nmyFunction: function() {} }",
+
+        "var array = [1,2,3];\narray.forEach(function() {});",
+        "var array = [1,2,3];\narray.filter(function() {});",
+        "Object.keys(this.options.rules || {}).forEach(function(name) {}.bind(this));",
+        "var object = { name: 'key'};\nObject.keys(object).forEach(function() {})"
+    ],
+
+    invalid: [
+        {
+            code: "var testFunction = function() {}",
+            errors: [{
+                message: "Missing JSDoc comment.",
+                type: "FunctionExpression"
+            }]
+        },
+        {
+            code: "function myFunction() {}",
+            errors: [{
+                message: "Missing JSDoc comment.",
+                type: "FunctionDeclaration"
+            }]
+        },
+        {
+            code: "var object = { myFunction: function() {} };",
+            errors: [{
+                message: "Missing JSDoc comment.",
+                type: "FunctionExpression"
+            }]
+        },
+        {
+            code: "var object = {};\nobject.testFunction = function() {}",
+            errors: [{
+                message: "Missing JSDoc comment.",
+                type: "FunctionExpression"
+            }]
+        }
+    ]
+});