docs: Clarifying the Use of Meta Objects (#18697)

* docs: Clarifying the Use of Meta Objects * Update plugin-migration-flat-config.md * specify meta object usage in custom processors * Update custom-processors.md * Update custom-processors.md * Update custom-processors.md * address revie changes * Update docs/src/extend/plugin-migration-flat-config.md Co-authored-by: Milos Djermanovic <[email protected]> * update custom-processors.md --------- Co-authored-by: Milos Djermanovic <[email protected]>
eslint · Oct 2, 2024 · 7ea4ecc · 7ea4ecc
1 parent d3e4b2e
commit 7ea4ecc
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 2 deletions.
diff --git a/docs/src/extend/custom-processors.md b/docs/src/extend/custom-processors.md
@@ -140,7 +140,56 @@ 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`.
+### How `meta` Objects are Used
+
+The `meta` object helps ESLint cache configurations that use a processor and to provide more friendly debug messages.
+
+#### Plugin `meta` Object
+
+The [plugin `meta` object](plugins#meta-data-in-plugins) provides information about the plugin itself. When a processor is specified using the string format `plugin-name/processor-name`, ESLint automatically uses the plugin `meta` to generate a name for the processor. This is the most common case for processors.
+
+Example:
+
+```js
+// eslint.config.js
+import example from "eslint-plugin-example";
+
+export default [
+    {
+        plugins: {
+            example
+        },
+        processor: "example/processor-name"
+    },
+    // ... other configs
+];
+```
+
+In this example, the processor name is `"example/processor-name"`, and that's the value that will be used for serializing configurations.
+
+#### Processor `meta` Object
+
+Each processor can also specify its own `meta` object. This information is used when the processor object is passed directly to `processor` in a configuration. In that case, ESLint doesn't know which plugin the processor belongs to. 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`.
+
+Example:
+
+```js
+// eslint.config.js
+import example from "eslint-plugin-example";
+
+export default [
+    {
+        processor: example.processors["processor-name"]
+    },
+    // ... other configs
+];
+```
+
+In this example, specifying `example.processors["processor-name"]` directly uses the processor's own `meta` object, which must be defined to ensure proper handling when the processor is not referenced through the plugin name.
+
+#### Why Both Meta Objects are Needed
+
+It is recommended that both the plugin and each processor provide their respective meta objects. This ensures that features relying on meta objects, such as `--print-config` and `--cache`, work correctly regardless of how the processor is specified in the configuration.
 
 ## Specifying Processor in Config Files
 

diff --git a/docs/src/extend/plugin-migration-flat-config.md b/docs/src/extend/plugin-migration-flat-config.md
@@ -63,7 +63,9 @@ No changes are necessary for the `rules` key in your plugin. Everything works th
 
 ## Migrating Processors for Flat Config
 
-No changes are necessary for the `processors` key in your plugin as long as you aren't using file extension-named processors. If you have any [file extension-named processors](custom-processors-deprecated#file-extension-named-processor), you must update the name to a valid identifier (numbers and letters). File extension-named processors were automatically applied in the old configuration system but are not automatically applied when using flat config. Here is an example of a file extension-named processor:
+Each processor should specify a `meta` object. For more information, see the [full documentation](custom-processors).
+
+No other changes are necessary for the `processors` key in your plugin as long as you aren't using file extension-named processors. If you have any [file extension-named processors](custom-processors-deprecated#file-extension-named-processor), you must update the name to a valid identifier (numbers and letters). File extension-named processors were automatically applied in the old configuration system but are not automatically applied when using flat config. Here is an example of a file extension-named processor:
 
 ```js
 const plugin = {