Add jsdoc/no-types eslint rule for TypeScript files (#44049)

Co-authored-by: JJ Kasper <jj@jjsweb.site>

.eslintrc.json

@@ -1,7 +1,7 @@
 {
   "root": true,
   "parser": "@babel/eslint-parser",
-  "plugins": ["react", "react-hooks", "jest", "import"],
+  "plugins": ["react", "react-hooks", "jest", "import", "jsdoc"],
   "env": {
     "browser": true,
     "commonjs": true,
@@ -96,7 +96,16 @@
         "@typescript-eslint/no-useless-constructor": "warn",
         "@typescript-eslint/prefer-literal-enum-member": "error",
         "@typescript-eslint/prefer-namespace-keyword": "error"
-      }
+      },
+      "overrides": [
+        {
+          "files": ["packages/**"],
+          "rules": {
+            "jsdoc/no-types": "error",
+            "jsdoc/no-undefined-types": "error"
+          }
+        }
+      ]
     },
     {
       "files": [

package.json

@@ -137,6 +137,7 @@
     "eslint-plugin-jest": "24.3.5",
     "eslint-plugin-react": "7.23.2",
     "eslint-plugin-react-hooks": "4.5.0",
+    "eslint-plugin-jsdoc": "39.6.4",
     "event-stream": "4.0.1",
     "execa": "2.0.3",
     "expect-type": "0.14.2",

packages/next/build/webpack/config/blocks/css/index.ts

@@ -28,10 +28,6 @@ const regexSassModules = /\.module\.(scss|sass)$/
 
 /**
  * Mark a rule as removable if built-in CSS support is disabled
- *
- * @param {webpack.RuleSetRule} r the rule to mark
- *
- * @returns {webpack.RuleSetRule} the marked rule
  */
 function markRemovable(r: webpack.RuleSetRule): webpack.RuleSetRule {
   Object.defineProperty(r, Symbol.for('__next_css_remove'), {
@@ -83,15 +79,11 @@ export async function lazyPostCSS(
         /**
          * Returns the vendor prefix extracted from an input string.
          *
-         * @param {string} prop String with or without vendor prefix.
-         *
-         * @return {string} vendor prefix or empty string
-         *
          * @example
          * postcss.vendor.prefix('-moz-tab-size') //=> '-moz-'
          * postcss.vendor.prefix('tab-size')      //=> ''
          */
-        prefix: function prefix(prop: any) {
+        prefix: function prefix(prop: string): string {
           const match = prop.match(/^(-\w+-)/)
 
           if (match) {
@@ -104,14 +96,15 @@ export async function lazyPostCSS(
         /**
          * Returns the input string stripped of its vendor prefix.
          *
-         * @param {string} prop String with or without vendor prefix.
-         *
-         * @return {string} String name without vendor prefixes.
-         *
          * @example
          * postcss.vendor.unprefixed('-moz-tab-size') //=> 'tab-size'
          */
-        unprefixed: function unprefixed(prop: any) {
+        unprefixed: function unprefixed(
+          /**
+           * String with or without vendor prefix.
+           */
+          prop: string
+        ): string {
           return prop.replace(/^-\w+-/, '')
         },
       }

packages/next/client/page-loader.ts

@@ -145,10 +145,10 @@ export default class PageLoader {
     )
   }
 
-  /**
-   * @param {string} route - the route (file-system path)
-   */
-  _isSsg(route: string): Promise<boolean> {
+  _isSsg(
+    /** the route (file-system path) */
+    route: string
+  ): Promise<boolean> {
     return this.promisedSsgManifest.then((manifest) => manifest.has(route))
   }
 

packages/next/lib/eslint/writeOutputFile.ts

@@ -5,10 +5,12 @@ import isError from '../../lib/is-error'
 
 /**
  * Check if a given file path is a directory or not.
- * @param {string} filePath The path to a file to check.
- * @returns {Promise<boolean>} `true` if the path is a directory.
+ * Returns `true` if the path is a directory.
  */
-async function isDirectory(filePath: string): Promise<boolean> {
+async function isDirectory(
+  /**  The path to a file to check. */
+  filePath: string
+): Promise<boolean> {
   try {
     return (await fs.stat(filePath)).isDirectory()
   } catch (error) {
@@ -23,10 +25,13 @@ async function isDirectory(filePath: string): Promise<boolean> {
 }
 /**
  * Create a file with eslint output data
- * @param {string} outputFile The name file that needs to be created
- * @param {string} outputData The data that needs to be inserted into the file
  */
-export async function writeOutputFile(outputFile: string, outputData: string) {
+export async function writeOutputFile(
+  /** The name file that needs to be created */
+  outputFile: string,
+  /** The data that needs to be inserted into the file */
+  outputData: string
+): Promise<void> {
   const filePath = path.resolve(process.cwd(), outputFile)
 
   if (await isDirectory(filePath)) {

packages/next/lib/recursive-delete.ts

@@ -35,14 +35,13 @@ const unlinkPath = async (p: string, isDir = false, t = 1): Promise<void> => {
 
 /**
  * Recursively delete directory contents
- * @param  {string} dir Directory to delete the contents of
- * @param  {RegExp} [exclude] Exclude based on relative file path
- * @param  {string} [previousPath] Ensures that parameter dir exists, this is not passed recursively
- * @returns Promise void
  */
 export async function recursiveDelete(
+  /** Directory to delete the contents of */
   dir: string,
+  /** Exclude based on relative file path */
   exclude?: RegExp,
+  /** Ensures that parameter dir exists, this is not passed recursively */
   previousPath: string = ''
 ): Promise<void> {
   let result

packages/next/lib/recursive-readdir.ts

@@ -3,17 +3,18 @@ import { join } from 'path'
 
 /**
  * Recursively read directory
- * @param  {string} dir Directory to read
- * @param  {RegExp} filter Filter for the file name, only the name part is considered, not the full path
- * @param  {string[]=[]} arr This doesn't have to be provided, it's used for the recursion
- * @param  {string=dir`} rootDir Used to replace the initial path, only the relative path is left, it's faster than path.relative.
- * @returns Promise array holding all relative paths
+ * Returns array holding all relative paths
  */
 export async function recursiveReadDir(
+  /** Directory to read */
   dir: string,
+  /** Filter for the file name, only the name part is considered, not the full path */
   filter: RegExp,
+  /** Filter for the file name, only the name part is considered, not the full path */
   ignore?: RegExp,
+  /** This doesn't have to be provided, it's used for the recursion */
   arr: string[] = [],
+  /** Used to replace the initial path, only the relative path is left, it's faster than path.relative. */
   rootDir: string = dir
 ): Promise<string[]> {
   const result = await promises.readdir(dir, { withFileTypes: true })

packages/next/server/lib/recursive-readdir-sync.ts

@@ -3,13 +3,14 @@ import { join } from 'path'
 
 /**
  * Recursively read directory
- * @param  {string[]=[]} arr This doesn't have to be provided, it's used for the recursion
- * @param  {string=dir`} rootDir Used to replace the initial path, only the relative path is left, it's faster than path.relative.
- * @returns Array holding all relative paths
+ * Returns array holding all relative paths
  */
 export function recursiveReadDirSync(
+  /** The directory to read */
   dir: string,
+  /** This doesn't have to be provided, it's used for the recursion */
   arr: string[] = [],
+  /** Used to replace the initial path, only the relative path is left, it's faster than path.relative. */
   rootDir = dir
 ): string[] {
   const result = fs.readdirSync(dir)