Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: move RuleTester documentation to Node.js API page #9273

Merged
merged 1 commit into from Sep 10, 2017

Conversation

not-an-aardvark
Copy link
Member

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 the eslint 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 of RuleTester.describe and RuleTester.it (namely, RuleTester will still work even if global.describe and global.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 providing parserOptions, filename, settings, and globals, 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. the env 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.)

@not-an-aardvark not-an-aardvark added the documentation Relates to ESLint's documentation label Sep 9, 2017
@mention-bot
Copy link

@not-an-aardvark, thanks for your PR! By analyzing the history of the files in this pull request, we identified @nzakas, @evangoer and @gyandeeps to be potential reviewers.

@eslintbot
Copy link

LGTM

@not-an-aardvark not-an-aardvark changed the title Docs: move RuleTester documentation to Node.js API docs Docs: move RuleTester documentation to Node.js API page Sep 9, 2017
@eslint eslint deleted a comment from eslintbot Sep 9, 2017
@not-an-aardvark not-an-aardvark merged commit cd698ba into master Sep 10, 2017
@not-an-aardvark not-an-aardvark deleted the rule-tester-to-api-docs branch September 10, 2017 03:20
@eslint-deprecated eslint-deprecated bot locked and limited conversation to collaborators Mar 10, 2018
@eslint-deprecated eslint-deprecated bot added the archived due to age This issue has been archived; please open a new issue for any further discussion label Mar 10, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
archived due to age This issue has been archived; please open a new issue for any further discussion documentation Relates to ESLint's documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants