feat(require-jsdoc): add minLineCount option to avoid reporting s…

…hort functions/contexts; fixes #870
gajus · Apr 12, 2022 · 199aa4a · 199aa4a
1 parent 520c7be
commit 199aa4a
Show file tree

Hide file tree

Showing 4 changed files with 88 additions and 3 deletions.
diff --git a/.README/rules/require-jsdoc.md b/.README/rules/require-jsdoc.md
@@ -92,11 +92,16 @@ if one only wishes documentation on one of the two accessors. Defaults to
 A boolean on whether to enable the fixer (which adds an empty jsdoc block).
 Defaults to `true`.
 
+##### `minLineCount`
+
+An integer to indicate a minimum number of lines expected for a node in order
+for it to require documentation. Defaults to 0.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `ClassDeclaration`, `ClassExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A|
 |Recommended|true|
-|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`|
+|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`|
 
 <!-- assertions requireJsdoc -->
diff --git a/README.md b/README.md
@@ -12884,12 +12884,19 @@ if one only wishes documentation on one of the two accessors. Defaults to
 A boolean on whether to enable the fixer (which adds an empty jsdoc block).
 Defaults to `true`.
 
+<a name="user-content-eslint-plugin-jsdoc-rules-require-jsdoc-options-28-minlinecount"></a>
+<a name="eslint-plugin-jsdoc-rules-require-jsdoc-options-28-minlinecount"></a>
+##### <code>minLineCount</code>
+
+An integer to indicate a minimum number of lines expected for a node in order
+for it to require documentation. Defaults to 0.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `ClassDeclaration`, `ClassExpression`, `FunctionDeclaration`, `FunctionExpression`; others when `contexts` option enabled|
 |Tags|N/A|
 |Recommended|true|
-|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`|
+|Options|`publicOnly`, `require`, `contexts`, `exemptEmptyConstructors`, `exemptEmptyFunctions`, `enableFixer`, `minLineCount`|
 
 The following patterns are considered problems:
 
@@ -13676,6 +13683,14 @@ module.exports = class Utility {
 };
 // "jsdoc/require-jsdoc": ["error"|"warn", {"enableFixer":false,"publicOnly":true,"require":{"ArrowFunctionExpression":true,"ClassDeclaration":true,"ClassExpression":true,"FunctionDeclaration":true,"FunctionExpression":true,"MethodDefinition":true}}]
 // Message: Missing JSDoc comment.
+
+function quux () {
+  return 3;
+}
+
+function b () {}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"minLineCount":2}]
+// Message: Missing JSDoc comment.
 ````
 
 The following patterns are not considered problems:
@@ -14489,6 +14504,13 @@ export class UserSettingsState { }
 export class User {
 }
 // "jsdoc/require-jsdoc": ["error"|"warn", {"contexts":["Decorator"],"require":{"FunctionDeclaration":false}}]
+
+  function quux () {
+  return 3;
+}
+
+function b () {}
+// "jsdoc/require-jsdoc": ["error"|"warn", {"minLineCount":4}]
 ````
 
 

diff --git a/src/rules/requireJsdoc.js b/src/rules/requireJsdoc.js
@@ -82,6 +82,10 @@ const OPTIONS_SCHEMA = {
       default: '',
       type: 'string',
     },
+    minLineCount: {
+      default: 0,
+      type: 'integer',
+    },
     publicOnly: {
       oneOf: [
         {
@@ -164,6 +168,7 @@ const getOptions = (context) => {
     exemptEmptyFunctions = false,
     enableFixer = true,
     fixerMessage = '',
+    minLineCount = 0,
   } = context.options[0] || {};
 
   return {
@@ -172,6 +177,7 @@ const getOptions = (context) => {
     exemptEmptyConstructors,
     exemptEmptyFunctions,
     fixerMessage,
+    minLineCount,
     publicOnly: ((baseObj) => {
       if (!publicOnly) {
         return false;
@@ -213,9 +219,18 @@ export default {
       exemptEmptyConstructors,
       enableFixer,
       fixerMessage,
+      minLineCount,
     } = getOptions(context);
 
     const checkJsDoc = (info, handler, node) => {
+      if (
+        // Optimize
+        minLineCount &&
+        (sourceCode.getText(node).match(/\n/gu)?.length ?? 0) < minLineCount
+      ) {
+        return;
+      }
+
       const jsDocNode = getJSDocComment(sourceCode, node, settings);
 
       if (jsDocNode) {

diff --git a/test/rules/assertions/requireJsdoc.js b/test/rules/assertions/requireJsdoc.js
@@ -3816,7 +3816,6 @@ function quux (foo) {
       `,
       parser: require.resolve('@typescript-eslint/parser'),
     },
-
     {
       code: `
          class Utility {
@@ -3883,6 +3882,36 @@ function quux (foo) {
         },
       ],
     },
+    {
+      code: `
+        function quux () {
+          return 3;
+        }
+
+        function b () {}
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'Missing JSDoc comment.',
+        },
+      ],
+      options: [
+        {
+          minLineCount: 2,
+        },
+      ],
+      output: `
+        /**
+         *
+         */
+        function quux () {
+          return 3;
+        }
+
+        function b () {}
+      `,
+    },
   ],
   valid: [
     {
@@ -5831,5 +5860,19 @@ function quux (foo) {
         },
       ],
     },
+    {
+      code: `
+          function quux () {
+          return 3;
+        }
+
+        function b () {}
+      `,
+      options: [
+        {
+          minLineCount: 4,
+        },
+      ],
+    },
   ],
 };