Docs: Distinguish examples in rules under Stylistic Issues part 7

[scriptdaemon]

What issue does this pull request address?

Documentation update.

What changes did you make? (Give an overview)

Documentation update.

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

• one-var
  • Combined the object properties for each object option. Willing to reconsider if desired.
  • Added language for using one of three different options
• quote-props
  • Do we have special language for object options that only apply based on choices of previous options? My only concern with this rule, I believe.

@pedrottimark Got another batch for ya.

[mention-bot]

@scriptdaemon, thanks for your PR! By analyzing the annotation information on this pull request, we identified @IanVS, @BYK and @pedrottimark to be potential reviewers

[eslintbot]

LGTM

[nzakas]

Hmm, this style is a bit confusing to me. The multiple "this rule has an X option" makes it difficult for me to understand if there's just one option that can be a string or object, or if there are multiple options.

I'd much rather we start with "This rule has two options," as I think that's a lot clearer.

[scriptdaemon]

What if we added language like so:

This rule has a string option:

*Stuff*

And an object option:

*More stuff*

This would make the language consistent with other forms that we currently use, such as:

This rule has a string option:

*Stuff*

Or an object option:

*More stuff*

[nzakas]

Why can't we say, "This rule has two options, a string option and an object option"?

[scriptdaemon]

Why not condense that to "This rule has a string option and an object option" so that it's consistent and makes more sense to say "This rule has two string options" when the options are of the same type? Seems @pedrottimark has been busy, but I'd like to know what he thinks as well since the guidelines would need to be updated.

[ilyavolodin]

@pedrottimark Any suggestions?

[nzakas]

@scriptdaemon As I said, I don't believe it's clear enough. For example "it has a string option and an object option" in one rule and "it has a string option OR an object option" in another. That's a really subtle difference for a reader to pick up, especially if English isn't their first language.

My rule of thumb is that if there's a choice between being explicit or not, always choose being explicit. That would change my examples to "This rule has two options, a string option and an object option" and then "This rule has one option, which can be a string option or an object option." Both of which leave little confusion over what is being described.

If there are other rule docs that aren't including the rule option count, then I apologize for missing those as they went through. I think we need to make this the convention going forward.

[eslintbot]

LGTM

[scriptdaemon]

@nzakas Now that you put it that way, I see your reasoning. I updated the PR. What do you think of these changes? I separated the text "This rule has two options, a string option:" "And an object option:" to be above their respective options. Should we keep that format, or do you have another suggestion?

Also, I'll add these to the guidelines later. Quite a few docs got through with the old style, however.

[platinumazure]

Speaking just for myself, when I get to "Or an object option:", I will probably have lost the context by then. I'd much rather see the full sentence ("This rule has one option, which may be a string object or an object option.") and then section delimiters ("String options:" or similar, and "Object option:" or similar).

[eslintbot]

LGTM

[scriptdaemon]

@platinumazure Updated with that in mind. What do you think of how it reads now?

[platinumazure]

I like it a lot more now. Hopefully @nzakas will agree.

[ilyavolodin]

LGTM, but waiting another day for others to look

[gyandeeps]

LGTM 👍
Thanks for contributing.