docs: add metadata for parser/processor (#17438)

JLHwung · nzakas · web-flow · commit d743ed3c06c6 · 2023-08-01T21:51:00.000+05:30
* docs: add metadata for parser/processor

* Update docs/src/extend/custom-parsers.md

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;

* review comments

* rearrange `meta` object after `postprocess`

---------

Co-authored-by: Nicholas C. Zakas &lt;nicholas@humanwhocodes.com&gt;
diff --git a/docs/src/extend/custom-parsers.md b/docs/src/extend/custom-parsers.md
@@ -12,6 +12,8 @@ ESLint custom parsers let you extend ESLint to support linting new non-standard
 
 ## Creating a Custom Parser
 
+### Methods in Custom Parsers
+
 A custom parser is a JavaScript object with either a `parse` or `parseForESLint` method. The `parse` method only returns the AST, whereas `parseForESLint` also returns additional values that let the parser customize the behavior of ESLint even more.
 
 Both methods should take in the source code as the first argument, and an optional configuration object as the second argument, which is provided as [`parserOptions`](../use/configure/language-options#specifying-parser-options) in a configuration file.
@@ -33,11 +35,11 @@ function parse(code, options) {
 module.exports = { parse };
 ```
 
-## `parse` Return Object
+### `parse` Return Object
 
 The `parse` method should simply return the [AST](#ast-specification) object.
 
-## `parseForESLint` Return Object
+### `parseForESLint` Return Object
 
 The `parseForESLint` method should return an object that contains the required property `ast` and optional properties `services`, `scopeManager`, and `visitorKeys`.
 
@@ -48,6 +50,22 @@ The `parseForESLint` method should return an object that contains the required p
 * `visitorKeys` can be an object to customize AST traversal. The keys of the object are the type of AST nodes. Each value is an array of the property names which should be traversed. The default is [KEYS of `eslint-visitor-keys`](https://github.com/eslint/eslint-visitor-keys#evkkeys).
     * Support for `visitorKeys` was added in ESLint v4.14.0. ESLint versions that support `visitorKeys` will provide an `eslintVisitorKeys: true` property in `parserOptions`, which can be used for feature detection.
 
+### Meta Data in Custom Parsers
+
+For easier debugging and more effective caching of custom parsers, it's recommended to provide a name and version in a `meta` object at the root of your custom parsers, like this:
+
+```js
+// preferred location of name and version
+module.exports = {
+    meta: {
+        name: "eslint-parser-custom",
+        version: "1.2.3"
+    }
+};
+```
+
+The `meta.name` property should match the npm package name for your custom parser and the `meta.version` property should match the npm package version for your custom parser. The easiest way to accomplish this is by reading this information from your `package.json`.
+
 ## AST Specification
 
 The AST that custom parsers should create is based on [ESTree](https://github.com/estree/estree). The AST requires some additional properties about detail information of the source code.
diff --git a/docs/src/extend/custom-processors.md b/docs/src/extend/custom-processors.md
@@ -18,6 +18,10 @@ In order to create a custom processor, the object exported from your module has
 module.exports = {
     processors: {
         "processor-name": {
+            meta: {
+                name: "eslint-processor-name",
+                version: "1.2.3"
+            },
             // takes text of the file and filename
             preprocess: function(text, filename) {
                 // here, you can strip out any non-JS content
@@ -121,6 +125,8 @@ By default, ESLint does not perform autofixes when a custom processor is used, e
 
 You can have both rules and custom processors in a single plugin. You can also have multiple processors in one plugin. To support multiple extensions, add each one to the `processors` element and point them to the same object.
 
+**The `meta` object** helps ESLint cache the processor and provide more friendly debug message. The `meta.name` property should match the processor name and the `meta.version` property should match the npm package version for your processors. The easiest way to accomplish this is by reading this information from your `package.json`.
+
 ## Specifying Processor in Config Files
 
 To use a processor, add its ID to a `processor` section in the config file. Processor ID is a concatenated string of plugin name and processor name with a slash as a separator. This can also be added to a `overrides` section of the config, to specify which processors should handle which files.
diff --git a/docs/src/extend/plugins.md b/docs/src/extend/plugins.md
@@ -18,34 +18,6 @@ Each plugin is an npm module with a name in the format of `eslint-plugin-<plugin
 
 The easiest way to start creating a plugin is to use the [Yeoman generator](https://www.npmjs.com/package/generator-eslint). The generator will guide you through setting up the skeleton of a plugin.
 
-### Metadata in Plugins
-
-For easier debugging and more effective caching of plugins, it's recommended to provide a name and version in a `meta` object at the root of your plugin, like this:
-
-```js
-// preferred location of name and version
-module.exports = {
-    meta: {
-        name: "eslint-plugin-custom",
-        version: "1.2.3"
-    }
-};
-```
-
-The `meta.name` property should match the npm package name for your plugin and the `meta.version` property should match the npm package version for your plugin. The easiest way to accomplish this is by reading this information from your `package.json`.
-
-As an alternative, you can also expose `name` and `version` properties at the root of your plugin, such as:
-
-```js
-// alternate location of name and version
-module.exports = {
-    name: "eslint-plugin-custom",
-    version: "1.2.3"
-};
-```
-
-While the `meta` object is the preferred way to provide the plugin name and version, this format is also acceptable and is provided for backward compatibility.
-
 ### Rules in Plugins
 
 Plugins can expose custom rules for use in ESLint. To do so, the plugin must export a `rules` object containing a key-value mapping of rule ID to rule. The rule ID does not have to follow any naming convention (so it can just be `dollar-sign`, for instance). To learn more about creating custom rules in plugins, refer to [Custom Rules](custom-rules).
@@ -163,6 +135,34 @@ If the example plugin above were called `eslint-plugin-myPlugin`, the `myConfig`
 
 ```
 
+### Meta Data in Plugins
+
+For easier debugging and more effective caching of plugins, it's recommended to provide a name and version in a `meta` object at the root of your plugin, like this:
+
+```js
+// preferred location of name and version
+module.exports = {
+    meta: {
+        name: "eslint-plugin-custom",
+        version: "1.2.3"
+    }
+};
+```
+
+The `meta.name` property should match the npm package name for your plugin and the `meta.version` property should match the npm package version for your plugin. The easiest way to accomplish this is by reading this information from your `package.json`.
+
+As an alternative, you can also expose `name` and `version` properties at the root of your plugin, such as:
+
+```js
+// alternate location of name and version
+module.exports = {
+    name: "eslint-plugin-custom",
+    version: "1.2.3"
+};
+```
+
+While the `meta` object is the preferred way to provide the plugin name and version, this format is also acceptable and is provided for backward compatibility.
+
 ### Peer Dependency
 
 To make clear that the plugin requires ESLint to work correctly, you must declare ESLint as a peer dependency by mentioning it in the `peerDependencies` field of your plugin's `package.json`.
