From 79b975ab7185cc4fbf6a3adea45c78fac2162d77 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Sun, 30 Oct 2022 11:14:50 -0400
Subject: [PATCH] [Docs] missing descriptions in some rules

---
 .eslintrc                                | 1 +
 README.md                                | 6 +++---
 docs/rules/label-has-for.md              | 9 +++++++--
 src/rules/accessible-emoji.js            | 1 +
 src/rules/label-has-for.js               | 2 ++
 src/rules/no-aria-hidden-on-focusable.js | 5 ++---
 src/rules/prefer-tag-over-role.js        | 1 +
 7 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/.eslintrc b/.eslintrc
index a94e7cb6a..7024a688d 100644
--- a/.eslintrc
+++ b/.eslintrc
@@ -21,6 +21,7 @@
       "files": ["src/rules/*"],
       "extends": ["plugin:eslint-plugin/rules-recommended"],
       "rules": {
+        "eslint-plugin/require-meta-docs-description": ["error", { "pattern": "^(Enforce|Require|Disallow)" }],
         "eslint-plugin/require-meta-docs-url": [
           "error",
           { "pattern": "https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/tree/HEAD/docs/rules/{{name}}.md" },
diff --git a/README.md b/README.md
index d74fc210e..5c2e29a03 100644
--- a/README.md
+++ b/README.md
@@ -120,7 +120,7 @@ configuration file by mapping each custom component name to a DOM element type.
 
 | Name                                                                                                         | Description                                                                                                                        | 💼    | ❌  |
 | :----------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :---- | :-- |
-| [accessible-emoji](docs/rules/accessible-emoji.md)                                                           |                                                                                                                                    |       | ❌  |
+| [accessible-emoji](docs/rules/accessible-emoji.md)                                                           | Enforce emojis are wrapped in `<span>` and provide screenreader access.                                                            |       | ❌  |
 | [alt-text](docs/rules/alt-text.md)                                                                           | Enforce all elements that require alternative text have meaningful information to relay back to end user.                          | ☑️ 🔒 |     |
 | [anchor-ambiguous-text](docs/rules/anchor-ambiguous-text.md)                                                 | Enforce `<a>` text to not exactly match "click here", "here", "link", or "a link".                                                 |       |     |
 | [anchor-has-content](docs/rules/anchor-has-content.md)                                                       | Enforce all anchors to contain accessible content.                                                                                 | ☑️ 🔒 |     |
@@ -139,7 +139,7 @@ configuration file by mapping each custom component name to a DOM element type.
 | [img-redundant-alt](docs/rules/img-redundant-alt.md)                                                         | Enforce `<img>` alt prop does not contain the word "image", "picture", or "photo".                                                 | ☑️ 🔒 |     |
 | [interactive-supports-focus](docs/rules/interactive-supports-focus.md)                                       | Enforce that elements with interactive handlers like `onClick` must be focusable.                                                  | ☑️ 🔒 |     |
 | [label-has-associated-control](docs/rules/label-has-associated-control.md)                                   | Enforce that a `label` tag has a text label and an associated control.                                                             | ☑️ 🔒 |     |
-| [label-has-for](docs/rules/label-has-for.md)                                                                 |                                                                                                                                    |       | ❌  |
+| [label-has-for](docs/rules/label-has-for.md)                                                                 | Enforce that `<label>` elements have the `htmlFor` prop.                                                                           |       | ❌  |
 | [lang](docs/rules/lang.md)                                                                                   | Enforce lang attribute has a valid value.                                                                                          |       |     |
 | [media-has-caption](docs/rules/media-has-caption.md)                                                         | Enforces that `<audio>` and `<video>` elements must have a `<track>` for captions.                                                 | ☑️ 🔒 |     |
 | [mouse-events-have-key-events](docs/rules/mouse-events-have-key-events.md)                                   | Enforce that `onMouseOver`/`onMouseOut` are accompanied by `onFocus`/`onBlur` for keyboard-only users.                             | ☑️ 🔒 |     |
@@ -153,7 +153,7 @@ configuration file by mapping each custom component name to a DOM element type.
 | [no-onchange](docs/rules/no-onchange.md)                                                                     | Enforce usage of `onBlur` over `onChange` on select menus for accessibility.                                                       |       | ❌  |
 | [no-redundant-roles](docs/rules/no-redundant-roles.md)                                                       | Enforce explicit role property is not the same as implicit/default role property on element.                                       | ☑️ 🔒 |     |
 | [no-static-element-interactions](docs/rules/no-static-element-interactions.md)                               | Enforce that non-interactive, visible elements (such as `<div>`) that have click handlers use the role attribute.                  | ☑️ 🔒 |     |
-| [prefer-tag-over-role](docs/rules/prefer-tag-over-role.md)                                                   |                                                                                                                                    |       |     |
+| [prefer-tag-over-role](docs/rules/prefer-tag-over-role.md)                                                   | Enforces using semantic DOM elements over the ARIA `role` property.                                                                |       |     |
 | [role-has-required-aria-props](docs/rules/role-has-required-aria-props.md)                                   | Enforce that elements with ARIA roles must have all required attributes for that role.                                             | ☑️ 🔒 |     |
 | [role-supports-aria-props](docs/rules/role-supports-aria-props.md)                                           | Enforce that elements with explicit or implicit roles defined contain only `aria-*` properties supported by that `role`.           | ☑️ 🔒 |     |
 | [scope](docs/rules/scope.md)                                                                                 | Enforce `scope` prop is only used on `<th>` elements.                                                                              | ☑️ 🔒 |     |
diff --git a/docs/rules/label-has-for.md b/docs/rules/label-has-for.md
index 34d7d91d1..1f319ac98 100644
--- a/docs/rules/label-has-for.md
+++ b/docs/rules/label-has-for.md
@@ -1,12 +1,12 @@
 # jsx-a11y/label-has-for
 
-❌ This rule is deprecated.
+❌ This rule is deprecated. It was replaced by [`label-has-associated-control`](label-has-associated-control.md).
 
 💼 This rule is _disabled_ in the following configs: ☑️ `recommended`, 🔒 `strict`.
 
 <!-- end auto-generated rule header -->
 
-*This rule was deprecated in v6.1.0. It will no longer be maintained. Please use [`label-has-associated-control`](label-has-associated-control.md) instead.*
+_This rule was deprecated in v6.1.0. It will no longer be maintained._
 
 Enforce label tags have associated control.
 
@@ -81,6 +81,7 @@ However, if `allowChildren` is set to `true`, no error will be raised. If you wa
 Note that passing props as spread attribute without `htmlFor` explicitly defined will cause this rule to fail. Explicitly pass down `htmlFor` prop for rule to pass. The prop must have an actual value to pass. Use `Label` component above as a reference. **It is a good thing to explicitly pass props that you expect to be passed for self-documentation.** For example:
 
 #### Bad
+
 ```jsx
 function Foo(props) {
   return <label {...props} />
@@ -88,6 +89,7 @@ function Foo(props) {
 ```
 
 #### Good
+
 ```jsx
 function Foo({ htmlFor, ...props}) {
     return <label htmlFor={htmlFor} {...props} />
@@ -106,6 +108,7 @@ function Foo(props) {
 ```
 
 ### Succeed
+
 ```jsx
 <label htmlFor="firstName">
   <input type="text" id="firstName" />
@@ -114,12 +117,14 @@ function Foo(props) {
 ```
 
 ### Fail
+
 ```jsx
 <input type="text" id="firstName" />
 <label>First Name</label>
 ```
 
 ## Accessibility guidelines
+
 - [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
 - [WCAG 3.3.2](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions)
 - [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
diff --git a/src/rules/accessible-emoji.js b/src/rules/accessible-emoji.js
index 788dabbf8..53eb89993 100644
--- a/src/rules/accessible-emoji.js
+++ b/src/rules/accessible-emoji.js
@@ -20,6 +20,7 @@ const schema = generateObjSchema();
 export default {
   meta: {
     docs: {
+      description: 'Enforce emojis are wrapped in `<span>` and provide screenreader access.',
       url: 'https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/tree/HEAD/docs/rules/accessible-emoji.md',
     },
     deprecated: true,
diff --git a/src/rules/label-has-for.js b/src/rules/label-has-for.js
index e231709dd..dd7ff0627 100644
--- a/src/rules/label-has-for.js
+++ b/src/rules/label-has-for.js
@@ -88,7 +88,9 @@ const getValidityStatus = (node, required, allowChildren, elementType) => {
 export default {
   meta: {
     deprecated: true,
+    replacedBy: ['label-has-associated-control'],
     docs: {
+      description: 'Enforce that `<label>` elements have the `htmlFor` prop.',
       url: 'https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/tree/HEAD/docs/rules/label-has-for.md',
     },
     schema: [schema],
diff --git a/src/rules/no-aria-hidden-on-focusable.js b/src/rules/no-aria-hidden-on-focusable.js
index 7c8129ec2..4f40c81b8 100644
--- a/src/rules/no-aria-hidden-on-focusable.js
+++ b/src/rules/no-aria-hidden-on-focusable.js
@@ -12,14 +12,13 @@ import getElementType from '../util/getElementType';
 import isFocusable from '../util/isFocusable';
 import { generateObjSchema } from '../util/schemas';
 
-const errorMessage = 'aria-hidden="true" must not be set on focusable elements.';
 const schema = generateObjSchema();
 
 export default {
   meta: {
     docs: {
       url: 'https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/tree/HEAD/docs/rules/no-aria-hidden-on-focusable.md',
-      description: errorMessage,
+      description: 'Disallow `aria-hidden="true"` from being set on focusable elements.',
     },
     schema: [schema],
   },
@@ -35,7 +34,7 @@ export default {
         if (isAriaHidden && isFocusable(type, attributes)) {
           context.report({
             node,
-            message: errorMessage,
+            message: 'aria-hidden="true" must not be set on focusable elements.',
           });
         }
       },
diff --git a/src/rules/prefer-tag-over-role.js b/src/rules/prefer-tag-over-role.js
index 0f6d00b3c..fbb9bea04 100644
--- a/src/rules/prefer-tag-over-role.js
+++ b/src/rules/prefer-tag-over-role.js
@@ -35,6 +35,7 @@ const getLastPropValue = (rawProp) => {
 export default {
   meta: {
     docs: {
+      description: 'Enforces using semantic DOM elements over the ARIA `role` property.',
       url: 'https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/tree/HEAD/docs/rules/prefer-tag-over-role.md',
     },
     schema: [schema],