eslint-plugin-jsdoc: Use TypeScript recommendations (#21556)

* eslint-plugin-jsdoc: Use TypeScript recommendations

* Fix new issues

* Update JSDocs

* Fix JSDoc

(Thanks, Copilot, for getting this wrong...)

.eslintrc.json

@@ -17,7 +17,7 @@
     "plugin:@typescript-eslint/stylistic",
     "plugin:import/recommended",
     "plugin:import/typescript",
-    "plugin:jsdoc/recommended"
+    "plugin:jsdoc/recommended-typescript"
   ],
   "settings": {
     "import/resolver": {
@@ -65,10 +65,7 @@
         }
       }
     ],
-    "jsdoc/require-param-type": "error",
     "jsdoc/require-returns": "error",
-    "jsdoc/require-returns-type": "error",
-    "jsdoc/no-undefined-types": "error",
     "jsdoc/require-yields": "error",
     "linebreak-style": ["error", "unix"],
     "no-console": "off",

index.ts

@@ -15,10 +15,10 @@ const dirname = fileURLToPath(new URL('.', import.meta.url));
 
 /**
  * Recursively load one or more directories passed as arguments.
- * @param {string[]} dirs The directories to load
- * @returns {object} All of the browser compatibility data
+ * @param dirs The directories to load
+ * @returns All of the browser compatibility data
  */
-const load = async (...dirs: string[]) => {
+const load = async (...dirs: string[]): Promise<CompatData> => {
   const result = {};
 
   for (const dir of dirs) {
@@ -49,10 +49,10 @@ const load = async (...dirs: string[]) => {
     }
   }
 
-  return result;
+  return result as CompatData;
 };
 
-export default (await load(
+export default await load(
   'api',
   'browsers',
   'css',
@@ -64,4 +64,4 @@ export default (await load(
   'webassembly',
   'webdriver',
   'webextensions',
-)) as CompatData;
+);

scripts/diff-features.ts

@@ -10,11 +10,11 @@ import { hideBin } from 'yargs/helpers';
 
 /**
  * Compare two references and print diff as Markdown or JSON
- * @param {{ref1: string | undefined, ref2: string | undefined, format: string, github: boolean}} opts Options
- * @param {string} opts.ref1 First reference to compare
- * @param {string} opts.ref2 Second reference to compare
- * @param {string} opts.format Format to export data as (either 'markdown' or 'json', default 'json')
- * @param {boolean} opts.github Whether to obtain artifacts from GitHub
+ * @param opts Options
+ * @param opts.ref1 First reference to compare
+ * @param opts.ref2 Second reference to compare
+ * @param opts.format Format to export data as (either 'markdown' or 'json', default 'json')
+ * @param opts.github Whether to obtain artifacts from GitHub
  */
 const main = (opts: {
   ref1: string | undefined;
@@ -34,12 +34,12 @@ const main = (opts: {
 
 /**
  * Compare two references and get feature diff
- * @param {{ref1: string | null, ref2: string | null, github: boolean, quiet: boolean}} opts Options
- * @param {string?} opts.ref1 First reference to compare
- * @param {string?} opts.ref2 Second reference to compare
- * @param {boolean} opts.github Whether to obtain artifacts from GitHub
- * @param {boolean} opts.quiet If true, don't log to conolse
- * @returns {{added: string[], removed: string[]}} Diff between two refs
+ * @param opts Options
+ * @param opts.ref1 First reference to compare
+ * @param opts.ref2 Second reference to compare
+ * @param opts.github Whether to obtain artifacts from GitHub
+ * @param opts.quiet If true, don't log to console
+ * @returns Diff between two refs
  */
 const diff = (opts: {
   ref1?: string;
@@ -75,10 +75,10 @@ const diff = (opts: {
 
 /**
  * Enumerate features from GitHub or local checkout
- * @param {string} ref Reference to obtain features for
- * @param {boolean} skipGithub Skip fetching artifacts from GitHub
- * @param {boolean} quiet If true, don't log to console
- * @returns {Set<string>} Feature list from reference
+ * @param ref Reference to obtain features for
+ * @param skipGithub Skip fetching artifacts from GitHub
+ * @param quiet If true, don't log to console
+ * @returns Feature list from reference
  */
 const enumerate = (
   ref: string,
@@ -102,8 +102,8 @@ const enumerate = (
 
 /**
  * Enumerate features from GitHub
- * @param {string} ref Reference to obtain features for
- * @returns {string[]} Feature list from reference
+ * @param ref Reference to obtain features for
+ * @returns Feature list from reference
  */
 const getEnumerationFromGithub = (ref: string): string[] => {
   const ENUMERATE_WORKFLOW = '15595228';
@@ -153,9 +153,9 @@ const getEnumerationFromGithub = (ref: string): string[] => {
 
 /**
  * Enumerate features from local checkout
- * @param {string} ref Reference to obtain features for
- * @param {boolean} quiet If true, don't log to console
- * @returns {string[]} Feature list from reference
+ * @param ref Reference to obtain features for
+ * @param quiet If true, don't log to console
+ * @returns Feature list from reference
  */
 const enumerateFeatures = (ref = 'HEAD', quiet = false): string[] => {
   // Get the short hash for this ref.
@@ -194,15 +194,15 @@ const enumerateFeatures = (ref = 'HEAD', quiet = false): string[] => {
 
 /**
  * Format feature for Markdown printing
- * @param {string} feat Feature
- * @returns {string} Formatted feature
+ * @param feat Feature
+ * @returns Formatted feature
  */
 const fmtFeature = (feat: string) => `- \`${feat}\``;
 
 /**
  * Print feature diff as Markdown
- * @param {Array.<string>} added List of added features
- * @param {Array.<string>} removed List of removed features
+ * @param added List of added features
+ * @param removed List of removed features
  */
 const printMarkdown = (added: string[], removed: string[]): void => {
   if (removed.length) {

scripts/diff.ts

@@ -26,11 +26,11 @@ interface DiffItem {
 /**
  * Get contents from base and head commits
  * Note: This does not detect renamed files
- * @param {string} baseCommit Base commit
- * @param {string} basePath Base path
- * @param {string} headCommit Head commit
- * @param {string} headPath Head path
- * @returns {Contents} The contents of both commits
+ * @param baseCommit Base commit
+ * @param basePath Base path
+ * @param headCommit Head commit
+ * @param headPath Head path
+ * @returns The contents of both commits
  */
 const getBaseAndHeadContents = (
   baseCommit: string,
@@ -45,23 +45,23 @@ const getBaseAndHeadContents = (
 
 /**
  * Returns a formatted string of before-and-after changes
- * @param {any} lhs Left-hand (before) side
- * @param {any} rhs Right-hand (after) side
- * @returns {string} Formatted string
+ * @param lhs Left-hand (before) side
+ * @param rhs Right-hand (after) side
+ * @returns Formatted string
  */
 const stringifyChange = (lhs: any, rhs: any): string =>
   `${JSON.stringify(lhs)} → ${JSON.stringify(rhs)}`;
 
 /**
  * Perform mirroring on specified diff statement
- * @param {{base: SupportStatement, head: SupportStatement}} diff The diff to perform mirroring on
- * @param {SupportStatement} diff.base The diff to perform mirroring on
- * @param {SupportStatement} diff.head The diff to perform mirroring on
- * @param {{base: Identifier, head: Identifier}} contents The contents to mirror from
- * @param {Identifier} contents.base The contents to mirror from
- * @param {Identifier} contents.head The contents to mirror from
- * @param {Array.<string>} path The feature path to mirror
- * @param {'base' | 'head'} direction Whether to mirror 'base' or 'head'
+ * @param diff The diff to perform mirroring on
+ * @param diff.base The diff to perform mirroring on
+ * @param diff.head The diff to perform mirroring on
+ * @param contents The contents to mirror from
+ * @param contents.base The contents to mirror from
+ * @param contents.head The contents to mirror from
+ * @param path The feature path to mirror
+ * @param direction Whether to mirror 'base' or 'head'
  */
 const doMirror = (
   diff: { base: SupportStatement; head: SupportStatement },
@@ -78,9 +78,9 @@ const doMirror = (
 
 /**
  * Describe the diff in text form (internal function)
- * @param {Diff<string, string>} diffItem The diff to describe
- * @param {Contents} contents The contents of the diff
- * @returns {string} A human-readable diff description
+ * @param diffItem The diff to describe
+ * @param contents The contents of the diff
+ * @returns A human-readable diff description
  */
 const describeByKind = (
   diffItem: Diff<string, string>,
@@ -125,9 +125,9 @@ const describeByKind = (
 
 /**
  * Describe the diff in text form
- * @param {Diff<string, string>} diffItem The diff to describe
- * @param {Contents} contents The contents of the diff
- * @returns {DiffItem} A human-readable diff description
+ * @param diffItem The diff to describe
+ * @param contents The contents of the diff
+ * @returns A human-readable diff description
  */
 const describeDiffItem = (
   diffItem: Diff<string, string>,
@@ -152,8 +152,8 @@ const describeDiffItem = (
 
 /**
  * Merge diff together as a map
- * @param {DiffItem[]} items Diff items to merge
- * @returns {Map<string, string>} A map of the diff items
+ * @param items Diff items to merge
+ * @returns A map of the diff items
  */
 const mergeAsMap = (items: DiffItem[]): Map<string, string> => {
   const map = new Map();
@@ -167,9 +167,9 @@ const mergeAsMap = (items: DiffItem[]): Map<string, string> => {
 
 /**
  * Get the diffs as a map
- * @param {string} base Base ref
- * @param {string} head Head ref
- * @returns {Map<string, string>} A map of the diff items
+ * @param base Base ref
+ * @param head Head ref
+ * @returns A map of the diff items
  */
 const getDiffs = (base: string, head = ''): Map<string, string> => {
   const namedDescriptions: { name: string; description: string }[] = [];

scripts/enumerate-features.ts

@@ -12,9 +12,9 @@ import { lowLevelWalk } from '../utils/walk.js';
 
 /**
  * Enumerate features and write to a destination file
- * @param {{dest: string, dataFrom: string}} argv Arguments
- * @param {string} argv.dest Destination file name
- * @param {string?} argv.dataFrom Where the data is (leave blank for repository folder)
+ * @param argv Arguments
+ * @param argv.dest Destination file name
+ * @param argv.dataFrom Where the data is (leave blank for repository folder)
  */
 const main = async (argv: {
   dest: string;
@@ -26,8 +26,8 @@ const main = async (argv: {
 
 /**
  * Enumerate compat data features
- * @param {string?} dataFrom Where to get the data from (leave blank for repository folder)
- * @returns {string[]} A list of features
+ * @param dataFrom Where to get the data from (leave blank for repository folder)
+ * @returns A list of features
  */
 const enumerateFeatures = async (dataFrom?: string): Promise<string[]> => {
   const feats: string[] = [];

scripts/fix/browser-order.ts

@@ -16,9 +16,9 @@ import { IS_WINDOWS } from '../../test/utils.js';
  * and so will be stringified in that order as well. This relies on
  * guaranteed "own" property ordering, which is insertion order for
  * non-integer keys (which is our case).
- * @param {string} key The key of the object
- * @param {CompatStatement} value The value of the key
- * @returns {CompatStatement} Value with sorting applied
+ * @param key The key of the object
+ * @param value The value of the key
+ * @returns Value with sorting applied
  */
 export const orderSupportBlock = (
   key: string,
@@ -41,7 +41,7 @@ export const orderSupportBlock = (
  * Perform a fix of the browser order of a __compat.support block within
  * all the data in a specified file.  The function will then automatically
  * write any needed changes back into the file.
- * @param {string} filename The path to the file to fix in-place
+ * @param filename The path to the file to fix in-place
  */
 const fixBrowserOrder = (filename: string): void => {
   let actual = fs.readFileSync(filename, 'utf-8').trim();

scripts/fix/feature-order.ts

@@ -13,9 +13,9 @@ import { IS_WINDOWS } from '../../test/utils.js';
  * stringified in that order as well. This relies on guaranteed "own"
  * property ordering, which is insertion order for non-integer keys
  * (which is our case).
- * @param {string} _ The key in the object
- * @param {Identifier} value The value of the key
- * @returns {Identifier} The new value
+ * @param _ The key in the object
+ * @param value The value of the key
+ * @returns The new value
  */
 export const orderFeatures = (_: string, value: Identifier): Identifier => {
   if (value instanceof Object && '__compat' in value) {
@@ -32,7 +32,7 @@ export const orderFeatures = (_: string, value: Identifier): Identifier => {
 /**
  * Perform a fix of feature order within all the data in a specified file.
  * The function will then automatically write any needed changes back into the file.
- * @param {string} filename The filename to perform fix upon
+ * @param filename The filename to perform fix upon
  */
 const fixFeatureOrder = (filename: string): void => {
   let actual = fs.readFileSync(filename, 'utf-8').trim();

scripts/fix/index.ts

@@ -21,7 +21,7 @@ const dirname = fileURLToPath(new URL('.', import.meta.url));
 
 /**
  * Recursively load one or more files and/or directories passed as arguments and perform automatic fixes.
- * @param {string[]} files The files to load and perform fix upon
+ * @param files The files to load and perform fix upon
  */
 const load = async (...files: string[]): Promise<void> => {
   for (let file of files) {

scripts/fix/links.ts

@@ -8,7 +8,7 @@ import { processData } from '../../test/linter/test-links.js';
 
 /**
  * Fix issues with links throughout the BCD files
- * @param {string} filename The name of the file to fix
+ * @param filename The name of the file to fix
  */
 const fixLinks = (filename: string): void => {
   const original = fs.readFileSync(filename, 'utf-8').trim();

scripts/fix/mirror.ts

@@ -20,9 +20,9 @@ const downstreamBrowsers = (
 
 /**
  * Check to see if the statement is equal to the mirrored statement
- * @param {InternalSupportBlock} support The support statement to test
- * @param {BrowserName} browser The browser to mirror for
- * @returns {boolean} Whether the support statement is equal to mirroring
+ * @param support The support statement to test
+ * @param browser The browser to mirror for
+ * @returns Whether the support statement is equal to mirroring
  */
 export const isMirrorEquivalent = (
   support: InternalSupportBlock,
@@ -47,7 +47,7 @@ export const isMirrorEquivalent = (
 
 /**
  * Set the support statement for each browser to mirror if it matches mirroring
- * @param {CompatData} bcd The compat data to update
+ * @param bcd The compat data to update
  */
 export const mirrorIfEquivalent = (bcd: CompatData): void => {
   for (const { compat } of walk(undefined, bcd)) {
@@ -61,7 +61,7 @@ export const mirrorIfEquivalent = (bcd: CompatData): void => {
 
 /**
  * Update compat data to 'mirror' if the statement matches mirroring
- * @param {string} filename The name of the file to fix
+ * @param filename The name of the file to fix
  */
 const fixMirror = (filename: string): void => {
   const actual = fs.readFileSync(filename, 'utf-8').trim();

scripts/fix/property-order.ts

@@ -8,7 +8,7 @@ import stringifyAndOrderProperties from '../lib/stringify-and-order-properties.j
 
 /**
  * Fix issues with the property order throughout the BCD files
- * @param {string} filename The name of the file to fix
+ * @param filename The name of the file to fix
  */
 const fixPropertyOrder = (filename: string): void => {
   let actual = fs.readFileSync(filename, 'utf-8').trim();

scripts/fix/statement-order.ts

@@ -11,9 +11,9 @@ import compareStatements from '../lib/compare-statements.js';
  * Return a new "support_block" object whose support statements have
  * been ordered in reverse chronological order, moving statements
  * with flags, partial support, prefixes, or alternative names lower.
- * @param {string} key The key in the object
- * @param {CompatStatement} value The value of the key
- * @returns {CompatStatement} The new value
+ * @param key The key in the object
+ * @param value The value of the key
+ * @returns The new value
  */
 export const orderStatements = (
   key: string,
@@ -32,7 +32,7 @@ export const orderStatements = (
 
 /**
  * Fix issues with statement order throughout the BCD files
- * @param {string} filename The name of the file to fix
+ * @param filename The name of the file to fix
  */
 const fixStatementOrder = (filename: string): void => {
   let actual = fs.readFileSync(filename, 'utf-8').trim();