🤖 Merge PR #68619 eslint: tweak documentation for rule meta propertie…

…s by @bmish

types/eslint/index.d.ts

@@ -696,17 +696,15 @@ export namespace Rule {
     }
 
     interface RuleMetaData {
+        /** Properties often used for documentation generation and tooling. */
         docs?: {
-            /** Provides a short description of the rule. */
+            /** Provides a short description of the rule. Commonly used when generating lists of rules. */
             description?: string | undefined;
-            /**
-             * TODO: remove this field in next major release of @types/eslint.
-             * @deprecated no longer used
-             */
+            /** Historically used by some plugins that divide rules into categories in their documentation. */
             category?: string | undefined;
-            /** Whether the rule is enabled in the plugin's `recommended` configuration. */
+            /** Historically used by some plugins to indicate a rule belongs in their `recommended` configuration. */
             recommended?: boolean | undefined;
-            /** Specifies the URL at which the full documentation can be accessed (enabling code editors to provide a helpful link on highlighted rule violations). */
+            /** Specifies the URL at which the full documentation can be accessed. Code editors often use this to provide a helpful link on highlighted rule violations. */
             url?: string | undefined;
             /**
              * TODO: remove this field in next major release of @types/eslint.
@@ -724,7 +722,7 @@ export namespace Rule {
         /**
          * Specifies the [options](https://eslint.org/docs/latest/developer-guide/working-with-rules#options-schemas)
          * so ESLint can prevent invalid [rule configurations](https://eslint.org/docs/latest/user-guide/configuring/rules#configuring-rules).
-         * TODO: schema is potentially planned to be no longer be optional in v9 (https://github.com/eslint/rfcs/blob/main/designs/2021-schema-object-rules/README.md)
+         * Mandatory for rules with options.
          */
         schema?: JSONSchema4 | JSONSchema4[] | undefined;