Docs: WIP Guidelines for rule pages

[pedrottimark]

This issue will accumulate the reusable patterns that emerge while the rules pages are edited to improve consistency. The result will become a template and guidelines (in a format yet to be determined) for future editing, especially new options and rules.

Goals: eslint/archive-website#186 (comment), eslint/archive-website#186 (comment), #5375 (comment)

Pull requests will have often discussion about specific occurrences which sometimes cause us to add generalized conclusions to this issue. This issue can also have questions, concerns, suggestions.

[pedrottimark]

Here are the level-2 headings in rules pages in the order that they are used, if needed:

Rule Details
Options
Environments
Known Limitations
When Not To Use It
Compatibility
Further Reading
Related Rules

EDIT 2016-06-17:

The gensite command adds Version and Resources to the end of the markdown files from eslint/docs/rules when they move to eslint.github.io/docs/rules

The introduction is the content between the main level-1 heading and Rule Details.

The gensite command will prepend Jekyll front matter from rule meta data: description, recommended, fixable to the markdown files. The rule layout in eslint.github.io will insert the content to the introduction via Liquid templates. We will delete the repeated content from the rule docs files.

[pedrottimark]

If a rule page has a level-2 Options heading, then for each option which has examples there is a level-3 heading.

The heading text is either:

• string value (for example, always, never)
• object key (for example, after, before, hoist)

For faster scanning, there is no additional punctuation (quotes) or formatting (code style indicated by backticks). The example sentences and eslint comments in the code specify the required syntax.

If there are separate examples for values of an object property, then there are level-4 headings. A colon separates key from value, for example:
hoist: functions
hoist: all
hoist: never

EDIT 2016-06-17:

We need a heading pattern for boolean properties which have incorrect/correct code for both true and false values (for example, after and before in the keyword-spacing rule).

[pedrottimark]

Most rules (and options) have examples of code so people can achieve the following goals:

• Given incorrect or inconsistent code, find a rule (and its options) to prevent it.
• Given a rule (and its options) in the configuration, write correct code.

So people can recognize quickly how rules and options relate to their code, most examples consist of incorrect code followed by correct code.

Examples of some options (for example, allow, exceptions, ignore) omit incorrect code because it is the same as or related to the incorrect code in a preceding example. The word additional makes this explicit: Examples of additional correct code …

Examples of a few options (for example, builtInGlobals or { "hoist": "all" } in no-shadow) can omit correct code because they are “reverse exceptions” which add to the what is incorrect by default for the rule. The word additional makes this explicit: Examples of additional incorrect code …

Adapt the following patterns for sentences to precede the code fence for an example.
Updated on 2016-04-10

• under Rule Details for a rule with no options
  Examples of incorrect code for this rule:
  Examples of correct code for this rule:
• under the level-3 heading for the default vanilla option
  Examples of incorrect code for this rule with the default "vanilla" option:
  Examples of correct code for this rule with the default "vanilla" option:
• under the level-3 heading for the chocolate option
  Examples of incorrect code for this rule with the "chocolate" option:
  Examples of correct code for this rule with the "chocolate" option:
• under the level-3 heading for options which are object literal keys
  in sentence and eslint comment in code use object-curly-spacing always and quote-props always
  however, the rule name itself is unquoted in the eslint comment
  after
  Examples of incorrect code for this rule with the default { "before": false, "after": true } options:
  Examples of correct code for this rule with the default { "before": false, "after": true } options:
  before
  Examples of incorrect code for this rule with the { "before": true, "after": false } options:
  Examples of correct code for this rule with the { "before": true, "after": false } options:
• only correct code for an option which is an exception for another option
  Examples of additional correct code for this rule with the "never", { "ignoreForLoopInit": true } options:
• only incorrect code for an option which is a “reverse exceptions” for another option
  Examples of additional incorrect code for this rule with the { "builtinGlobals": true } option:
• sentence includes significant conditions
  but use comments in code for more minor distinctions
  Examples of correct code for this rule with es6 environment:
  Examples of correct code for this rule with es6 environment and strict mode:
  Examples of correct code this rule with null elements for the default { "before": false, "after": true } option:
  Examples of incorrect code for this rule, unlike the corresponding rule in JSHint:
  Examples of correct code for this rule, because of JavaScript function and variable hoisting:
• option has an arbitrary value as a primitive type
  Examples of incorrect code for this rule with a maximum of 2:
• option has an arbitrary value as a array or object
  Examples of incorrect code for this rule with a sample of identifier names:
  Examples of correct code for this rule with a sample of identifier names:
  Examples of incorrect code for this rule with a sample of "preferType" options:
  Examples of correct code for this rule with a sample of "preferType" options:
  Examples of correct code for this rule with a sample { "allowPattern": "^[a-z]+(_[a-z]+)+$" } option:
  Examples of correct code for this rule with a sample { "exceptions": ["Object"] } option:
  Examples of correct code for this rule with a sample { "allow": ["!!", "~"] } option:
• under Known Limitations in callback-return the code has information gray background-color
  Example of a false negative when this rule reports correct code:
  Example of a false positive when this rule reports incorrect code:

EDIT 2016-06-17:

Suggesting bold (instead of italic) format for false negative or false positive.

The rule layout has replacement rules in a Liquid template to add the incorrect or correct class to the p element for several initial phrases of example sentences.

The matching phrases now include Example singular in addition to Examples plural. If there is just one example of additional code, plural just reads wrong. In ordinary examples, plural seems to read okay even if there is only one example.

Consistent structure of headings, order of incorrect/correct example, and wording of example paragraph (so the class is added) might allow side-by-side format for examples on wide screens.

[pedrottimark]

If a rule has options, then heading level 2 Options follows the Rule Details section.

Look at the schema or meta.schema array in module.exports in the rule file: lib/rules/*.js

For each “slot” in the array, include a sentence like one of the following to introduce a bulleted list. The brackets contain example rules for your further study. Do not include them, of course.

• This rule has a string option:
• This rule has a number or string option: [indent]
• This rule has an object option: [camelcase]
• This rule has either a string option: [one-var, padded-blocks, space-before-function-paren]
• Or an object option: [one-var, padded-blocks, space-before-function-paren]
• This rule has either an object option: [generator-star-spacing]
• Or a string option: [generator-star-spacing]
• This rule has string options: [consistent-this]
• This rule has another string option: [quotes]
• This rule has an object option for exceptions: [operator-linebreak]
• This rule has an object option for an exception: [brace-style]
• This rule has an object option for exceptions to the "always" option: [object-curly-spacing]
• This rule has an object option for exceptions to the "never" option: [object-curly-spacing, yoda]
• This rule has an object option for an exception to the "declarations" option: [func-style]

Here are recommended VERBS to use in list items. Try to limit each item to one sentence which begins with the option in code style (enclosed in backticks) and does not end with a period

• … disallows …
• … requires …
• … allows … [yoda]
• … allows (but does not require) … [comma-dangle]

list item for string option

• "option" (default) VERB …
• "option" VERB …

list item for string options

• designated alias names for this (default "that") [consistent-this]

list item for number option

• a positive integer (default 4) enforces … [indent]

list item for object option

• "SwitchCase" has an integer value (default 0) to enforce … [indent]
• "exceptRange": true (default false) allows … [yoda]
• "before": true (default) enforces … [generator-star-spacing]
• "after": false (default) disallows … [generator-star-spacing]
• "exceptions" has an array of strings … [spaced-comment]
• "exceptions" has properties whose names correspond to node types in the abstract syntax tree (AST) of JavaScript code: [comma-style]

useful phrases in list items

• except when [eqeqeq]

Here is a question we will answer as we go: how much description to repeat following a heading level 3 for an option preceding its example code? Initial opinion by Mark is usually none.

EDIT 2016-06-17:

If the effect of a boolean option is not an obvious on/off (analogous to a check box on a form) but two different things which need separate descriptions (analogous to two option buttons on a form) then use nested bullets. Here is an example from the valid-jsdoc rule:

• "requireReturn" requires a return tag:
  • true (default) even if the function or method does not have a return statement (this option value does not apply to constructors)
  • false if and only if the function or method has a return statement (this option value does apply to constructors)

[scriptdaemon]

To remain consistent with the discussions for the process of deprecating rules (and simply for sanity's sake), docs for maintained rules (i.e. non-deprecated rules) should not list any deprecated rules in their "Related Rules" sections.

[scriptdaemon]

Where options have been deprecated, examples should no longer reference the deprecated option, nor should the option be listed among the available options. However, a note with the following format should be placed at the bottom of its respective option summary:

Deprecated: The object property maximum is deprecated; please use the object property max instead.

[pedrottimark]

• no-empty-character-class: delete Related Rules no-empty-class
• space-before-function-paren: delete Related Rules space-after-keywords space-return-throw-case
• object-curly-spacing: under Related Rules delete space-in-brackets
• under Removed space-in-brackets add computed-property-spacing to replaced by
• spaced-comment: delete Related Rules spaced-line-comment

[pedrottimark]

The strict rule has a rare example of a removed option (the original default, lack of any option ;)

If we find any more, we can compare them and decide on a pattern.

[originalfoo]

FYI: I've started work on ES6 rules.

For removed, deprecated, changed options, we could use blockquotes to highlight the changes, eg:

From ESLint 1.2.3 the "whatever" option is deprecated/removed/etc.....

[originalfoo]

@pedrottimark do you have an example doc showing the full headings, in particular the following h2 headings:

• Environments
• Known Limitations
• Compatibility

Also, IMO it would be better to rename the "When Not To Use It" heading to "Recommendations" so we can also give guidance on when to use it if desired. For example, the arrow-body-style rule I might say:

Recommendations

• If you use arrow functions, use this rule.
• For concise and expressive code, use the "as-needed" pattern
• For consistent code. use the "never" pattern

We could potentially have a list of keywords associated with the meta goals of linting, and then in the recommendations section suggest options to use for different goals. Off the top of my head, I can think of the following meta reasons:

• maintainability - to facilitate best practice
• consistency - to reduce learning curves
• expressiveness - to aid reasoning
• brevity - to ensure concise code
• stylistic - a mixture of the above + personal preference

There are likely others. The meta terms could also be used when evaluating new rules or changes to existing rules, and as an aid to decision making could be mentioned in the contributing guidelines.

[originalfoo]

Mockup of a rule page with revised headings, options, etc...

https://github.com/aubergine10/scrapbook/wiki

[pedrottimark]

Here are 11 examples of rules whose docs contain h2 headings you asked about.

I put * at the left of 2 with unexpected order and r at the left of 1 with unexpected capitalization

  Rule Details, Compatibility, Further Reading no-octal
* Rule Details, Environments, Options, Further Reading no-invalid-regexp
  Rule Details, Known Limitations, When Not To Use It, Further Reading, Related Rules no-regex-spaces
  Rule Details, Options, Compatibility, Further Reading one-var
  Rule Details, Options, Compatibility, When Not To Use It, Related Rules object-curly-newline
  Rule Details, Options, Environments, When Not To Use It, Compatibility, Further Reading no-undef
* Rule Details, Options, Further Reading, Compatibility: func-names
  Rule Details, Options, Known Limitations, When Not To Use It, Further Reading, Related Rules callback-return
  Rule Details, Options, When Not To Use It, Compatibility, Related Rules object-property-newline
r Rule Details, Options, When Not To Use It, Further reading, Related Rules, Compatibility max-lines
  Rule Details, When Not To Use It, Compatibility, Further Reading no-floating-decimal

[originalfoo]

With regards to this scenario:

under Rule Details for a rule with no options

• Examples of incorrect code for this rule:
• Examples of correct code for this rule:

I think we should also match those strings if used under a level-2 Examples heading - IMO the code samples should always live under Examples heading, even if the rule has no options - this keeps document structure consistent.

[originalfoo]

Key notes from es6 rule docs initial sweep:

• Struggling with one branch per PR approach - can't figure out how to prevent PRs from merging.
• Issues with code example blocks (not covered by initial sweep):
  • ensure each starts with the inline options comment
  • ensure blank line between comment and code example
  • ensure 'correct' vs. 'incorrect' examples clearly convey difference - Docs: no-duplicate-imports - confusing option description and examples #6455 (comment)
  • some examples are too terse for newbies to comprehend - Docs: no-duplicate-imports - confusing option description and examples #6455
  • colorization and iconification of examples is limited to at most 3 code blocks per heading (or colour?)
    • could maybe merge and add extra comments, see Docs: Consistent example headings & text (refs #5446) #6453 (comment) for example
    • alternatively eradicate the restriction (as it would likely cause issues further down the line if we start hosting docs for 3rd party rule plugins)
• Still a lot of inconsistency with opening sections
  • Many docs don't explain the rationale behind the rule
  • Options sections still need lots of cleanup - IMO more discussion needed on the format of the options section as I feel it's still too cumbersome in many scenarios
• Inconsistency of h2 Examples heading, particularly for rules with no options
  • I'd like to ensure every doc includes that heading, even if no options
• With es6 rules, the h2 When Not To Use This Rule section should always include "If using ES3/5"
  • I'd like to discuss renaming that heading to "Recommendations"
    • Would allow us to say when the rule should be used, in addition to when it should not be used
    • Also allow suggesting which options to use for various project goals

Overall, I'm chomping at the bit to get cracking with more updates to the docs. Real blocker issues from my end are:

• Auto-merging PRs - how to prevent it and ensure separate PR per branch?
  • This could become critical for some of the larger updates planned where a PR might be limited to a specific file with lots of changes that need to be carefully examined
  • If I have to wait for current PR to be merged before submitting next PR, it's going to add lots of latency to workflow
• Scope-creep during the PR review phase; eats up time
  • Better commit comments, stating clearly what is in and out of scope for the PR could help?

[originalfoo]

Another thing to consider - would it be worth having an optional h2.FAQ section on rule docs?

For example, with some es6 stuff, people can get AssertionError: A fatal parsing error occurred: Parsing error: Assigning to rvalue - to fix they have to add parserOptions: { ecmaVersion: 6 } to their tests (example). An FAQ section could cover such externalities.

[originalfoo]

Currently updating some docs outside es6 category, list will probably grow as I find more (task focus: correct headings and captions in examples section):

• http://eslint.org/docs/rules/padded-blocks
• http://eslint.org/docs/rules/space-before-blocks
• http://eslint.org/docs/rules/wrap-regex
• http://eslint.org/docs/rules/spaced-comment - PR for this one will need extra scrutiny
• http://eslint.org/docs/rules/space-unary-ops
• http://eslint.org/docs/rules/space-infix-ops
• http://eslint.org/docs/rules/space-in-parens
• http://eslint.org/docs/rules/space-before-function-paren - unclear if this rule affects arrow functions
• http://eslint.org/docs/rules/sort-vars
• http://eslint.org/docs/rules/semi-spacing
• http://eslint.org/docs/rules/semi
• http://eslint.org/docs/rules/require-jsdoc
• http://eslint.org/docs/rules/quotes - major reordering of examples, will need careful review in PR
• http://eslint.org/docs/rules/quote-props

Looks like most of the Stylistic section will need the correct style applying (irony much? lol) but I'll start with those listed above for now.

[originalfoo]

Noticed a fairly common anti-pattern - options section being spread throughout the examples. space-in-parens rule is a good example:

• Options section describes never and always
• Then mid way through lots of examples, the exceptions option is introduced
• Then near the bottom the empty exception is introduced.

A quick glance of the Options section could leave a reader thinking there were only always and never options, that the rule didn't meet their specific needs.

I've moved all the options information in to a single h2 Options section and used headings throughout examples to highlight where each option is being discussed.

[kaicataldo]

Closing because it doesn't look like there's enough interest to finish implementing this.