Docs: Add rationale to rules #5265
Comments
|
Strong agree! We can treat this as a spin-off / subset of #4861, in that this is a big part of why a lot of rule docs are unclear. It'd be great to have testing set up to make sure each rule has a Rule Details section and at least one sentence explaining the rule. Right now that's in Jest tests but will likely eventually be linting. #4366. |
|
Following up on this old issue, we've had a lot of docs overhauls land:
At this point, roughly all rules have a 1-2 paragraph rationale as their opening descriptions. So I think we can close this general issue out as resolved. But! Docs are never done, and it's a certainty some rules don't have informative rationales. Request to anybody reading this: if you see a rule whose docs are lacking, please file a new issue. That'd be lovely. ❤️ |
Before You File a Documentation Request Please Confirm You Have Done The Following...
Suggested Changes
Would be great if the rules consistently explained why something is a rule.
See e.g.
shellcheckrules, which always include a "Rationale" section:For
typescript-eslint, the rationales are either unclear (mixed in the what section) or missing (e.g. https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/docs/rules/restrict-template-expressions.md).A rationale would help developers improve their understanding as they stumble upon violations, and would help rule writers clarify their reasoning.
Affected URL(s)
Some examples:
The text was updated successfully, but these errors were encountered: