New Rule: requireParamDescription

Fixes #107
Closes gh-111

Author: dtracers

lib/rules/validate-jsdoc/index.js

@@ -6,6 +6,7 @@ var validatorsByName = module.exports = {
     checkParamNames: require('./check-param-names'),
     checkRedundantParams: require('./check-redundant-params'),
     requireParamTypes: require('./require-param-types'),
+    requireParamDescription: require('./require-param-description'),
     requireHyphenBeforeDescription: require('./require-hyphen-before-description'),
 
     checkReturnTypes: require('./check-return-types'),

lib/rules/validate-jsdoc/require-param-description.js

@@ -0,0 +1,28 @@
+module.exports = validateParamTagDescription;
+module.exports.tags = ['param', 'arg', 'argument'];
+module.exports.scopes = ['function'];
+module.exports.options = {
+    requireParamDescription: {allowedValues: [true]}
+};
+
+/**
+ * Validator for @param
+ *
+ * @param {(FunctionDeclaration|FunctionExpression)} node
+ * @param {DocTag} tag
+ * @param {Function} err
+ */
+function validateParamTagDescription(node, tag, err) {
+    // checking existance
+    if (tag.description) {
+        return;
+    }
+
+    var offset = (tag.name && tag.name.value && tag.name.value.length) || 0;
+    var loc = (tag.name ? tag.name.loc : null) || tag.loc;
+
+    return err('Missing param description', {
+        line: loc.line,
+        column: loc.column + offset
+    });
+}

test/lib/rules/validate-jsdoc/require-param-description.js

@@ -0,0 +1,146 @@
+describe('lib/rules/validate-jsdoc/require-param-description', function () {
+    var checker = global.checker({
+        plugins: ['./lib/index']
+    });
+
+    describe('not configured', function() {
+
+        it('should report with undefined', function() {
+            global.expect(function() {
+                checker.configure({requireParamDescription: undefined});
+            }).to.throws(/accepted value/i);
+        });
+
+        it('should report with an object', function() {
+            global.expect(function() {
+                checker.configure({requireParamDescription: {}});
+            }).to.throws(/accepted value/i);
+        });
+
+    });
+
+    describe('with true', function() {
+        checker.rules({requireParamDescription: true});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not report',
+                code: function() {
+                    function yay(yey) {
+                    }
+                }
+            }, {
+                it: 'should report missing jsdoc-param description for function',
+                errors: 1,
+                code: function () {
+                    var x = 1;
+                    /**
+                     * @param xxx
+                     */
+                    function funcName(xxx) {
+                        // dummy
+                    }
+                }
+            }, {
+                it: 'should report missing jsdoc-param description for method',
+                errors: 1,
+                code: function () {
+                    Cls.prototype = {
+                        /**
+                         * @param yyy
+                         */
+                        run: function(xxx) {
+                            // dummy
+                        }
+                    };
+                }
+            }, {
+                it: 'should not report invalid jsdoc for method',
+                code: function () {
+                    var x = 1;
+                    /**
+                     * @param {String} xxx description
+                     */
+                    function funcName(xxx) {
+                        // dummy
+                    }
+                }
+            }, {
+                it: 'should not report invalid jsdoc for function',
+                code: function () {
+                    Cls.prototype = {
+                        /**
+                         * @param {String} xxx description
+                         */
+                        run: function(xxx) {
+                            // dummy
+                        }
+                    };
+                }
+            }, {
+                it: 'should not report invalid jsdoc with object type for method',
+                code: function () {
+                    var x = 1;
+                    /**
+                     * @param {{foo: string}} xxx description
+                     */
+                    function funcName(xxx) {
+                        // dummy
+                    }
+                }
+            }, {
+                it: 'should not report invalid jsdoc with object type for function',
+                code: function () {
+                    Cls.prototype = {
+                        /**
+                         * @param {{foo: string}} xxx description
+                         */
+                        run: function(xxx) {
+                            // dummy
+                        }
+                    };
+                }
+            }, {
+                it: 'should not report invalid jsdoc with no param type for method',
+                code: function () {
+                    var x = 1;
+                    /**
+                     * @param xxx description
+                     */
+                    function funcName(xxx) {
+                        // dummy
+                    }
+                }
+            }, {
+                it: 'should not report invalid jsdoc with no param type for function',
+                code: function () {
+                    Cls.prototype = {
+                        /**
+                         * @param xxx description
+                         */
+                        run: function(xxx) {
+                            // dummy
+                        }
+                    };
+                }
+            }, {
+                it: 'should report with right location',
+                code: function () {
+                    Cls.prototype = {
+                        /**
+                         * @param xxx
+                         */
+                        run: function(xxx) {
+                            // dummy
+                        }
+                    };
+                },
+                errors: {column: 17, line: 3}
+            }
+            /* jshint ignore:end */
+        ]);
+
+    });
+
+});