eslint: tweak documentation for rule meta properties

[bmish]

Please fill in this template.

• Use a meaningful title for the pull request. Include the name of the package modified.
• Test the change in your own code. (Compile and run.)
• Add or edit tests to reflect the change.
• Follow the advice from the readme.
• Avoid common mistakes.
• Run pnpm test <package to test>.

If changing an existing definition:

• Provide a URL to documentation or source code which provides context for the suggested changes: <>
• If this PR brings the type definitions up to date with a new version of the JS library, update the version number in the package.json.

Tweak documentation based on real-world usage of these ESLint rule properties. Especially, this clarifies how properties are commonly used.

Similar change I made in the ESLint repository:

• docs: tweak explanation for meta.docs rule properties eslint/eslint#18057

Follow-up to a previous change I made to tweak this documentation:

• eslint: improve documentation for rule meta properties #61803

Relevant RFC about schemas becoming mandatory in the soon-to-be-released ESLint v9:

• https://github.com/eslint/rfcs/blob/main/designs/2021-schema-object-rules/README.md
• feat!: Require schemas and object-style rules eslint/rfcs#85

[typescript-bot]

@bmish Thank you for submitting this PR!

This is a live comment which I will keep updated.

1 package in this PR

• eslint — on npm, on unpkg
  • owner-approval: @bradzacher

Code Reviews

Because this is a widely-used package, a DT maintainer will need to review it before it can be merged.

You can test the changes of this PR in the Playground.

Status

• ✅ No merge conflicts
• ✅ Continuous integration tests have passed
• ✅ Only a DT maintainer can approve changes without tests

All of the items on the list are green. To merge, you need to post a comment including the string "Ready to merge" to bring in your changes.

---

Diagnostic Information: What the bot saw about this PR

{
  "type": "info",
  "now": "-",
  "pr_number": 68619,
  "author": "bmish",
  "headCommitOid": "d6f2f05a91a2fadac58613a21b9e1e9e830ea772",
  "mergeBaseOid": "8beea70823af10e72a62883b0a525ebe4587c755",
  "lastPushDate": "2024-02-13T21:35:07.000Z",
  "lastActivityDate": "2024-02-22T22:08:11.000Z",
  "mergeOfferDate": "2024-02-22T22:05:19.000Z",
  "mergeRequestDate": "2024-02-22T22:08:11.000Z",
  "mergeRequestUser": "bmish",
  "hasMergeConflict": false,
  "isFirstContribution": false,
  "tooManyFiles": false,
  "hugeChange": false,
  "popularityLevel": "Critical",
  "pkgInfo": [
    {
      "name": "eslint",
      "kind": "edit",
      "files": [
        {
          "path": "types/eslint/index.d.ts",
          "kind": "definition"
        }
      ],
      "owners": [
        "pmdartus",
        "j-f1",
        "saadq",
        "JasonHK",
        "bradzacher",
        "JounQin"
      ],
      "addedOwners": [],
      "deletedOwners": [],
      "popularityLevel": "Critical"
    }
  ],
  "reviews": [
    {
      "type": "approved",
      "reviewer": "rbuckton",
      "date": "2024-02-22T22:04:39.000Z",
      "isMaintainer": true
    },
    {
      "type": "approved",
      "reviewer": "bradzacher",
      "date": "2024-02-13T21:41:46.000Z",
      "isMaintainer": false
    }
  ],
  "mainBotCommentID": 1942646984,
  "ciResult": "pass"
}

[typescript-bot]

Hey @bmish,

😒 Your PR doesn't modify any tests, so it's hard to know what's being fixed, and your changes might regress in the future. Please consider adding tests to cover the change you're making. Including tests allows this PR to be merged by yourself and the owners of this module.

This can potentially save days of time for you!

[typescript-bot]

🔔 @pmdartus @j-f1 @saadq @JasonHK @bradzacher @JounQin — please review this PR in the next few days. Be sure to explicitly select Approve or Request Changes in the GitHub UI so I know what's going on.

[typescript-bot]

⏳ Hi @bmish,

It's been a few days since this PR was approved by bradzacher and we're waiting for a DT maintainer to give a review.

If you would like to short-circuit this wait, you can edit some of the test files in the package which verify how the .d.ts files work. This would allow the PR to be merged by you or the DT module owners after a re-review.

[typescript-bot]

@bmish: Everything looks good here. I am ready to merge this PR (at d6f2f05) on your behalf whenever you think it's ready.

If you'd like that to happen, please post a comment saying:

Ready to merge

and I'll merge this PR almost instantly. Thanks for helping out! ❤️

(@pmdartus, @j-f1, @saadq, @JasonHK, @bradzacher, @JounQin: you can do this too.)

[bmish]

Ready to merge