docs: few documentation around rules
MODIFY
website/src/_includes/docs/getting-started.md
website/src/_includes/docs/getting-started.md
@@ -24,7 +24,7 @@ rome init
This will create a `rome.rjson` that contains your project config. This will also lint, autofix, and format all the files in the directory.
-Refer to [Project Configuration](#project-config) for configuration options.
+Refer to [Project Configuration](#project-configuration) for configuration options.
> Note: The `.rjson` extension. [RJSON](#rome-json) is a superset of JSON that supports more-concise syntax and features such as comments.

MODIFY
website/src/_includes/layouts/base.liquid
website/src/_includes/layouts/base.liquid
<a href="/#cli">CLI</a>
</li>
<li>
- <a href="/#project-config">Project Configuration</a>
+ <a href="/#project-configuration">Project Configuration</a>
</li>
</ul>
</nav>

MODIFY
website/src/docs/lint/rules/index.md
website/src/docs/lint/rules/index.md
@@ -11,7 +11,7 @@ eleventyNavigation:
# Rules
-<!-- GENERATED:START(hash:86ceb4398f2bba411a252b81eeb16577ecc17b96,id:main) Everything below is automatically generated. DO NOT MODIFY. Run `./rome run scripts/generated-files/lint-rules` to update. -->
+<!-- GENERATED:START(hash:3128d0f07e8ff7734e9ebd5cae28530a68364168,id:main) Everything below is automatically generated. DO NOT MODIFY. Run `./rome run scripts/generated-files/lint-rules` to update. -->
<section class="rules">
## JavaScript
@@ -388,14 +388,14 @@ MISSING DOCUMENTATION
<a href="/docs/lint/rules/ts/noExplicitAny">noExplicitAny</a>
<a class="header-anchor" href="#noExplicitAny"></a>
</h3>
-MISSING DOCUMENTATION
+it bans the use of `any`
</div>
<div class="rule">
<h3 data-toc-exclude id="preferInterfaces">
<a href="/docs/lint/rules/ts/preferInterfaces">preferInterfaces</a>
<a class="header-anchor" href="#preferInterfaces"></a>
</h3>
-MISSING DOCUMENTATION
+it suggests the use of `interface` over `type`
</div>
</section>
<section class="rules">
@@ -406,7 +406,7 @@ MISSING DOCUMENTATION
<a href="/docs/lint/rules/jsx-a11y/altText">altText</a>
<a class="header-anchor" href="#altText"></a>
</h3>
-MISSING DOCUMENTATION
+enforce alternative text
</div>
<div class="rule">
<h3 data-toc-exclude id="anchorHasContent">
@@ -462,7 +462,7 @@ MISSING DOCUMENTATION
<a href="/docs/lint/rules/jsx-a11y/htmlHasLang">htmlHasLang</a>
<a class="header-anchor" href="#htmlHasLang"></a>
</h3>
-MISSING DOCUMENTATION
+the `lang` attribute is mandatory
</div>
<div class="rule">
<h3 data-toc-exclude id="iframeHasTitle">
@@ -483,7 +483,7 @@ MISSING DOCUMENTATION
<a href="/docs/lint/rules/jsx-a11y/lang">lang</a>
<a class="header-anchor" href="#lang"></a>
</h3>
-MISSING DOCUMENTATION
+check if `lang` attribute is valid
</div>
<div class="rule">
<h3 data-toc-exclude id="mediaHasCaption">
@@ -511,7 +511,7 @@ MISSING DOCUMENTATION
<a href="/docs/lint/rules/jsx-a11y/noAutofocus">noAutofocus</a>
<a class="header-anchor" href="#noAutofocus"></a>
</h3>
-MISSING DOCUMENTATION
+discourage the usage of `autoFocus`
</div>
<div class="rule">
<h3 data-toc-exclude id="noDistractingElements">
@@ -539,7 +539,7 @@ MISSING DOCUMENTATION
<a href="/docs/lint/rules/jsx-a11y/noOnChange">noOnChange</a>
<a class="header-anchor" href="#noOnChange"></a>
</h3>
-MISSING DOCUMENTATION
+discourage the usage of `onChange`
</div>
<div class="rule">
<h3 data-toc-exclude id="noRedundantRoles">

MODIFY
website/src/docs/lint/rules/jsx-a11y/altText.md
website/src/docs/lint/rules/jsx-a11y/altText.md
---
title: Lint Rule jsx-a11y/altText
layout: layouts/rule.liquid
-description: MISSING DOCUMENTATION
+description: enforce alternative text
eleventyNavigation:
key: lint-rules/jsx-a11y/altText
parent: lint-rules
@@ -10,7 +10,8 @@ eleventyNavigation:
# jsx-a11y/altText
-MISSING DOCUMENTATION
+Providing alternative text to images or areas help to rely on to screen
+readers to understand the purpose and the context of the image.
<!-- GENERATED:START(hash:21a7a92e0091f149a2c7459b52783be6c31a4500,id:main) Everything below is automatically generated. DO NOT MODIFY. Run `./rome run scripts/generated-files/lint-rules-docs` to update. -->
## Examples

MODIFY
website/src/docs/lint/rules/jsx-a11y/htmlHasLang.md
website/src/docs/lint/rules/jsx-a11y/htmlHasLang.md
---
title: Lint Rule jsx-a11y/htmlHasLang
layout: layouts/rule.liquid
-description: MISSING DOCUMENTATION
+description: the `lang` attribute is mandatory
eleventyNavigation:
key: lint-rules/jsx-a11y/htmlHasLang
parent: lint-rules
@@ -10,7 +10,7 @@ eleventyNavigation:
# jsx-a11y/htmlHasLang
-MISSING DOCUMENTATION
+This rule make sure that the `html` tag has the `lang` attribute.
<!-- GENERATED:START(hash:a934171412c5faba4aca8942bc9b150ec5e9fe66,id:main) Everything below is automatically generated. DO NOT MODIFY. Run `./rome run scripts/generated-files/lint-rules-docs` to update. -->
## Examples

MODIFY
website/src/docs/lint/rules/jsx-a11y/lang.md
website/src/docs/lint/rules/jsx-a11y/lang.md
---
title: Lint Rule jsx-a11y/lang
layout: layouts/rule.liquid
-description: MISSING DOCUMENTATION
+description: check if `lang` attribute is valid
eleventyNavigation:
key: lint-rules/jsx-a11y/lang
parent: lint-rules
@@ -10,7 +10,7 @@ eleventyNavigation:
# jsx-a11y/lang
-MISSING DOCUMENTATION
+This rule makes sure the value of `lang` attribute is valid.
<!-- GENERATED:START(hash:56f54d62106b444342da246772586c0e33971cdd,id:main) Everything below is automatically generated. DO NOT MODIFY. Run `./rome run scripts/generated-files/lint-rules-docs` to update. -->
## Examples

MODIFY
website/src/docs/lint/rules/jsx-a11y/noAutofocus.md
website/src/docs/lint/rules/jsx-a11y/noAutofocus.md
---
title: Lint Rule jsx-a11y/noAutofocus
layout: layouts/rule.liquid
-description: MISSING DOCUMENTATION
+description: discourage the usage of `autoFocus`
eleventyNavigation:
key: lint-rules/jsx-a11y/noAutofocus
parent: lint-rules
@@ -10,7 +10,17 @@ eleventyNavigation:
# jsx-a11y/noAutofocus
-MISSING DOCUMENTATION
+It discourages the usage to the attribute `autoFocus` on elements. This practice could cause issues for
+ sighted and non-sighted users.
+
+# Accessibility guidelines
+
+General best practice (reference resources)
+
+### Resources
+
+- [WHATWG HTML Standard, The autofocus attribute](https://html.spec.whatwg.org/multipage/interaction.html#attr-fe-autofocus)
+- [The accessibility of HTML 5 autofocus](https://www.brucelawson.co.uk/2009/the-accessibility-of-html-5-autofocus/)
<!-- GENERATED:START(hash:8275f6449bd0c79f5e6ab69880dc39c9a89e1c11,id:main) Everything below is automatically generated. DO NOT MODIFY. Run `./rome run scripts/generated-files/lint-rules-docs` to update. -->
## Examples

MODIFY
website/src/docs/lint/rules/jsx-a11y/noOnChange.md
website/src/docs/lint/rules/jsx-a11y/noOnChange.md
---
title: Lint Rule jsx-a11y/noOnChange
layout: layouts/rule.liquid
-description: MISSING DOCUMENTATION
+description: discourage the usage of `onChange`
eleventyNavigation:
key: lint-rules/jsx-a11y/noOnChange
parent: lint-rules
@@ -10,7 +10,18 @@ eleventyNavigation:
# jsx-a11y/noOnChange
-MISSING DOCUMENTATION
+It discourages the usage of the event handler `onChange` on input fields and it promotes the usage
+of `onBlur`, which is more reliable using the keyboard.
+
+
+## Accessibility guidelines
+
+- [WCAG 3.2.2](https://www.w3.org/WAI/WCAG21/Understanding/on-input)
+
+### Resources
+
+- [onChange Event Accessibility Issues](http://cita.disability.uiuc.edu/html-best-practices/auto/onchange.php)
+- [onChange Select Menu](http://www.themaninblue.com/writing/perspective/2004/10/19/)
<!-- GENERATED:START(hash:765b474011f8c5556396840f7104be4cc91bf82b,id:main) Everything below is automatically generated. DO NOT MODIFY. Run `./rome run scripts/generated-files/lint-rules-docs` to update. -->
## Examples

MODIFY
website/src/docs/lint/rules/ts/noExplicitAny.md
website/src/docs/lint/rules/ts/noExplicitAny.md
---
title: Lint Rule ts/noExplicitAny
layout: layouts/rule.liquid
-description: MISSING DOCUMENTATION
+description: it bans the use of `any`
eleventyNavigation:
key: lint-rules/ts/noExplicitAny
parent: lint-rules
@@ -10,4 +10,6 @@ eleventyNavigation:
# ts/noExplicitAny
-MISSING DOCUMENTATION
+Using the `any` type defeats the purpose of using TypeScript.
+
+When `any` is used, all compiler type checks around that value are ignored.

MODIFY
website/src/docs/lint/rules/ts/preferInterfaces.md
website/src/docs/lint/rules/ts/preferInterfaces.md
---
title: Lint Rule ts/preferInterfaces
layout: layouts/rule.liquid
-description: MISSING DOCUMENTATION
+description: it suggests the use of `interface` over `type`
eleventyNavigation:
key: lint-rules/ts/preferInterfaces
parent: lint-rules
@@ -10,4 +10,4 @@ eleventyNavigation:
# ts/preferInterfaces
-MISSING DOCUMENTATION
+It promotes the use of `interface` over `type`.

docs: few documentation around rules (#941)