chore: clean up extra * in TSDoc comments (#13336)

Author: mrazauskas

.eslintrc.cjs

@@ -333,7 +333,7 @@ module.exports = {
   parserOptions: {
     sourceType: 'module',
   },
-  plugins: ['import'],
+  plugins: ['import', 'jsdoc'],
   rules: {
     'accessor-pairs': ['warn', {setWithoutGet: true}],
     'block-scoped-var': 'off',
@@ -390,6 +390,7 @@ module.exports = {
       },
     ],
     'init-declarations': 'off',
+    'jsdoc/check-alignment': 'error',
     'lines-around-comment': 'off',
     'max-depth': 'off',
     'max-nested-callbacks': 'off',

package.json

@@ -38,6 +38,7 @@
     "eslint-plugin-eslint-comments": "^3.1.2",
     "eslint-plugin-import": "^2.6.0",
     "eslint-plugin-jest": "^26.1.0",
+    "eslint-plugin-jsdoc": "^39.3.6",
     "eslint-plugin-local": "^1.0.0",
     "eslint-plugin-markdown": "^3.0.0",
     "eslint-plugin-prettier": "^4.0.0",

packages/jest-environment/src/index.ts

@@ -184,27 +184,27 @@ export interface Jest {
     options?: {virtual?: boolean},
   ): Jest;
   /**
-    * Returns the actual module instead of a mock, bypassing all checks on
-    * whether the module should receive a mock implementation or not.
-    *
-    * @example
-    ```js
-     jest.mock('../myModule', () => {
-     // Require the original module to not be mocked...
-     const originalModule = jest.requireActual('../myModule');
-
-       return {
-         __esModule: true, // Use it when dealing with esModules
-         ...originalModule,
-         getRandom: jest.fn().mockReturnValue(10),
-       };
-     });
-
-     const getRandom = require('../myModule').getRandom;
-
-     getRandom(); // Always returns 10
-     ```
-    */
+   * Returns the actual module instead of a mock, bypassing all checks on
+   * whether the module should receive a mock implementation or not.
+   *
+   * @example
+   * ```js
+   * jest.mock('../myModule', () => {
+   *   // Require the original module to not be mocked...
+   *   const originalModule = jest.requireActual('../myModule');
+   *
+   *   return {
+   *     __esModule: true, // Use it when dealing with esModules
+   *     ...originalModule,
+   *     getRandom: jest.fn().mockReturnValue(10),
+   *   };
+   * });
+   *
+   * const getRandom = require('../myModule').getRandom;
+   *
+   * getRandom(); // Always returns 10
+   * ```
+   */
   requireActual<T = unknown>(moduleName: string): T;
   /**
    * Wraps types of the `source` object and its deep members with type definitions

packages/jest-types/src/Config.ts

@@ -35,7 +35,7 @@ export type GlobalFakeTimersConfig = {
    *
    * @defaultValue
    * The default is `false`.
-   * */
+   */
   enableGlobally?: boolean;
 };
 
@@ -55,7 +55,7 @@ export type FakeTimersConfig = {
    *
    * @defaultValue
    * The default is `[]`, meaning all APIs are faked.
-   * */
+   */
   doNotFake?: Array<FakeableAPI>;
   /**
    * Sets current system time to be used by fake timers.

yarn.lock

@@ -2485,6 +2485,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@es-joy/jsdoccomment@npm:~0.31.0":
+  version: 0.31.0
+  resolution: "@es-joy/jsdoccomment@npm:0.31.0"
+  dependencies:
+    comment-parser: 1.3.1
+    esquery: ^1.4.0
+    jsdoc-type-pratt-parser: ~3.1.0
+  checksum: 1691ff501559f45593e5f080d2c08dea4fadba5f48e526b9ff2943c050fbb40408f5e83968542e5b6bf47219c7573796d00bfe80dacfd1ba8187904cc475cefb
+  languageName: node
+  linkType: hard
+
 "@eslint/eslintrc@npm:^1.3.0":
   version: 1.3.0
   resolution: "@eslint/eslintrc@npm:1.3.0"
@@ -2766,6 +2777,7 @@ __metadata:
     eslint-plugin-eslint-comments: ^3.1.2
     eslint-plugin-import: ^2.6.0
     eslint-plugin-jest: ^26.1.0
+    eslint-plugin-jsdoc: ^39.3.6
     eslint-plugin-local: ^1.0.0
     eslint-plugin-markdown: ^3.0.0
     eslint-plugin-prettier: ^4.0.0
@@ -7284,6 +7296,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"comment-parser@npm:1.3.1":
+  version: 1.3.1
+  resolution: "comment-parser@npm:1.3.1"
+  checksum: 421e6a113a3afd548500e7174ab46a2049dccf92e82bbaa3b209031b1bdf97552aabfa1ae2a120c0b62df17e1ba70e0d8b05d68504fee78e1ef974c59bcfe718
+  languageName: node
+  linkType: hard
+
 "common-tags@npm:^1.8.0":
   version: 1.8.2
   resolution: "common-tags@npm:1.8.2"
@@ -9099,6 +9118,23 @@ __metadata:
   languageName: node
   linkType: hard
 
+"eslint-plugin-jsdoc@npm:^39.3.6":
+  version: 39.3.6
+  resolution: "eslint-plugin-jsdoc@npm:39.3.6"
+  dependencies:
+    "@es-joy/jsdoccomment": ~0.31.0
+    comment-parser: 1.3.1
+    debug: ^4.3.4
+    escape-string-regexp: ^4.0.0
+    esquery: ^1.4.0
+    semver: ^7.3.7
+    spdx-expression-parse: ^3.0.1
+  peerDependencies:
+    eslint: ^7.0.0 || ^8.0.0
+  checksum: 0825a5eba6cdcb250e45cd5ad488bd234da346f324a11160ad4b8c9fb3c76d8e1457d462fa91c24f11bdff5ef0013375d65c366b648202254c4bcc79eed89060
+  languageName: node
+  linkType: hard
+
 "eslint-plugin-local@npm:^1.0.0":
   version: 1.0.0
   resolution: "eslint-plugin-local@npm:1.0.0"
@@ -13155,6 +13191,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"jsdoc-type-pratt-parser@npm:~3.1.0":
+  version: 3.1.0
+  resolution: "jsdoc-type-pratt-parser@npm:3.1.0"
+  checksum: 2f437b57621f1e481918165f6cf0e48256628a9e510d8b3f88a2ab667bf2128bf8b94c628b57c43e78f555ca61983e9c282814703840dc091d2623992214a061
+  languageName: node
+  linkType: hard
+
 "jsdom@npm:^20.0.0":
   version: 20.0.0
   resolution: "jsdom@npm:20.0.0"
@@ -19075,7 +19118,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"spdx-expression-parse@npm:^3.0.0":
+"spdx-expression-parse@npm:^3.0.0, spdx-expression-parse@npm:^3.0.1":
   version: 3.0.1
   resolution: "spdx-expression-parse@npm:3.0.1"
   dependencies: