docs: Formatters page updates

Makefile.js

@@ -447,8 +447,9 @@ function lintMarkdown(files) {
  */
 function getFormatterResults() {
     const stripAnsi = require("strip-ansi");
+    const formattersMetadata = require("./lib/cli-engine/formatters/_manifest");
 
-    const formatterFiles = fs.readdirSync("./lib/cli-engine/formatters/"),
+    const formatterFiles = fs.readdirSync("./lib/cli-engine/formatters/").filter(fileName => !fileName.includes("_manifest.js")),
         rules = {
             "no-else-return": "warn",
             indent: ["warn", 4],
@@ -489,7 +490,8 @@ function getFormatterResults() {
             );
 
             data.formatterResults[name] = {
-                result: stripAnsi(formattedOutput)
+                result: stripAnsi(formattedOutput),
+                description: formattersMetadata.find(formatter => formatter.name === name).description
             };
         }
         return data;

lib/cli-engine/formatters/_manifest.js

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Metadata about built-in formatters
+ * @author Ben Perlmutter
+ */
+"use strict";
+
+/**
+ * @typedef Formatter
+ * @type {Object}
+ * @property {string} name Name of formatter.
+ * @property {string} description Description of formatter in Markdown.
+ */
+
+/**
+ * @type {Array<Formatter>} Array of Formatter metadata objects
+ */
+const formatterMetadata = [
+    {
+        name: "checkstyle",
+        description: "Outputs results to the [Checkstyle](https://checkstyle.sourceforge.io/) format."
+    },
+    {
+        name: "compact",
+        description: "Human-readable output format. Mimics the default output of JSHint."
+    },
+    {
+        name: "html",
+        description: "Outputs results to HTML. The `html` formatter is useful for visual presentation in the browser."
+    },
+    {
+        name: "jslint-xml",
+        description: "Outputs results to format compatible with the [JSLint Jenkins plugin](https://plugins.jenkins.io/jslint/)."
+    },
+    {
+        name: "json-with-metadata",
+        description: "Outputs JSON-serialized results. The `json-with-meta` provides the same linting results as the [`json`](#json) formatter with additional metadata about the rules applied. The linting results are included in the `results` property and the rules metadata is included in the `metadata` property.\n\nAlternatively, you can use the [ESLint Node.js API](../../developer-guide/nodejs-api.md) to programmatically use ESLint."
+    },
+    {
+        name: "json",
+        description: "Outputs JSON-serialized results. The `json` formatter is useful when you want to programmatically work with the CLI's linting results.\n\nAlternatively, you can use the [ESLint Node.js API](../../developer-guide/nodejs-api.md) to programmatically use ESLint."
+    },
+    {
+        name: "junit",
+        description: "Outputs results to format compatible with the [JUnit Jenkins plugin](https://plugins.jenkins.io/junit/)."
+    },
+    {
+        name: "stylish",
+        description: "Human-readable output format. This is the default formatter."
+    },
+    {
+        name: "tap",
+        description: "Outputs results to the [Test Anything Protocol (TAP)](https://testanything.org/) specification format."
+    },
+    {
+        name: "unix",
+        description: "Outputs results to a format similar to many commands in UNIX-like systems. Parsable with tools such as [grep](https://www.gnu.org/software/grep/manual/grep.html), [sed](https://www.gnu.org/software/sed/manual/sed.html), and [awk](https://www.gnu.org/software/gawk/manual/gawk.html)."
+    },
+    {
+        name: "visualstudio",
+        description: "Outputs results to format compatible with the integrated terminal of the [Visual Studio](https://visualstudio.microsoft.com/) IDE. When using Visual Studio, you can click on the linting results in the integrated terminal to go to the issue in the source code."
+    }
+];
+
+module.exports = formatterMetadata;

templates/formatter-examples.md.ejs

@@ -10,7 +10,7 @@ edit_link: https://github.com/eslint/eslint/edit/main/templates/formatter-exampl
 
 ESLint comes with several built-in formatters to control the appearance of the linting results, and supports third-party formatters as well.
 
-You can specify a formatter using the `--format` or `-f` flag on the command line. For example, `--format json` uses the `json` formatter.
+You can specify a formatter using the `--format` or `-f` flag in the CLI. For example, `--format json` uses the `json` formatter.
 
 The built-in formatter options are:
 
@@ -22,7 +22,7 @@ The built-in formatter options are:
 
 Examples of each formatter were created from linting `fullOfProblems.js` using the `.eslintrc` configuration shown below.
 
-### `fullOfProblems.js`
+`fullOfProblems.js`:
 
 ```js
 function addOne(i) {
@@ -34,7 +34,7 @@ function addOne(i) {
 };
 ```
 
-### `.eslintrc`
+`.eslintrc.json`:
 
 ```json
 {
@@ -49,17 +49,28 @@ function addOne(i) {
 }
 ```
 
-## Output Examples
+Tests the formatters with the CLI:
+
+```shell
+npx eslint --formatter <Add formatter here> fullOfProblems.js
+```
+
+## Built-In Formatter Options
+
 <% Object.keys(formatterResults).forEach(function(formatterName) { -%>
 
 ### <%= formatterName %>
-<% if (formatterName !== "html") { -%>
 
+<%= formatterResults[formatterName].description %>
+
+Example output:
+
+<% if (formatterName !== "html") { -%>
 ```text
 <%= formatterResults[formatterName].result %>
 ```
 <% } else {-%>
-
 <iframe src="html-formatter-example.html" width="100%" height="460px"></iframe>
 <% } -%>
+
 <% }) -%>