Standardize Rule Documentation

[bpmutter]

ESLint version

v8.x

What problem do you want to solve?

there is currently a lot of variability in how rules are documented. rules pages structures and content varies significantly. this makes harder for an end user to navigate the docs, and harder for rule makers to know how to document rules.

What do you think is the correct solution?

• Create a standardized way to document a rule.
• Apply the standardized way to X most important rules (exact number to be determined).
• Given the very large number of rules, add guidance to contributor documentation that documenting a rule using the template is a great place to start contributing to ESLint.
• Investigate using an 11ty template for the rule documentation.

Participation

• I am willing to submit a pull request for this change.

Additional comments

No response

[bpmutter]

Notes

High Level Thoughts

1. brief overview
2. api reference
3. examples
4. additional information

note this is heavily influenced by the reference documentation for the MongoDB aggregation operators (such as this page for $sort). i think the aggregation operator pages do a good job with presenting reference docs with examples for complex configurations. given that the rules documentation is reference docs with example for complex configurations, the model applies here.

Page-Level Outines

every rule page should have:

• high level overview (no heading)
  • ~1 sentence
  • i still need to better understand the template, but this comed from source code
  • add the call out w info about if rule is recommended. also generated from source code or metadata
• Rule Details (heading)
  • free-form explanation of rule
• Options (heading)
  • optional. only include if rules has options
  • Argument Names (subheadings)
    • For each argument name include list with following:
      • Required: Yes/No
      • Type: Data type and any further description necessary.
      • Default Value: Optional. Default value and description if applicable.
• Examples (heading)
  • include the incorrect and correct examples as exists now
  • can include subheadings
    • for example, right now a lot of the rules have examples with the options. now they'd be shifted to this example section.
  • put all examples in here
• Additional Information (heading)
  • optional
  • contain subheadings like the following:
    • Known Limitations
    • When Not to Use
• Related Rules (heading)
  • chips with the related rules
  • same as now, generated from metadata
• Resources (heading)
  • same as now
• in the last line of the file, put the version introduced in italics (no heading)

Implementation Plan Options

A couple of proposals.

Option 1: More Structured Data in Frontmatter

One potential way would be to use as much structured data as possible, including stuff in the frontmatter and injecting in the template.

could add following fields:

# added to doc in `## Rule Details`
rule_details: |>
  detailed description of rule in markdown.
# added to doc in `## Options`
options: 
  option_1:
    type: Markdown. specify String, bool, etc and any other important related info
    description: Markdown description of option
   required: true/false
   default_value: Markdown. specify important related info

update rules template to render content based on this structured data. to support incremental adoption of this, adding these frontmatter fields would.

then the only free-form text would be the examples section and any additional info that writer wants to add.

[bpmutter]

continuing the above comment as a discussion - #16643

[nzakas]

A quick question on this: for the options section, are you envisioning that all options are explained there without examples, and then we follow up with specific examples in the Examples section?

[bpmutter]

A quick question on this: for the options section, are you envisioning that all options are explained there without examples, and then we follow up with specific examples in the Examples section?

correct. put the reference first, then expand in the examples section