Migrate to eslint-plugin-jsdoc

The deprecated valid-jsdoc rule of eslint does not support using typescript syntax for types, while it allows being more precise about types in a much more readable way than using the older jsdoc syntax with separate typedef or callback definitions. The plugin also implements more rules than what valid-jsdoc does.
symfony · Apr 21, 2021 · 609fd3d · 609fd3d
1 parent e8ac09f
commit 609fd3d
Show file tree

Hide file tree

Showing 39 changed files with 110 additions and 63 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -9,8 +9,8 @@
 
 module.exports = {
     "root": true,
-    "plugins": ["node", "header"],
-    "extends": ["eslint:recommended", "plugin:node/recommended"],
+    "plugins": ["node", "header", "jsdoc"],
+    "extends": ["eslint:recommended", "plugin:node/recommended", "plugin:jsdoc/recommended"],
     "env": {
         "node": true,
         "es6": true,
@@ -49,7 +49,12 @@ module.exports = {
             "after": true
         }],
         "no-console": "off",
-        "valid-jsdoc": ["error", { "requireParamDescription": false, "requireReturnDescription": false }],
+        "jsdoc/require-jsdoc": "off",
+        "jsdoc/require-param-description": "off",
+        "jsdoc/require-property-description": "off",
+        "jsdoc/require-returns-description": "off",
+        // We use typescript-like literal `false` for some signatures, which is not yet supported natively by eslint-plugin-jsdoc
+        "jsdoc/no-undefined-types": ["error", { definedTypes: ["false"] }],
         "node/no-unsupported-features": ["error", { version: 8 }],
         "node/no-deprecated-api": "error",
         "node/no-missing-import": "error",
@@ -66,6 +71,11 @@ module.exports = {
         "node/process-exit-as-throw": "error",
         "header/header": [2, "block", { "pattern": "This file is part of the Symfony Webpack Encore package" }]
     },
+    "settings": {
+        "jsdoc": {
+            "mode": "typescript"
+        }
+    },
     "overrides": [
         {
             "files": [".eslintrc.js"],

diff --git a/index.js b/index.js
@@ -114,7 +114,7 @@ class Encore {
      * })
      * ```
      *
-     * @param {function} definePluginOptionsCallback
+     * @param {Function} definePluginOptionsCallback
      * @returns {Encore}
      */
     configureDefinePlugin(definePluginOptionsCallback = () => {}) {
@@ -135,7 +135,7 @@ class Encore {
      * })
      * ```
      *
-     * @param {function} friendlyErrorsPluginOptionsCallback
+     * @param {Function} friendlyErrorsPluginOptionsCallback
      * @returns {Encore}
      */
     configureFriendlyErrorsPlugin(friendlyErrorsPluginOptionsCallback = () => {}) {
@@ -156,7 +156,7 @@ class Encore {
      * })
      * ```
      *
-     * @param {function} manifestPluginOptionsCallback
+     * @param {Function} manifestPluginOptionsCallback
      * @returns {Encore}
      */
     configureManifestPlugin(manifestPluginOptionsCallback = () => {}) {
@@ -182,7 +182,7 @@ class Encore {
      * })
      * ```
      *
-     * @param {function} terserPluginOptionsCallback
+     * @param {Function} terserPluginOptionsCallback
      * @returns {Encore}
      */
     configureTerserPlugin(terserPluginOptionsCallback = () => {}) {
@@ -203,7 +203,7 @@ class Encore {
      * })
      * ```
      *
-     * @param {function} cssMinimizerPluginOptionsCallback
+     * @param {Function} cssMinimizerPluginOptionsCallback
      * @returns {Encore}
      */
     configureCssMinimizerPlugin(cssMinimizerPluginOptionsCallback = () => {}) {
@@ -347,7 +347,7 @@ class Encore {
      * })
      * ```
      *
-     * @param {Object<string, string>} aliases
+     * @param {object<string, string>} aliases
      *
      * @returns {Encore}
      */
@@ -721,7 +721,7 @@ class Encore {
      *  This is useful for older packages, that might
      *  expect jQuery (or something else) to be a global variable.
      *
-     * @param {Object<string, string|string[]>} variables
+     * @param {object<string, string | string[]>} variables
      * @returns {Encore}
      */
     autoProvideVariables(variables) {
@@ -1031,7 +1031,7 @@ class Encore {
      * ```
      *
      * @param {object} buildDependencies
-     * @param {function} cacheCallback
+     * @param {Function} cacheCallback
      * @returns {Encore}
      */
     enableBuildCache(buildDependencies, cacheCallback = (cache) => {}) {
@@ -1058,8 +1058,8 @@ class Encore {
      * );
      * ```
      *
-     * @param {function} loaderOptionsCallback
-     * @param {function} pluginOptionsCallback
+     * @param {Function} loaderOptionsCallback
+     * @param {Function} pluginOptionsCallback
      * @returns {Encore}
      */
     configureMiniCssExtractPlugin(loaderOptionsCallback, pluginOptionsCallback = () => {}) {
@@ -1271,7 +1271,6 @@ class Encore {
      * Supported options:
      *      * {boolean} lintVue (default=false)
      *              Configure the loader to lint `.vue` files
-     * ```
      *
      * @param {string|object|(function(object): object|void)} eslintLoaderOptionsOrCallback
      * @param {{lintVue?: boolean}} encoreOptions
@@ -1349,6 +1348,7 @@ class Encore {
      *
      * Internally, this disables the mini-css-extract-plugin
      * and uses the style-loader instead.
+     *
      * @param {boolean} disabled
      * @returns {Encore}
      */
@@ -1458,7 +1458,7 @@ class Encore {
      * ```
      *
      * @param {object} options
-     * @param {string|object|function} ruleCallback
+     * @param {string|object|Function} ruleCallback
      * @returns {Encore}
      */
     configureImageRule(options = {}, ruleCallback = (rule) => {}) {
@@ -1475,7 +1475,7 @@ class Encore {
      * See configureImageRule() for more details.
      *
      * @param {object} options
-     * @param {string|object|function} ruleCallback
+     * @param {string|object|Function} ruleCallback
      * @returns {Encore}
      */
     configureFontRule(options = {}, ruleCallback = (rule) => {}) {
@@ -1504,7 +1504,7 @@ class Encore {
      *
      * @param {string} name
      * @param {function(webpack.RuleSetRule): webpack.RuleSetRule|void} callback
-     * @return {Encore}
+     * @returns {Encore}
      */
     configureLoaderRule(name, callback) {
         webpackConfig.configureLoaderRule(name, callback);
@@ -1700,6 +1700,7 @@ class Encore {
 /**
  * Proxy the API in order to prevent calls to most of its methods
  * if the webpackConfig object hasn't been initialized yet.
+ *
  * @type {Encore}
  */
 module.exports = EncoreProxy.createProxy(new Encore());
diff --git a/lib/WebpackConfig.js b/lib/WebpackConfig.js
@@ -19,7 +19,7 @@ const { calculateDevServerUrl } = require('./config/path-util');
 
 /**
  * @param {RuntimeConfig|null} runtimeConfig
- * @return {void}
+ * @returns {void}
  */
 function validateRuntimeConfig(runtimeConfig) {
     // if you're using the encore executable, these things should never happen
@@ -38,7 +38,7 @@ function validateRuntimeConfig(runtimeConfig) {
 
 /**
  * @param {RuntimeConfig} runtimeConfig
- * @return {void}
+ * @returns {void}
  */
 function checkPackageJson(runtimeConfig) {
     // Display a warning if webpack is listed as a [dev-]dependency

diff --git a/lib/config-generator.js b/lib/config-generator.js
@@ -619,7 +619,7 @@ class ConfigGenerator {
 /**
  * @param {WebpackConfig} webpackConfig A configured WebpackConfig object
  *
- * @return {*} The final webpack config object
+ * @returns {*} The final webpack config object
  */
 module.exports = function(webpackConfig) {
     const generator = new ConfigGenerator(webpackConfig);

diff --git a/lib/config/parse-runtime.js b/lib/config/parse-runtime.js
@@ -16,7 +16,7 @@ const babel = require('@babel/core');
 
 /**
  * @param {object} argv
- * @param {String} cwd
+ * @param {string} cwd
  * @returns {RuntimeConfig}
  */
 module.exports = function(argv, cwd) {

diff --git a/lib/config/path-util.js b/lib/config/path-util.js
@@ -19,7 +19,7 @@ module.exports = {
      * Determines the "contentBase" to use for the devServer.
      *
      * @param {WebpackConfig} webpackConfig
-     * @return {String}
+     * @returns {string}
      */
     getContentBase(webpackConfig) {
         // strip trailing slash (for Unix or Windows)
@@ -59,7 +59,7 @@ module.exports = {
      * Returns the output path, but as a relative string (e.g. web/build)
      *
      * @param {WebpackConfig} webpackConfig
-     * @return {String}
+     * @returns {string}
      */
     getRelativeOutputPath(webpackConfig) {
         return webpackConfig.outputPath.replace(webpackConfig.getContext() + path.sep, '');
@@ -72,7 +72,7 @@ module.exports = {
      * ok to use the publicPath as the manifestKeyPrefix.
      *
      * @param {WebpackConfig} webpackConfig
-     * @return {void}
+     * @returns {void}
      */
     validatePublicPathAndManifestKeyPrefix(webpackConfig) {
         if (webpackConfig.manifestKeyPrefix !== null) {
@@ -120,7 +120,7 @@ module.exports = {
 
     /**
      * @param {RuntimeConfig} runtimeConfig
-     * @return {string|null|Object.public|*}
+     * @returns {string}
      */
     calculateDevServerUrl(runtimeConfig) {
         if (runtimeConfig.devServerFinalIsHttps === null) {

diff --git a/lib/loaders/babel.js b/lib/loaders/babel.js
@@ -16,7 +16,7 @@ const applyOptionsCallback = require('../utils/apply-options-callback');
 module.exports = {
     /**
      * @param {WebpackConfig} webpackConfig
-     * @return {Array} of loaders to use for Babel
+     * @returns {Array} of loaders to use for Babel
      */
     getLoaders(webpackConfig) {
         let babelConfig = {
@@ -106,7 +106,7 @@ module.exports = {
 
     /**
      * @param {WebpackConfig} webpackConfig
-     * @return {RegExp} to use for eslint-loader `test` rule
+     * @returns {RegExp} to use for eslint-loader `test` rule
      */
     getTest(webpackConfig) {
         const extensions = [

diff --git a/lib/loaders/css-extract.js b/lib/loaders/css-extract.js
@@ -19,7 +19,7 @@ module.exports = {
      *
      * @param {WebpackConfig} webpackConfig
      * @param {Array} loaders An array of some style loaders
-     * @return {Array}
+     * @returns {Array}
      */
     prependLoaders(webpackConfig, loaders) {
         if (!webpackConfig.extractCss) {

diff --git a/lib/loaders/css.js b/lib/loaders/css.js
@@ -17,7 +17,7 @@ module.exports = {
     /**
      * @param {WebpackConfig} webpackConfig
      * @param {boolean} useCssModules
-     * @return {Array} of loaders to use for CSS files
+     * @returns {Array} of loaders to use for CSS files
      */
     getLoaders(webpackConfig, useCssModules = false) {
         const usePostCssLoader = webpackConfig.usePostCssLoader;

diff --git a/lib/loaders/eslint.js b/lib/loaders/eslint.js
@@ -24,7 +24,7 @@ function isMissingConfigError(e) {
 module.exports = {
     /**
      * @param {WebpackConfig} webpackConfig
-     * @return {Object} of options to use for eslint-loader options.
+     * @returns {object} of options to use for eslint-loader options.
      */
     getOptions(webpackConfig) {
         loaderFeatures.ensurePackagesExistAndAreCorrectVersion('eslint');
@@ -73,7 +73,7 @@ Install ${chalk.yellow('babel-eslint')} to prevent potential parsing issues: ${p
 
     /**
      * @param {WebpackConfig} webpackConfig
-     * @return {RegExp} to use for eslint-loader `test` rule
+     * @returns {RegExp} to use for eslint-loader `test` rule
      */
     getTest(webpackConfig) {
         const extensions = ['jsx?'];

diff --git a/lib/loaders/handlebars.js b/lib/loaders/handlebars.js
@@ -16,7 +16,7 @@ const applyOptionsCallback = require('../utils/apply-options-callback');
 module.exports = {
     /**
      * @param {WebpackConfig} webpackConfig
-     * @return {Array} of loaders to use for Handlebars
+     * @returns {Array} of loaders to use for Handlebars
      */
     getLoaders(webpackConfig) {
         loaderFeatures.ensurePackagesExistAndAreCorrectVersion('handlebars');

diff --git a/lib/loaders/less.js b/lib/loaders/less.js
@@ -18,7 +18,7 @@ module.exports = {
     /**
      * @param {WebpackConfig} webpackConfig
      * @param {boolean} useCssModules
-     * @return {Array} of loaders to use for Less files
+     * @returns {Array} of loaders to use for Less files
      */
     getLoaders(webpackConfig, useCssModules = false) {
         loaderFeatures.ensurePackagesExistAndAreCorrectVersion('less');

diff --git a/lib/loaders/sass.js b/lib/loaders/sass.js
@@ -18,7 +18,7 @@ module.exports = {
     /**
      * @param {WebpackConfig} webpackConfig
      * @param {boolean} useCssModules
-     * @return {Array} of loaders to use for Sass files
+     * @returns {Array} of loaders to use for Sass files
      */
     getLoaders(webpackConfig, useCssModules = false) {
         loaderFeatures.ensurePackagesExistAndAreCorrectVersion('sass');

diff --git a/lib/loaders/stylus.js b/lib/loaders/stylus.js
@@ -18,7 +18,7 @@ module.exports = {
     /**
      * @param {WebpackConfig} webpackConfig
      * @param {boolean} useCssModules
-     * @return {Array} of loaders to use for Stylus files
+     * @returns {Array} of loaders to use for Stylus files
      */
     getLoaders(webpackConfig, useCssModules = false) {
         loaderFeatures.ensurePackagesExistAndAreCorrectVersion('stylus');

diff --git a/lib/loaders/typescript.js b/lib/loaders/typescript.js
@@ -17,7 +17,7 @@ const applyOptionsCallback = require('../utils/apply-options-callback');
 module.exports = {
     /**
      * @param {WebpackConfig} webpackConfig
-     * @return {Array} of loaders to use for TypeScript
+     * @returns {Array} of loaders to use for TypeScript
      */
     getLoaders(webpackConfig) {
         loaderFeatures.ensurePackagesExistAndAreCorrectVersion('typescript');

diff --git a/lib/loaders/vue.js b/lib/loaders/vue.js
@@ -17,7 +17,7 @@ const getVueVersion = require('../utils/get-vue-version');
 module.exports = {
     /**
      * @param {WebpackConfig} webpackConfig
-     * @return {Array} of loaders to use for Vue files
+     * @returns {Array} of loaders to use for Vue files
      */
     getLoaders(webpackConfig) {
         const vueVersion = getVueVersion(webpackConfig);

diff --git a/lib/plugins/asset-output-display.js b/lib/plugins/asset-output-display.js
@@ -21,7 +21,7 @@ const PluginPriorities = require('./plugin-priorities');
  * @param {Array} plugins
  * @param {WebpackConfig} webpackConfig
  * @param {FriendlyErrorsWebpackPlugin} friendlyErrorsPlugin
- * @return {void}
+ * @returns {void}
  */
 module.exports = function(plugins, webpackConfig, friendlyErrorsPlugin) {
     if (webpackConfig.useDevServer()) {

diff --git a/lib/plugins/clean.js b/lib/plugins/clean.js
@@ -19,7 +19,7 @@ const applyOptionsCallback = require('../utils/apply-options-callback');
  *
  * @param {Array} plugins to push to
  * @param {WebpackConfig} webpackConfig read only variable
- * @return {void}
+ * @returns {void}
  */
 module.exports = function(plugins, webpackConfig) {
 

diff --git a/lib/plugins/define.js b/lib/plugins/define.js
@@ -17,7 +17,7 @@ const applyOptionsCallback = require('../utils/apply-options-callback');
 /**
  * @param {Array} plugins
  * @param {WebpackConfig} webpackConfig
- * @return {void}
+ * @returns {void}
  */
 module.exports = function(plugins, webpackConfig) {
     const definePluginOptions = {

diff --git a/lib/plugins/delete-unused-entries.js b/lib/plugins/delete-unused-entries.js
@@ -17,7 +17,7 @@ const copyEntryTmpName = require('../utils/copyEntryTmpName');
 /**
  * @param {Array} plugins
  * @param {WebpackConfig} webpackConfig
- * @return {void}
+ * @returns {void}
  */
 module.exports = function(plugins, webpackConfig) {
     const entries = [... webpackConfig.styleEntries.keys()];

diff --git a/lib/plugins/entry-files-manifest.js b/lib/plugins/entry-files-manifest.js
@@ -84,7 +84,7 @@ function processOutput(webpackConfig) {
 /**
  * @param {Array} plugins
  * @param {WebpackConfig} webpackConfig
- * @return {void}
+ * @returns {void}
  */
 module.exports = function(plugins, webpackConfig) {
     plugins.push({