New Rule: requireReturnDescription

Added requireReturnDescription rule implementation, tests, and documentation.

Fixes #122
Closes gh-125

Author: weekens

README.md

@@ -847,6 +847,54 @@ function method(arg) {}
 ```
 
 
+### requireReturnDescription
+
+Ensures a return description exists.
+
+Type: `Boolean`
+
+Values: `true`
+
+Context: `functions`
+
+Tags: `return`, `returns`
+
+#### Example
+
+```js
+"requireReturnDescription": true
+```
+
+##### Valid
+
+```js
+/**
+ * @returns {Boolean} Method result.
+ */
+function method() {
+  return false;
+}
+
+/**
+ * @returns {String} method result
+ */
+function method() {
+  return 'Hello!';
+}
+```
+
+##### Invalid
+
+```js
+/**
+ * @returns {Boolean}
+ */
+function method() {
+  return false;
+}
+```
+
+
 ## Browser Usage
 
 NOT SUPPORTED ATM. SORRY.

lib/rules/validate-jsdoc/index.js

@@ -11,6 +11,7 @@ var validatorsByName = module.exports = {
 
     checkReturnTypes: require('./check-return-types'),
     requireReturnTypes: require('./require-return-types'),
+    requireReturnDescription: require('./require-return-description'),
     checkRedundantReturns: require('./check-redundant-returns'),
 
     checkAnnotations: require('./check-annotations'),

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

@@ -0,0 +1,22 @@
+module.exports = validateReturnTagDescription;
+module.exports.tags = ['return', 'returns'];
+module.exports.scopes = ['function'];
+module.exports.options = {
+    requireReturnDescription: {allowedValues: [true]}
+};
+
+/**
+ * Validator for @return description.
+ *
+ * @param {(FunctionDeclaration|FunctionExpression)} node
+ * @param {DocTag} tag
+ * @param {Function} err
+ */
+function validateReturnTagDescription(node, tag, err) {
+    // Check tag existence. Note: for @returns tag, description is parsed as a name.
+    if (tag.name) {
+        return;
+    }
+
+    return err('Missing return description', tag.loc);
+}

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

@@ -0,0 +1,105 @@
+describe('lib/rules/validate-jsdoc/require-return-description', function() {
+    var checker = global.checker({
+        plugins: ['./lib/index']
+    });
+
+    describe('not configured', function() {
+        it('should report with undefined', function() {
+            global.expect(function() {
+                checker.configure({requireReturnDescription: undefined});
+            }).to.throws(/accepted value/i);
+        });
+
+        it('should report with an object', function() {
+            global.expect(function() {
+                checker.configure({requireReturnDescription: {}});
+            }).to.throws(/accepted value/i);
+        });
+    });
+
+    describe('with true', function() {
+        checker.rules({requireReturnDescription: true});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not report',
+                code: function() {
+                    function yay(yey) {
+                    }
+                }
+            },
+            {
+                it: 'should report missing jsdoc-return description for function',
+                errors: 1,
+                code: function() {
+                    var x = 1;
+
+                    /**
+                     * @returns
+                     */
+                    function funcName() {
+                        // dummy
+                    }
+                }
+            },
+            {
+                it: 'should report missing jsdoc-return description for method',
+                errors: 1,
+                code: function() {
+                    Cls.prototype = {
+                        /**
+                         * @returns
+                         */
+                        run: function() {
+                            // dummy
+                        }
+                    };
+                }
+            },
+            {
+                it: 'should not report valid jsdoc for function',
+                code: function() {
+                    var x = 1;
+
+                    /**
+                     * @returns {Boolean} False.
+                     */
+                    function funcName() {
+                        return false;
+                    }
+                }
+            },
+            {
+                it: 'should not report valid jsdoc for method',
+                code: function() {
+                    Cls.prototype = {
+                        /**
+                         * @returns {Boolean} False.
+                         */
+                        run: function() {
+                            return false;
+                        }
+                    };
+                }
+            },
+            {
+                it: 'should report with right location',
+                code: function() {
+                    Cls.prototype = {
+                        /**
+                         * @returns
+                         */
+                        run: function() {
+                            return false;
+                        }
+                    };
+                },
+                errors: {column: 7, line: 3}
+            }
+            /* jshint ignore:end */
+        ]);
+
+    });
+});
+