eslint: improve documentation for rule meta properties

[bmish]

• 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 npm test <package to test>.

What's included

• Marks a few properties as deprecated and to be removed in the next major release of @types/eslint:
  • meta.docs.category - see docs: remove unused meta.docs.category field in working-with-rules page eslint/eslint#16109, Unnecessary category field in template for plugin-based rules eslint/generator-eslint#131
  • meta.docs.suggestion - see Breaking: Require meta.hasSuggestions for rules with suggestions eslint/eslint#14573
• Ensures documentation for each property is included and up-to-date with wording on ESLint's Working with Rules page
• Generalize wording to refer to any plugin rules and not just ESLint core rules (ESLint plugins use these types but ESLint core rules don't)
• Tweaks grammar and consistency

[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: @JounQin

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": 61803,
  "author": "bmish",
  "headCommitOid": "4dd7317d3505a981a4d58655a204c72a9d1bd89e",
  "mergeBaseOid": "9205f7999a9a2ec11cecee84b9af881f834a9bd8",
  "lastPushDate": "2022-08-18T21:06:20.000Z",
  "lastActivityDate": "2022-08-19T02:14:35.000Z",
  "mergeOfferDate": "2022-08-18T23:20:16.000Z",
  "mergeRequestDate": "2022-08-19T02:14:35.000Z",
  "mergeRequestUser": "JounQin",
  "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": "jakebailey",
      "date": "2022-08-18T23:19:33.000Z",
      "isMaintainer": true
    },
    {
      "type": "approved",
      "reviewer": "JounQin",
      "date": "2022-08-18T23:08:51.000Z",
      "isMaintainer": false
    }
  ],
  "mainBotCommentID": 1219951159,
  "ciResult": "pass"
}

[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.

[JounQin]

Can deprecation be tested?

I'm serious, see also https://sonarsource.github.io/rspec/#/rspec/S1874/javascript and it's source at https://github.com/SonarSource/SonarJS/blob/master/eslint-bridge/src/linting/eslint/rules/deprecation.ts.

[bmish]

Can desperation be tested?

I'm serious, see also https://sonarsource.github.io/rspec/#/rspec/S1874/javascript and it's source at https://github.com/SonarSource/SonarJS/blob/master/eslint-bridge/src/linting/eslint/rules/deprecation.ts.

@JounQin I'm assuming you mean "deprecation". In the context of my PR, what do you mean by testing deprecation? These deprecated properties are referenced in the DefinitelyTyped eslint test file to ensure they can continue to be used.

[JounQin]

@bmish sorry for my typo. 😅

Yes, I mean can that be tested in favor of function overloads. (Not specific on this PR)

[bmish]

I'm still not sure what you mean by "tested in favor of function overloads".

[JounQin]

I'm still not sure what you mean by "tested in favor of function overloads".

Function A can have different signatures, only a few of them maybe deprecated, I want to have test cases to make sure TS understand which overload usages should be considered as deprecation, which should be used without deprecation notice.

For example, // @ts-expect-deprecation and // @ts-expect-no-deprecation

[bmish]

@JounQin I was hoping something like that existed but haven't found anything.

[JounQin]

@JounQin I was hoping something like that existed but haven't found anything.

Yeah, so I'm just asking, and I'd like to raise an issue on https://github.com/microsoft/TypeScript.

[JounQin]

Ready to merge