feat: allow empty line between jsdoc and jscode (#353)

feat(*): have doc block retrieval allow or require additional preceding empty lines via min/max line setting API
gajus · Aug 8, 2019 · 19a6590 · 19a6590
1 parent c8d0611
commit 19a6590
Show file tree

Hide file tree

Showing 6 changed files with 207 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -4757,6 +4757,32 @@ Accepts one optional options object with the following optional keys.
 The following patterns are considered problems:
 
 ````js
+/**
+ * @func myFunction
+ */
+function myFunction() {
+
+}
+// Settings: {"jsdoc":{"maxLines":3,"minLines":2}}
+// Message: Missing JSDoc comment.
+
+/**
+ * @func myFunction
+ */
+
+
+function myFunction() {
+
+}
+// Settings: {"jsdoc":{"maxLines":2}}
+// Message: Missing JSDoc comment.
+
+/** @func myFunction */ function myFunction() {
+
+}
+// Settings: {"jsdoc":{"minLines":1}}
+// Message: Missing JSDoc comment.
+
 export var test = function () {
 
 };
@@ -5181,6 +5207,39 @@ Object.keys(this.options.rules || {}).forEach(function(name) {}.bind(this));
 var object = { name: 'key'};
 Object.keys(object).forEach(function() {})
 
+/**
+ * @func myFunction
+ */
+
+function myFunction() {
+
+}
+// Settings: {"jsdoc":{"maxLines":2,"minLines":0}}
+
+/**
+ * @func myFunction
+ */
+
+
+function myFunction() {
+
+}
+// Settings: {"jsdoc":{"maxLines":3,"minLines":0}}
+
+/** @func myFunction */  function myFunction() {
+
+}
+// Settings: {"jsdoc":{"maxLines":0,"minLines":0}}
+
+/** 
+ * @func myFunction
+ */
+
+function myFunction() {
+
+}
+// Settings: {"jsdoc":{"maxLines":3,"minLines":2}}
+
 function myFunction() {}
 // Options: [{"require":{"ClassDeclaration":true,"FunctionDeclaration":false,"MethodDefinition":true}}]
 

diff --git a/src/eslint/getJSDocComment.js b/src/eslint/getJSDocComment.js
@@ -32,12 +32,13 @@ const looksLikeExport = function (astNode) {
  *
  * @param {SourceCode} sourceCode The ESLint SourceCode
  * @param {ASTNode} node The AST node to get the comment for.
+ * @param {object} settings The settings in context
  * @returns {Token|null} The Block comment token containing the JSDoc comment
  *    for the given node or null if not found.
  * @public
  * @deprecated
  */
-const getJSDocComment = function (sourceCode, node) {
+const getJSDocComment = function (sourceCode, node, settings) {
   /**
    * Checks for the presence of a JSDoc comment for the given node and returns it.
    *
@@ -48,13 +49,14 @@ const getJSDocComment = function (sourceCode, node) {
    */
   const findJSDocComment = (astNode) => {
     const tokenBefore = sourceCode.getTokenBefore(astNode, {includeComments: true});
-
+    const {minLines, maxLines} = settings;
     if (
       tokenBefore &&
       isCommentToken(tokenBefore) &&
       tokenBefore.type === 'Block' &&
       tokenBefore.value.charAt(0) === '*' &&
-      astNode.loc.start.line - tokenBefore.loc.end.line <= 1
+      astNode.loc.start.line - tokenBefore.loc.end.line >= minLines &&
+      astNode.loc.start.line - tokenBefore.loc.end.line <= maxLines
     ) {
       return tokenBefore;
     }

diff --git a/src/iterateJsdoc.js b/src/iterateJsdoc.js
@@ -78,7 +78,9 @@ const getUtils = (
     tagNamePreference,
     overrideReplacesDocs,
     implementsReplacesDocs,
-    augmentsExtendsReplacesDocs
+    augmentsExtendsReplacesDocs,
+    maxLines,
+    minLines
   },
   report,
   context
@@ -263,7 +265,10 @@ const getUtils = (
 
   utils.getClassJsdoc = () => {
     const classNode = utils.getClassNode();
-    const classJsdocNode = getJSDocComment(sourceCode, classNode);
+    const classJsdocNode = getJSDocComment(sourceCode, classNode, {
+      maxLines,
+      minLines
+    });
 
     if (classJsdocNode) {
       const indent = ' '.repeat(classJsdocNode.loc.start.column);
@@ -319,6 +324,8 @@ const getSettings = (context) => {
 
   // All rules
   settings.ignorePrivate = Boolean(_.get(context, 'settings.jsdoc.ignorePrivate'));
+  settings.minLines = Number(_.get(context, 'settings.jsdoc.minLines', 0));
+  settings.maxLines = Number(_.get(context, 'settings.jsdoc.maxLines', 1));
 
   // `check-tag-names` and many returns/param rules
   settings.tagNamePreference = _.get(context, 'settings.jsdoc.tagNamePreference') || {};
@@ -435,6 +442,7 @@ const iterateAllJsdocs = (iterator, ruleConfig) => {
 };
 
 export {
+  getSettings,
   parseComment
 };
 
@@ -478,7 +486,7 @@ export default function iterateJsdoc (iterator, ruleConfig) {
       const settings = getSettings(context);
 
       const checkJsdoc = (node) => {
-        const jsdocNode = getJSDocComment(sourceCode, node);
+        const jsdocNode = getJSDocComment(sourceCode, node, settings);
 
         if (!jsdocNode) {
           return;

diff --git a/src/rules/requireJsdoc.js b/src/rules/requireJsdoc.js
@@ -3,6 +3,7 @@ import jsdocUtils from '../jsdocUtils';
 import exportParser from '../exportParser';
 import getJSDocComment from '../eslint/getJSDocComment';
 import warnRemovedSettings from '../warnRemovedSettings';
+import {getSettings} from '../iterateJsdoc';
 
 const OPTIONS_SCHEMA = {
   additionalProperties: false,
@@ -141,8 +142,10 @@ export default {
 
     const {require: requireOption, publicOnly, exemptEmptyFunctions} = getOptions(context);
 
+    const settings = getSettings(context);
+
     const checkJsDoc = (node) => {
-      const jsDocNode = getJSDocComment(sourceCode, node);
+      const jsDocNode = getJSDocComment(sourceCode, node, settings);
 
       if (jsDocNode) {
         return;

diff --git a/test/eslint/getJSDocComment.js b/test/eslint/getJSDocComment.js
@@ -2,6 +2,7 @@ import {
   RuleTester
 } from 'eslint';
 import getJSDocComment from '../../src/eslint/getJSDocComment';
+import {getSettings} from '../../src/iterateJsdoc';
 
 /* eslint-disable sort-keys */
 const rule = {
@@ -13,10 +14,11 @@ const rule = {
   },
   create (context) {
     const sourceCode = context.getSourceCode();
+    const settings = getSettings(context);
 
     return {
       ObjectExpression: (node) => {
-        const comment = getJSDocComment(sourceCode, node);
+        const comment = getJSDocComment(sourceCode, node, settings);
         if (comment !== null) {
           return;
         }

diff --git a/test/rules/assertions/requireJsdoc.js b/test/rules/assertions/requireJsdoc.js
@@ -4,6 +4,66 @@
 
 export default {
   invalid: [
+    {
+      code: `
+       /**
+        * @func myFunction
+        */
+       function myFunction() {
+       
+       }
+       `,
+      errors: [
+        {
+          message: 'Missing JSDoc comment.'
+        }
+      ],
+      settings: {
+        jsdoc: {
+          maxLines: 3,
+          minLines: 2
+        }
+      }
+    },
+    {
+      code: `
+       /**
+        * @func myFunction
+        */
+        
+        
+       function myFunction() {
+       
+       }
+       `,
+      errors: [
+        {
+          message: 'Missing JSDoc comment.'
+        }
+      ],
+      settings: {
+        jsdoc: {
+          maxLines: 2
+        }
+      }
+    },
+    {
+      code: `
+       /** @func myFunction */ function myFunction() {
+       
+       }
+       `,
+      errors: [
+        {
+          message: 'Missing JSDoc comment.'
+        }
+      ],
+      settings: {
+        jsdoc: {
+          minLines: 1
+        }
+      }
+    },
     {
       code: `
           export var test = function () {
@@ -1130,6 +1190,71 @@ export default {
       Object.keys(object).forEach(function() {})
     `
   },
+  {
+    code: `
+       /**
+        * @func myFunction
+        */
+       
+       function myFunction() {
+       
+       }
+       `,
+    settings: {
+      jsdoc: {
+        maxLines: 2,
+        minLines: 0
+      }
+    }
+  },
+  {
+    code: `
+     /**
+      * @func myFunction
+      */
+     
+     
+     function myFunction() {
+     
+     }
+     `,
+    settings: {
+      jsdoc: {
+        maxLines: 3,
+        minLines: 0
+      }
+    }
+  },
+  {
+    code: `
+        /** @func myFunction */  function myFunction() {
+   
+        }
+   `,
+    settings: {
+      jsdoc: {
+        maxLines: 0,
+        minLines: 0
+      }
+    }
+  },
+  {
+    code: `
+        /** 
+         * @func myFunction
+         */
+         
+        function myFunction() {
+ 
+        }
+    `,
+    settings: {
+      jsdoc: {
+        maxLines: 3,
+        minLines: 2
+      }
+    }
+  },
   {
     code: 'function myFunction() {}',
     options: [{