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 · Dec 3, 2020 · 3462433 · 3462433
1 parent 17ce5fd
commit 3462433
Show file tree

Hide file tree

Showing 42 changed files with 114 additions and 67 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,
@@ -48,7 +48,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",
@@ -65,6 +70,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 = () => {}) {
@@ -206,7 +206,7 @@ class Encore {
      * })
      * ```
      *
-     * @param {function} optimizeCssPluginOptionsCallback
+     * @param {Function} optimizeCssPluginOptionsCallback
      * @returns {Encore}
      */
     configureOptimizeCssPlugin(optimizeCssPluginOptionsCallback = () => {}) {
@@ -350,7 +350,7 @@ class Encore {
      * })
      * ```
      *
-     * @param {Object<string, string>} aliases
+     * @param {object<string, string>} aliases
      *
      * @returns {Encore}
      */
@@ -746,7 +746,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) {
@@ -1237,7 +1237,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
@@ -1331,6 +1330,7 @@ class Encore {
      *
      * Internally, this disables the mini-css-extract-plugin
      * and uses the style-loader instead.
+     *
      * @param {boolean} disabled
      * @returns {Encore}
      */
@@ -1412,7 +1412,7 @@ class Encore {
      * falsy value the file-loader will be used instead.
      *
      * @param {{images?: false|object, fonts?: false|object}} urlLoaderOptions
-     * @return {Encore}
+     * @returns {Encore}
      */
     configureUrlLoader(urlLoaderOptions = {}) {
         webpackConfig.configureUrlLoader(urlLoaderOptions);
@@ -1440,7 +1440,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);
@@ -1633,31 +1633,31 @@ class Encore {
 
     /**
      * @deprecated
-     * @return {void}
+     * @returns {void}
      */
     configureExtractTextPlugin() {
         throw new Error('The configureExtractTextPlugin() method was removed from Encore. The underlying plugin was removed from Webpack 4.');
     }
 
     /**
      * @deprecated
-     * @return {void}
+     * @returns {void}
      */
     enableCoffeeScriptLoader() {
         throw new Error('The enableCoffeeScriptLoader() method and CoffeeScript support was removed from Encore due to support problems with Webpack 4. If you are interested in this feature, please submit a pull request!');
     }
 
     /**
      * @deprecated
-     * @return {void}
+     * @returns {void}
      */
     configureUglifyJsPlugin() {
         throw new Error('The configureUglifyJsPlugin() method was removed from Encore due to uglify-js dropping ES6+ support in its latest version. Please use configureTerserPlugin() instead.');
     }
 
     /**
      * @deprecated
-     * @return {void}
+     * @returns {void}
      */
     configureLoaderOptionsPlugin() {
         throw new Error('The configureLoaderOptionsPlugin() method was removed from Encore. The underlying plugin should not be needed anymore unless you are using outdated loaders. If that\'s the case you can still add it using addPlugin().');
@@ -1667,6 +1667,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
@@ -18,7 +18,7 @@ const regexpEscaper = require('./utils/regexp-escaper');
 
 /**
  * @param {RuntimeConfig|null} runtimeConfig
- * @return {void}
+ * @returns {void}
  */
 function validateRuntimeConfig(runtimeConfig) {
     // if you're using the encore executable, these things should never happen
@@ -37,7 +37,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
@@ -669,7 +669,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
@@ -17,7 +17,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)
@@ -57,7 +57,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, '');
@@ -70,7 +70,7 @@ module.exports = {
      * ok to use the publicPath as the manifestKeyPrefix.
      *
      * @param {WebpackConfig} webpackConfig
-     * @return {void}
+     * @returns {void}
      */
     validatePublicPathAndManifestKeyPrefix(webpackConfig) {
         if (webpackConfig.manifestKeyPrefix !== 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
@@ -86,7 +86,7 @@ function processOutput(webpackConfig) {
 /**
  * @param {Array} plugins
  * @param {WebpackConfig} webpackConfig
- * @return {void}
+ * @returns {void}
  */
 module.exports = function(plugins, webpackConfig) {
     plugins.push({