docs: Custom Parsers cleanup/expansion

[bpmutter]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

Custom Parsers page cleanup/expansion

Is there anything you'd like reviewers to focus on?

Resolves #16813

[netlify]

✅ Deploy Preview for docs-eslint ready!

Name	Link
🔨 Latest commit	3f1dc78
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/6404e63bf8795300086fa57a
😎 Deploy Preview	https://deploy-preview-16887--docs-eslint.netlify.app/extend/custom-parsers
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[bpmutter]

question for reviewers: this syntax is a little different from what i'm used to seeing with Node.js.

to my understanding, this is equivalent to the following:

function parseForESLint(code, options){
// function definition
}

module.exports = { parseForESLint }

i think this module.exports = ... pattern is more common.

would we be open to adjusting this example to use the module.exports = ... pattern?

[nzakas]

You're correct, the two are equivalent. No objections to using the pattern you suggest.

[bpmutter]

adding

[bpmutter]

to reviewers, would you mind providing some high level direction on what should be included here? perhaps a simple example with a bit of description?

[nzakas]

Hehe, didn't realize we left a TODO in there.

Basically, what this section should be is how to create an npm package out of your custom parser. I imagine it would simply be:

1. Create your npm package
2. Ensure that main in package.json points to your parser file
3. Publish your npm package
4. Show how to use the npm package in a config file

[bpmutter]

to reviewers, would you mind providing some high level direction on what should be included here? perhaps a simple example with a bit of description?

[fasttime]

I think that the other example on that page is already quite clear. But you would like to add a new example with parse rather than parseForESLint if I understand correctly?

[bpmutter]

yes, that's correct

[fasttime]

You could show just a very simple parser, like one that calls espree and prints a message to the console. This one for example will print the time required to parse each file:

const espree = require("espree");

exports.parse = function (code, options) {
    const label = `Parsing file "${options.filePath}"`;
    console.time(label);
    const ast = espree.parse(code, options);
    console.timeEnd(label);
    return ast; // Only the AST is returned.
};

As I understand it, the only difference is that parse only returns the AST, whereas parseForESLint also returns additional values that let you customize the behavior of the parser even more.

[nzakas]

As I understand it, the only difference is that parse only returns the AST, whereas parseForESLint also returns additional values that let you customize the behavior of the parser even more.

That's correct. The usage is exactly the same. I think @fasttime's example is solid -- anything where parse is calling another parser and somehow manipulating the AST result before returning it would also be appropriate.

[bpmutter]

thank you for the feedback! also TIL about console.time() 💡

[bpmutter]

@nzakas and @fasttime, incorporating your feedback, i refactored the page pretty thoroughly. please re-review when you get a chance 😄

[fasttime]

I won't nitpick on this, but I'm afraid that "Create an npm package" and "Publish the npm package" are not self-explanatory. Maybe we could like these steps to npm init and npm publish respectively, or just show the commands to enter in the shell?

[nzakas]

I think the wording is okay, but would be helpful to link out to some supporting documentation.

[nzakas]

Looking good! Just a couple of notes.

[nzakas]

I think the wording is okay, but would be helpful to link out to some supporting documentation.

[mdjermanovic]

What do we mean by "when it processes a node"?

[nzakas]

Yeah, this description is inaccurate. What this is doing is providing a context.parserServices.foo() for rules.

[bpmutter]

@nzakas, @fasttime, @mdjermanovic, @snitin315, ready for re-review!

[nzakas]

LGTM. Just waiting for others to verify their comments were addressed.

[snitin315]

LGTM. Leaving it open for others to review.

[fasttime]

Just left a suggestion.

[fasttime]

LGTM, thanks! Leaving open for @mdjermanovic to review.

[mdjermanovic]

LGTM, thanks!