refactor: Improve function names, add JSDoc to functions.

Author: Rebecca Stevens

src/common/ignore-options.ts

@@ -125,6 +125,11 @@ export const ignoreNewArrayOptionSchema: JSONSchema4 = {
   additionalProperties: false
 };
 
+/**
+ * Recursive callback of `getNodeText`.
+ *
+ * This function not be called from anywhere else.
+ */
 function _getNodeText(
   node: TSESTree.Node,
   context: RuleContext<string, BaseOptions>
@@ -139,6 +144,9 @@ function _getNodeText(
     : context.getSourceCode().getText(node);
 }
 
+/**
+ * Get the text of the given node.
+ */
 function getNodeText(
   node: TSESTree.Node,
   context: RuleContext<string, BaseOptions>
@@ -156,6 +164,9 @@ function getNodeText(
     : _getNodeText(node, context);
 }
 
+/**
+ * Get all the important bits of texts from the given node.
+ */
 function getNodeTexts(
   node: TSESTree.Node,
   context: RuleContext<string, BaseOptions>
@@ -166,7 +177,12 @@ function getNodeTexts(
   ).filter(name => name !== undefined) as ReadonlyArray<string>;
 }
 
-function isIgnoredPattern(
+/**
+ * Should the given text be ignore?
+ *
+ * Test using the given pattern(s).
+ */
+function shouldIgnoreViaPattern(
   text: string,
   ignorePattern: ReadonlyArray<string> | string
 ): boolean {
@@ -178,7 +194,14 @@ function isIgnoredPattern(
   return patterns.some(pattern => new RegExp(pattern).test(text));
 }
 
-function findMatch(
+/**
+ * Recursive callback of `shouldIgnoreViaAccessorPattern`.
+ *
+ * This function not be called from anywhere else.
+ *
+ * Does the given text match the given pattern.
+ */
+function accessorPatternMatch(
   [pattern, ...remainingPatternParts]: ReadonlyArray<string>,
   textParts: ReadonlyArray<string>,
   allowExtra: boolean = false
@@ -188,23 +211,41 @@ function findMatch(
     : // Match any depth (including 0)?
     pattern === "**"
     ? textParts.length === 0
-      ? findMatch(remainingPatternParts, [], allowExtra)
+      ? accessorPatternMatch(remainingPatternParts, [], allowExtra)
       : Array.from({ length: textParts.length })
           .map((_element, index) => index)
           .some(offset =>
-            findMatch(remainingPatternParts, textParts.slice(offset), true)
+            accessorPatternMatch(
+              remainingPatternParts,
+              textParts.slice(offset),
+              true
+            )
           )
     : // Match anything?
     pattern === "*"
     ? textParts.length > 0 &&
-      findMatch(remainingPatternParts, textParts.slice(1), allowExtra)
+      accessorPatternMatch(
+        remainingPatternParts,
+        textParts.slice(1),
+        allowExtra
+      )
     : // Text matches pattern?
       new RegExp("^" + escapeRegExp(pattern).replace(/\\\*/g, ".*") + "$").test(
         textParts[0]
-      ) && findMatch(remainingPatternParts, textParts.slice(1), allowExtra);
+      ) &&
+      accessorPatternMatch(
+        remainingPatternParts,
+        textParts.slice(1),
+        allowExtra
+      );
 }
 
-function isIgnoredAccessorPattern(
+/**
+ * Should the given text be ignore?
+ *
+ * Test using the given accessor pattern(s).
+ */
+function shouldIgnoreViaAccessorPattern(
   text: string,
   ignorePattern: ReadonlyArray<string> | string
 ): boolean {
@@ -214,7 +255,7 @@ function isIgnoredAccessorPattern(
 
   // One or more patterns match?
   return patterns.some(pattern =>
-    findMatch(pattern.split("."), text.split("."))
+    accessorPatternMatch(pattern.split("."), text.split("."))
   );
 }
 
@@ -238,12 +279,15 @@ export function shouldIgnore(
         ? // Ignore if ignorePattern is set and a pattern matches.
           (options.ignorePattern !== undefined &&
             texts.every(text =>
-              isIgnoredPattern(text, options.ignorePattern!)
+              shouldIgnoreViaPattern(text, options.ignorePattern!)
             )) ||
           // Ignore if ignoreAccessorPattern is set and an accessor pattern matches.
           (options.ignoreAccessorPattern !== undefined &&
             texts.every(text =>
-              isIgnoredAccessorPattern(text, options.ignoreAccessorPattern!)
+              shouldIgnoreViaAccessorPattern(
+                text,
+                options.ignoreAccessorPattern!
+              )
             ))
         : false)(getNodeTexts(node, context))
   );

src/rules/functional-parameters.ts

@@ -83,8 +83,11 @@ const meta: RuleMetaData<keyof typeof errorMessages> = {
   schema
 };
 
+/**
+ * Get the rest parameter violations.
+ */
 function getRestParamViolations(
-  allowRestParameter: boolean,
+  allowRestParameter: Options["allowRestParameter"],
   node:
     | TSESTree.FunctionDeclaration
     | TSESTree.FunctionExpression
@@ -102,6 +105,9 @@ function getRestParamViolations(
     : [];
 }
 
+/**
+ * Get the parameter count violations.
+ */
 function getParamCountViolations(
   enforceParameterCount: Options["enforceParameterCount"],
   node:

src/rules/no-conditional-statement.ts

@@ -72,6 +72,10 @@ const meta: RuleMetaData<keyof typeof errorMessages> = {
   schema
 };
 
+/**
+ * Get all of the violations in the given if statement assuming if statements
+ * are allowed.
+ */
 function getIfBranchViolations(
   node: TSESTree.IfStatement
 ): RuleResult<keyof typeof errorMessages, Options>["descriptors"] {
@@ -97,7 +101,11 @@ function getIfBranchViolations(
   return nodes.flatMap(node => [{ node, messageId: "incompleteBranch" }]);
 }
 
-function getSwitchCaseViolations(
+/**
+ * Get all of the violations in the given switch statement assuming switch
+ * statements are allowed.
+ */
+function getSwitchViolations(
   node: TSESTree.SwitchStatement
 ): RuleResult<keyof typeof errorMessages, Options>["descriptors"] {
   const nodes = node.cases.reduce<ReadonlyArray<TSESTree.Node>>(
@@ -116,10 +124,16 @@ function getSwitchCaseViolations(
   return nodes.flatMap(node => [{ node, messageId: "incompleteBranch" }]);
 }
 
+/**
+ * Does the given if statement violate this rule if it must be exhaustive.
+ */
 function isExhaustiveIfViolation(node: TSESTree.IfStatement): boolean {
   return node.alternate === null;
 }
 
+/**
+ * Does the given switch statement violate this rule if it must be exhaustive.
+ */
 function isExhaustiveSwitchViolation(node: TSESTree.SwitchStatement): boolean {
   return (
     // No cases defined.
@@ -163,8 +177,8 @@ function checkSwitchStatement(
       ? options.allowReturningBranches === "ifExhaustive"
         ? isExhaustiveSwitchViolation(node)
           ? [{ node, messageId: "incompleteSwitch" }]
-          : getSwitchCaseViolations(node)
-        : getSwitchCaseViolations(node)
+          : getSwitchViolations(node)
+        : getSwitchViolations(node)
       : [{ node, messageId: "unexpectedSwitch" }]
   };
 }

src/util/misc.ts

@@ -1,5 +1,6 @@
 /**
- * Returns a function that checks if the given value is the same as the expected value.
+ * Returns a function that checks if the given value is the same as the expected
+ * value.
  */
 export function isExpected<T>(expected: T): (actual: T) => boolean {
   return actual => actual === expected;

src/util/rule.ts

@@ -65,13 +65,13 @@ export function createRule<
   } as any) as any;
 }
 
+// This function can't be functional as it needs to interact with 3rd-party
+// libraries that aren't functional.
+/* eslint-disable ts-immutable/no-return-void, ts-immutable/no-conditional-statement, ts-immutable/no-expression-statement */
 /**
  * Create a function that processes common options and then runs the given
  * check.
  */
-// This function can't be functional as it needs to interact with 3rd-party
-// libraries that aren't functional.
-/* eslint-disable ts-immutable/no-return-void, ts-immutable/no-conditional-statement, ts-immutable/no-expression-statement */
 export function checkNode<
   MessageIds extends string,
   Context extends RuleContext<MessageIds, BaseOptions>,

src/util/tree.ts

@@ -72,6 +72,9 @@ export function isInReturnType(node: TSESTree.Node): boolean {
   );
 }
 
+/**
+ * Is the given identifier a property of an object?
+ */
 export function isPropertyAccess(node: TSESTree.Identifier): boolean {
   return (
     node.parent !== undefined &&
@@ -80,6 +83,9 @@ export function isPropertyAccess(node: TSESTree.Identifier): boolean {
   );
 }
 
+/**
+ * Is the given identifier a property name?
+ */
 export function isPropertyName(node: TSESTree.Identifier): boolean {
   return (
     node.parent !== undefined &&

src/util/typeguard.ts

@@ -1,5 +1,5 @@
 /**
- * This file has functions that typeguard the given node/type.
+ * @file Functions that typeguard the given node/type.
  */
 
 import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/typescript-estree";
@@ -8,6 +8,9 @@ import { Type, UnionType } from "typescript";
 // TS import - conditionally imported only when typescript is avaliable.
 import ts from "../util/conditional-imports/typescript";
 
+// Any JSDoc for these functions would be tedious.
+/* eslint-disable jsdoc/require-jsdoc */
+
 /*
  * TS Types.
  */
@@ -64,6 +67,11 @@ export function isCallExpression(
   return node.type === AST_NODE_TYPES.CallExpression;
 }
 
+/**
+ * Is the given node a class node?
+ *
+ * It doesn't matter what type of class.
+ */
 export function isClassLike(
   node: TSESTree.Node
 ): node is TSESTree.ClassDeclaration | TSESTree.ClassExpression {
@@ -73,6 +81,11 @@ export function isClassLike(
   );
 }
 
+/**
+ * Is the given node a function node?
+ *
+ * It doesn't matter what type of function.
+ */
 export function isFunctionLike(
   node: TSESTree.Node
 ): node is

tests/util.ts

@@ -65,6 +65,9 @@ export function processValidTestCase(
   return processInvalidTestCase(testCases as any);
 }
 
+/**
+ * Create a dummy rule for testing.
+ */
 export function createDummyRule(
   create: (
     /* eslint-disable-next-line @typescript-eslint/no-explicit-any */