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: Improve examples and clarify default option #12067

Merged
merged 2 commits into from Sep 14, 2019

Conversation

zypA13510
Copy link
Contributor

@zypA13510 zypA13510 commented Aug 6, 2019

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

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

What changes did you make? (Give an overview)

  • The "default" option is now set to overrides instead of after because the ternary examples in after may be misleading.
  • Changed the example in overrides to reflect the default behavior. The old one += is removed as it serves no purpose after the change.
  • A new incorrect example is added to overrides to clarify whether the overridden style can still be used.

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

The "default" option is now set to `overrides` instead of `after` because examples in after may be misleading.
A new incorrect example is added to `overrides` to clarify whether the overridden style can still be used.
@eslint-deprecated eslint-deprecated bot added the triage An ESLint team member will look at this issue soon label Aug 6, 2019
@platinumazure platinumazure added documentation Relates to ESLint's documentation evaluating The team will evaluate this issue to decide whether it meets the criteria for inclusion rule Relates to ESLint's core rules and removed triage An ESLint team member will look at this issue soon labels Aug 6, 2019
@platinumazure
Copy link
Member

Hi @zypA13510, thanks for the PR.

I'm a bit confused. Are the docs currently incorrect/showing invalid defaults? What problem are you solving with this change?

@zypA13510
Copy link
Contributor Author

@platinumazure in the same documentation, options section:

The default configuration is "after", { "overrides": { "?": "before", ":": "before" } }

in the incorrect example of "after" (which claims to be the default)

answer = everything
  ? 42
  : foo;

same for the correct example of "after".

Imho, this could be very confusing - if the reader somehow skipped the "real" default above and jumped to the examples directly, or, if the reader read the default, thinking all the example in "after" section is the default (with overrides), they can come to the wrong conclusion and misconfigure this rule.

You can compare the entire document, if that's clearer: before and after

Copy link
Member

@platinumazure platinumazure left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Basically looks good to me, but I have one question. Thanks for your patience!

docs/rules/operator-linebreak.md Outdated Show resolved Hide resolved
@zypA13510
Copy link
Contributor Author

zypA13510 commented Aug 7, 2019

Actually, after reading it again, I think that adding two new examples at the end of "overrides", with some examples from the "after" section included could be better (i.e. show a complete example of the default behavior). What do you think @platinumazure?

Edit: like this[diff]. If ok then I will push it to this PR.

@platinumazure
Copy link
Member

Actually, after reading it again,

Hmm. Not sure which is better. Maybe another team member will have a better idea how to proceed. I'm okay either way at this point.

@zypA13510
Copy link
Contributor Author

Since no one replied to evaluate the two versions. I decided by myself to use the second version and updated this PR. Please review again.

Copy link
Member

@aladdin-add aladdin-add left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks!

@zypA13510
Copy link
Contributor Author

Sorry, I misclicked. @aladdin-add

@platinumazure I think all the changes are now resolved. Review please?

@ilyavolodin ilyavolodin removed evaluating The team will evaluate this issue to decide whether it meets the criteria for inclusion rule Relates to ESLint's core rules labels Sep 14, 2019
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