Docs: move RuleTester documentation to Node.js API page #9273
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What is the purpose of this pull request? (put an "X" next to item)
[x] Documentation update
What changes did you make? (Give an overview)
Previously,
RuleTester
was documented in two different places: the "working with rules" page, and the "working with plugins" page. There was a lot of duplicated information between the two pages, and some information was mentioned on one page but not the other.RuleTester
wasn't mentioned on the "Node.js API" page, even though it's exported by theeslint
module.This commit moves all of the
RuleTester
documentation to the "Node.js API" page, and creates links from the other two pages. It also clarifies the semantics ofRuleTester.describe
andRuleTester.it
(namely,RuleTester
will still work even ifglobal.describe
andglobal.it
aren't available).Is there anything you'd like reviewers to focus on?
Previously, the "working with rules" page provided a lot of examples of how to use
RuleTester
, but it didn't explain the underlying details as thoroughly. For example, it had separate code samples for providingparserOptions
,filename
,settings
, andglobals
, but it didn't mention that some of these options are just passed through to the config. From reading that page, the user would probably be able to replicate the simple examples easily, but they wouldn't be able to figure out that e.g. theenv
property can also be used.On the other hand, the "working with plugins" page described the semantics of the
RuleTester
API in more detail, without providing as many specific examples for each property.Personally, when reading documentation I prefer the second style more than the first style, because then the API feels less "magic" to me, and I then can build abstractions myself rather than copy-pasting examples. As such, I've made the new description on the "Node.js API" page copy mostly from the "working with plugins" page. However, I'm probably not a good judge of the understandability of the docs since I've used
RuleTester
a lot, and some things that seem obvious to me might be confusing for new users.So I'd appreciate if you could point out any places where the updated docs might be difficult to understand, or where an example would be useful. (The updated page has more examples than the "working with plugins" page had, but it still has fewer examples than the "working with rules" page had.)