docs: disambiguate types FormatterFunction and LoadedFormatter (#15727)

fasttime · web-flow · commit f2c2d3504252 · 2022-04-04T11:30:37.000+02:00
* chore: disambiguate types `FormatterFunction` and `LoadedFormatter` Fixes #15654 * Code review update * Remove redundant `LintResult` type import * Remove note about `context` argument of `FormatterFunction` from JSDoc * docs: Revert to using variable name `formatter` in code examples
diff --git a/docs/developer-guide/nodejs-api.md b/docs/developer-guide/nodejs-api.md
@@ -21,7 +21,7 @@ While ESLint is designed to be run on the command line, it's possible to use ESL
     * [LintMessage type][lintmessage]
     * [SuppressedLintMessage type][suppressedlintmessage]
     * [EditInfo type][editinfo]
-    * [Formatter type][formatter]
+    * [LoadedFormatter type][loadedformatter]
 * [SourceCode](#sourcecode)
     * [splitLines()](#sourcecodesplitlines)
 * [Linter](#linter)
@@ -287,8 +287,8 @@ This method loads a formatter. Formatters convert lint results to a human- or ma
 
 #### Return Value
 
-* (`Promise<Formatter>`)<br>
-  The promise that will be fulfilled with a [Formatter] object.
+* (`Promise<LoadedFormatter>`)<br>
+  The promise that will be fulfilled with a [LoadedFormatter] object.
 
 ### ◆ ESLint.version
 
@@ -430,9 +430,9 @@ The `EditInfo` value is information to edit text. The `fix` and `suggestions` pr
 
 This edit information means replacing the range of the `range` property by the `text` property value. It's like `sourceCodeText.slice(0, edit.range[0]) + edit.text + sourceCodeText.slice(edit.range[1])`. Therefore, it's an add if the `range[0]` and `range[1]` property values are the same value, and it's removal if the `text` property value is empty string.
 
-### ◆ Formatter type
+### ◆ LoadedFormatter type
 
-The `Formatter` value is the object to convert the [LintResult] objects to text. The [eslint.loadFormatter()][eslint-loadformatter] method returns it. It has the following method:
+The `LoadedFormatter` value is the object to convert the [LintResult] objects to text. The [eslint.loadFormatter()][eslint-loadformatter] method returns it. It has the following method:
 
 * `format` (`(results: LintResult[]) => string | Promise<string>`)<br>
   The method to convert the [LintResult] objects to text.
@@ -960,5 +960,5 @@ ruleTester.run("my-rule", myRule, {
 [lintmessage]: #-lintmessage-type
 [suppressedlintmessage]: #-suppressedlintmessage-type
 [editinfo]: #-editinfo-type
-[formatter]: #-formatter-type
+[loadedformatter]: #-loadedformatter-type
 [linter]: #linter
diff --git a/docs/developer-guide/working-with-custom-formatters.md b/docs/developer-guide/working-with-custom-formatters.md
@@ -2,7 +2,7 @@
 
 While ESLint has some built-in formatters available to format the linting results, it's also possible to create and distribute your own custom formatters. You can include custom formatters in your project directly or create an npm package to distribute them separately.
 
-Each formatter is just a function that receives a `results` object and returns a string. For example, the following is how the `json` built-in formatter is implemented:
+Each formatter is just a function that receives a `results` object and a `context` and returns a string. For example, the following is how the `json` built-in formatter is implemented:
 
 ```js
 //my-awesome-formatter.js
@@ -11,7 +11,7 @@ module.exports = function(results, context) {
 };
 ```
 
-Formatter can also be an async function (from ESLint v8.4.0), the following shows a simple example:
+A formatter can also be an async function (from ESLint v8.4.0), the following shows a simple example:
 
 ```js
 //my-awesome-formatter.js
@@ -280,7 +280,7 @@ warning no-unused-vars (https://eslint.org/docs/rules/no-unused-vars)
 
 ## Passing Arguments to Formatters
 
-While custom formatter do not receive arguments in addition to the results object, it is possible to pass additional data into formatters.
+While formatter functions do not receive arguments in addition to the results object and the context, it is possible to pass additional data into custom formatters using the methods described below.
 
 ## Using Environment Variables
 
diff --git a/lib/cli-engine/cli-engine.js b/lib/cli-engine/cli-engine.js
@@ -56,6 +56,7 @@ const validFixTypes = new Set(["directive", "problem", "suggestion", "layout"]);
 /** @typedef {import("../shared/types").Plugin} Plugin */
 /** @typedef {import("../shared/types").RuleConf} RuleConf */
 /** @typedef {import("../shared/types").Rule} Rule */
+/** @typedef {import("../shared/types").FormatterFunction} FormatterFunction */
 /** @typedef {ReturnType<CascadingConfigArrayFactory.getConfigArrayForFile>} ConfigArray */
 /** @typedef {ReturnType<ConfigArray.extractConfig>} ExtractedConfig */
 
@@ -1002,7 +1003,7 @@ class CLIEngine {
      * @param {string} [format] The name of the format to load or the path to a
      *      custom formatter.
      * @throws {any} As may be thrown by requiring of formatter
-     * @returns {(Function|null)} The formatter function or null if the `format` is not a string.
+     * @returns {(FormatterFunction|null)} The formatter function or null if the `format` is not a string.
      */
     getFormatter(format) {
 
diff --git a/lib/eslint/eslint.js b/lib/eslint/eslint.js
@@ -35,10 +35,11 @@ const { version } = require("../../package.json");
 /** @typedef {import("../shared/types").SuppressedLintMessage} SuppressedLintMessage */
 /** @typedef {import("../shared/types").Plugin} Plugin */
 /** @typedef {import("../shared/types").Rule} Rule */
+/** @typedef {import("../shared/types").LintResult} LintResult */
 
 /**
  * The main formatter object.
- * @typedef Formatter
+ * @typedef LoadedFormatter
  * @property {function(LintResult[]): string | Promise<string>} format format function.
  */
 
@@ -74,22 +75,6 @@ const { version } = require("../../package.json");
  * @property {Object} definition The plugin definition.
  */
 
-/**
- * A linting result.
- * @typedef {Object} LintResult
- * @property {string} filePath The path to the file that was linted.
- * @property {LintMessage[]} messages All of the messages for the result.
- * @property {SuppressedLintMessage[]} suppressedMessages All of the suppressed messages for the result.
- * @property {number} errorCount Number of errors for the result.
- * @property {number} fatalErrorCount Number of fatal errors for the result.
- * @property {number} warningCount Number of warnings for the result.
- * @property {number} fixableErrorCount Number of fixable errors for the result.
- * @property {number} fixableWarningCount Number of fixable warnings for the result.
- * @property {string} [source] The source code of the file that was linted.
- * @property {string} [output] The source code of the file that was linted, with as many fixes applied as possible.
- * @property {DeprecatedRuleInfo[]} usedDeprecatedRules The list of used deprecated rules.
- */
-
 /**
  * Private members for the `ESLint` instance.
  * @typedef {Object} ESLintPrivateMembers
@@ -619,7 +604,7 @@ class ESLint {
      *   - `@foo` → `@foo/eslint-formatter`
      *   - `@foo/bar` → `@foo/eslint-formatter-bar`
      * - A file path ... Load the file.
-     * @returns {Promise<Formatter>} A promise resolving to the formatter object.
+     * @returns {Promise<LoadedFormatter>} A promise resolving to the formatter object.
      * This promise will be rejected if the given formatter was not found or not
      * a function.
      */
@@ -639,7 +624,7 @@ class ESLint {
 
             /**
              * The main formatter method.
-             * @param {LintResults[]} results The lint results to format.
+             * @param {LintResult[]} results The lint results to format.
              * @returns {string | Promise<string>} The formatted lint results.
              */
             format(results) {
diff --git a/lib/shared/types.js b/lib/shared/types.js
@@ -173,3 +173,27 @@ module.exports = {};
  * @property {string} ruleId The rule ID.
  * @property {string[]} replacedBy The rule IDs that replace this deprecated rule.
  */
+
+/**
+ * A linting result.
+ * @typedef {Object} LintResult
+ * @property {string} filePath The path to the file that was linted.
+ * @property {LintMessage[]} messages All of the messages for the result.
+ * @property {SuppressedLintMessage[]} suppressedMessages All of the suppressed messages for the result.
+ * @property {number} errorCount Number of errors for the result.
+ * @property {number} fatalErrorCount Number of fatal errors for the result.
+ * @property {number} warningCount Number of warnings for the result.
+ * @property {number} fixableErrorCount Number of fixable errors for the result.
+ * @property {number} fixableWarningCount Number of fixable warnings for the result.
+ * @property {string} [source] The source code of the file that was linted.
+ * @property {string} [output] The source code of the file that was linted, with as many fixes applied as possible.
+ * @property {DeprecatedRuleInfo[]} usedDeprecatedRules The list of used deprecated rules.
+ */
+
+/**
+ * A formatter function.
+ * @callback FormatterFunction
+ * @param {LintResult[]} results The list of linting results.
+ * @param {{cwd: string, rulesMeta: Record<string, RuleMeta>}} [context] A context object.
+ * @returns {string | Promise<string>} Formatted text.
+ */
