docs: add metadata for parser/processor

docs/src/extend/custom-parsers.md

@@ -12,6 +12,24 @@ ESLint custom parsers let you extend ESLint to support linting new non-standard
 
 ## Creating a Custom Parser
 
+### Metadata 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`.
+
+### 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 +51,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`.
 

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
@@ -45,6 +49,8 @@ module.exports = {
 };
 ```
 
+**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`.
+
 **The `preprocess` method** takes the file contents and filename as arguments, and returns an array of code blocks to lint. The code blocks will be linted separately but still be registered to the filename.
 
 A code block has two properties `text` and `filename`. The `text` property is the content of the block and the `filename` property is the name of the block. The name of the block can be anything, but should include the file extension, which tells the linter how to process the current block. The linter checks the [`--ext` CLI option](../use/command-line-interface#--ext) to see if the current block should be linted and resolves `overrides` configs to check how to process the current block.