requireNewlineAfterDescription: rule to enforce newline after doc description

Fixes #85
Closes gh-99

Author: Alexej Yaroshevich

lib/rules/validate-jsdoc/index.js

@@ -14,6 +14,8 @@ var validatorsByName = module.exports = {
 
     checkAnnotations: require('./check-annotations'),
 
+    requireNewlineAfterDescription: require('./require-newline-after-description'),
+
     checkRedundantAccess: require('./check-redundant-access'),
     enforceExistence: require('./enforce-existence'),
     leadingUnderscoreAccess: require('./leading-underscore-access')

lib/rules/validate-jsdoc/require-newline-after-description.js

@@ -0,0 +1,30 @@
+module.exports = requireNewlineAfterDescription;
+module.exports.scopes = ['function'];
+module.exports.options = {
+    requireNewlineAfterDescription: {allowedValues: [true]}
+};
+
+var RE_NEWLINE_AT_THE_END = /\n$/;
+var RE_NEWLINES = /\n/g;
+
+/**
+ * Requires newline after description in jsdoc comment
+ *
+ * @param {(FunctionDeclaration|FunctionExpression)} node
+ * @param {Function} err
+ */
+function requireNewlineAfterDescription(node, err) {
+    var doc = node.jsdoc;
+    if (!doc || !doc.tags.length || !doc.description || !doc.description.length) {
+        return;
+    }
+
+    if (!RE_NEWLINE_AT_THE_END.test(doc.description)) {
+        var loc = node.jsdoc.loc.start;
+        var lines = doc.description.split(RE_NEWLINES);
+        err('Newline required after description', {
+            line: loc.line + lines.length,
+            column: loc.column + 3 + lines[lines.length - 1].length
+        });
+    }
+}

test/lib/rules/validate-jsdoc/require-newline-after-description.js

@@ -0,0 +1,76 @@
+describe('lib/rules/validate-jsdoc/require-newline-after-description', function () {
+    var checker = global.checker({
+        additionalRules: ['lib/rules/validate-jsdoc.js']
+    });
+
+    describe('not configured', function() {
+
+        it('should report with undefined', function() {
+            global.expect(function() {
+                checker.configure({requireNewlineAfterDescription: undefined});
+            }).to.throws(/accepted value/i);
+        });
+
+        it('should report with an object', function() {
+            global.expect(function() {
+                checker.configure({requireNewlineAfterDescription: {}});
+            }).to.throws(/accepted value/i);
+        });
+
+    });
+
+    describe('with true', function() {
+        checker.rules({requireNewlineAfterDescription: true});
+
+        checker.cases([
+            /* jshint ignore:start */
+            {
+                it: 'should not report common cases',
+                code: function() {
+                    function fun(p) {
+                    }
+
+                    /**
+                     * Description
+                     */
+                    function fun(p) {
+                    }
+
+                    /**
+                     * @param p
+                     */
+                    function fun(p) {
+                    }
+                }
+            }, {
+                it: 'should report newline absence after description',
+                code: function () {
+                    /**
+                     * Some description
+                     * @param {number} p description without hyphen
+                     */
+                    function fun(p) {
+                    }
+                },
+                errors: {
+                    line: 2,
+                    column: 19
+                },
+            }, {
+                it: 'should not report newline after description',
+                code: function () {
+                    /**
+                     * Some description.
+                     * Get me higher and higher!
+                     *
+                     * @param {number} p description without hyphen
+                     */
+                    function fun(p) {}
+                }
+            }
+            /* jshint ignore:end */
+        ]);
+
+    });
+
+});