From fe3e204def266d287f52924189f6b4f5006a9dd0 Mon Sep 17 00:00:00 2001 From: Christophe Coevoet Date: Fri, 30 Aug 2024 11:40:55 +0200 Subject: [PATCH] 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. --- .eslintrc.js | 17 ++- index.js | 108 ++++++++++--------- lib/WebpackConfig.js | 6 +- lib/config-generator.js | 3 +- lib/config/parse-runtime.js | 2 +- lib/config/path-util.js | 8 +- lib/loaders/babel.js | 4 +- lib/loaders/css-extract.js | 2 +- lib/loaders/css.js | 2 +- lib/loaders/handlebars.js | 2 +- lib/loaders/less.js | 2 +- lib/loaders/sass.js | 2 +- lib/loaders/stylus.js | 2 +- lib/loaders/typescript.js | 2 +- lib/loaders/vue.js | 2 +- lib/plugins/asset-output-display.js | 2 +- lib/plugins/clean.js | 2 +- lib/plugins/define.js | 2 +- lib/plugins/delete-unused-entries.js | 2 +- lib/plugins/entry-files-manifest.js | 2 +- lib/plugins/forked-ts-types.js | 2 +- lib/plugins/friendly-errors.js | 2 +- lib/plugins/manifest.js | 2 +- lib/plugins/mini-css-extract.js | 2 +- lib/plugins/notifier.js | 2 +- lib/plugins/optimize-css-assets.js | 2 +- lib/plugins/terser.js | 2 +- lib/plugins/variable-provider.js | 2 +- lib/plugins/vue.js | 2 +- lib/utils/get-vue-version.js | 2 +- lib/utils/manifest-key-prefix-helper.js | 2 +- lib/utils/package-up.js | 2 +- lib/utils/pretty-error.js | 3 +- lib/utils/regexp-escaper.js | 2 +- lib/utils/string-escaper.js | 2 +- package.json | 1 + test/helpers/assert.js | 8 +- test/helpers/setup.js | 2 +- yarn.lock | 133 ++++++++++++++++++++++++ 39 files changed, 245 insertions(+), 104 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index a018f2a46..397c19740 100644 --- 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,13 @@ 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", + "jsdoc/tag-lines": ["warn", "never", { + "startLines": 1 + }], "node/no-unsupported-features": ["error", { version: 8 }], "node/no-deprecated-api": "error", "node/no-missing-import": "error", @@ -66,6 +72,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 index be4b35c02..d8c4b16fc 100644 --- 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 = () => {}) { @@ -249,7 +249,7 @@ class Encore { * If the JavaScript files imports/requires CSS/Sass/LESS files, * then a CSS file (e.g. main.css) will also be output. * - * @param {Object.} entries where the Keys are the + * @param {Record} entries where the Keys are the * names (without extension) that will be used * as the output filename (e.g. app will become app.js) * in the output directory. The values are the path(s) @@ -337,7 +337,6 @@ class Encore { * Adds a custom loader config * * @param {object} loader The loader config object - * * @returns {Encore} */ addLoader(loader) { @@ -350,7 +349,6 @@ class Encore { * Alias to addLoader * * @param {object} rule - * * @returns {Encore} */ addRule(rule) { @@ -374,8 +372,7 @@ class Encore { * }) * ``` * - * @param {object} aliases - * + * @param {Record} aliases * @returns {Encore} */ addAliases(aliases) { @@ -415,7 +412,6 @@ class Encore { * ``` * * @param {*} externals - * * @returns {Encore} */ addExternals(externals) { @@ -496,7 +492,7 @@ class Encore { * You can pass all the options supported by the SplitChunksPlugin * but also the following shorthand provided by Encore: * - * * `node_modules`: An array of `node_modules` packages names + * - `node_modules`: An array of `node_modules` packages names * * For example: * @@ -511,9 +507,9 @@ class Encore { * * By default, the new cache group will be created with the * following options: - * * `chunks` set to `"all"` - * * `enforce` set to `true` - * * `name` set to the value of the "name" parameter + * - `chunks` set to `"all"` + * - `enforce` set to `true` + * - `name` set to the value of the "name" parameter * * @param {string} name The chunk name (e.g. vendor to create a vendor.js) * @param {object} options Cache group option @@ -567,22 +563,22 @@ class Encore { * ``` * * Notes: - * * No transformation is applied to the copied files (for instance + * No transformation is applied to the copied files (for instance * copying a CSS file won't minify it) * * Supported options: - * * {string} from (mandatory) + * - {string} from (mandatory) * The path of the source directory (mandatory) - * * {RegExp|string} pattern (default: all files) + * - {RegExp|string} pattern (default: all files) * A regular expression (or a string containing one) that * the filenames must match in order to be copied - * * {string} to (default: [path][name].[ext]) + * - {string} to (default: [path][name].[ext]) * Where the files must be copied to. You can add all the * placeholders supported by the file-loader. * https://github.com/webpack-contrib/file-loader#placeholders - * * {boolean} includeSubdirectories (default: true) + * - {boolean} includeSubdirectories (default: true) * Whether or not the copy should include subdirectories. - * * {string} context (default: path of the source directory) + * - {string} context (default: path of the source directory) * The context to use as a root path when copying files. * * @param {object|Array} configs @@ -670,7 +666,7 @@ class Encore { * }); * ``` * - * @param {function} callback + * @param {Function} callback * @returns {Encore} */ configureSplitChunks(callback) { @@ -692,7 +688,7 @@ class Encore { * }); * ``` * - * @param {function} callback + * @param {Function} callback * @returns {Encore} */ configureWatchOptions(callback) { @@ -719,7 +715,7 @@ class Encore { * }); * ``` * - * @param {function} callback + * @param {Function} callback * @returns {Encore} */ configureDevServerOptions(callback) { @@ -747,7 +743,7 @@ class Encore { * This is useful for older packages, that might * expect jQuery (or something else) to be a global variable. * - * @param {object} variables + * @param {Record} variables * @returns {Encore} */ autoProvideVariables(variables) { @@ -795,7 +791,7 @@ class Encore { * }) * ``` * - * @param {function} postCssLoaderOptionsCallback + * @param {Function} postCssLoaderOptionsCallback * @returns {Encore} */ enablePostCssLoader(postCssLoaderOptionsCallback = () => {}) { @@ -824,18 +820,18 @@ class Encore { * ``` * * Supported options: - * * {boolean} resolveUrlLoader (default=true) + * - {boolean} resolveUrlLoader (default=true) * Whether or not to use the resolve-url-loader. * Setting to false can increase performance in some * cases, especially when using bootstrap_sass. But, * when disabled, all url()'s are resolved relative * to the original entry file... not whatever file * the url() appears in. - * * {object} resolveUrlLoaderOptions (default={}) + * - {object} resolveUrlLoaderOptions (default={}) * Options parameters for resolve-url-loader * // https://www.npmjs.com/package/resolve-url-loader#options * - * @param {function} sassLoaderOptionsCallback + * @param {Function} sassLoaderOptionsCallback * @param {object} encoreOptions * @returns {Encore} */ @@ -862,7 +858,7 @@ class Encore { * }); * ``` * - * @param {function} lessLoaderOptionsCallback + * @param {Function} lessLoaderOptionsCallback * @returns {Encore} */ enableLessLoader(lessLoaderOptionsCallback = () => {}) { @@ -887,7 +883,7 @@ class Encore { * }); * ``` * - * @param {function} stylusLoaderOptionsCallback + * @param {Function} stylusLoaderOptionsCallback * @returns {Encore} */ enableStylusLoader(stylusLoaderOptionsCallback = () => {}) { @@ -932,7 +928,7 @@ class Encore { * ``` * * Supported options: - * * {Condition} exclude (default=/(node_modules|bower_components)/) + * - {Condition} exclude (default=/(node_modules|bower_components)/) * A Webpack Condition passed to the JS/JSX rule that * determines which files and folders should not be * processed by Babel (https://webpack.js.org/configuration/module/#condition). @@ -943,7 +939,7 @@ class Encore { * they are not excluded anymore. * Cannot be used if the "includeNodeModules" option is * also set. - * * {string[]} includeNodeModules + * - {string[]} includeNodeModules * If set that option will include the given Node modules to * the files that are processed by Babel. * Can be used even if you have an external Babel configuration @@ -951,7 +947,7 @@ class Encore { * Warning: .babelrc config files don't apply to node_modules. Use * babel.config.json instead to apply the same config to these modules. * Cannot be used if the "exclude" option is also set - * * {'usage'|'entry'|false} useBuiltIns (default=false) + * - {'usage'|'entry'|false} useBuiltIns (default=false) * Set the "useBuiltIns" option of @babel/preset-env that changes * how it handles polyfills (https://babeljs.io/docs/en/babel-preset-env#usebuiltins) * Using it with 'entry' will require you to import core-js @@ -962,12 +958,12 @@ class Encore { * Cannot be used if you have an external Babel configuration (a .babelrc * file for instance). In this case you can set the option directly into * that configuration file. - * * {number|string|object} corejs (default=not set) + * - {number|string|object} corejs (default=not set) * Set the "corejs" option of @babel/preset-env. * It should contain the version of core-js you added to your project * if useBuiltIns isn't set to false. * - * @param {function|null} callback + * @param {Function|null} callback * @param {object} encoreOptions * @returns {Encore} */ @@ -993,7 +989,7 @@ class Encore { * }); * ``` * - * @param {function} callback + * @param {Function} callback * @returns {Encore} */ configureBabelPresetEnv(callback) { @@ -1014,7 +1010,7 @@ class Encore { * }); * ``` * - * @param {function} callback + * @param {Function} callback * @returns {Encore} */ configureCssLoader(callback) { @@ -1047,7 +1043,7 @@ class Encore { * // __filename means that changes to webpack.config.js should invalidate the cache * config: [__filename], * }); - ** + * * // also configure other options the Webpack "cache" key * Encore.enableBuildCache({ config: [__filename] }, (cache) => { * cache.version: `${process.env.GIT_REV}`; @@ -1057,7 +1053,7 @@ class Encore { * ``` * * @param {object} buildDependencies - * @param {function} cacheCallback + * @param {Function} cacheCallback * @returns {Encore} */ enableBuildCache(buildDependencies, cacheCallback = (cache) => {}) { @@ -1084,8 +1080,8 @@ class Encore { * ); * ``` * - * @param {function} loaderOptionsCallback - * @param {function} pluginOptionsCallback + * @param {Function} loaderOptionsCallback + * @param {Function} pluginOptionsCallback * @returns {Encore} */ configureMiniCssExtractPlugin(loaderOptionsCallback, pluginOptionsCallback = () => {}) { @@ -1150,7 +1146,7 @@ class Encore { * }); * ``` * - * @param {function} callback + * @param {Function} callback * @returns {Encore} */ enableTypeScriptLoader(callback = () => {}) { @@ -1165,7 +1161,7 @@ class Encore { * * This is a build optimization API to reduce build times. * - * @param {function} forkedTypeScriptTypesCheckOptionsCallback + * @param {Function} forkedTypeScriptTypesCheckOptionsCallback * @returns {Encore} */ enableForkedTypeScriptTypesChecking(forkedTypeScriptTypesCheckOptionsCallback = () => {}) { @@ -1249,11 +1245,11 @@ class Encore { * ``` * * Supported options: - * * {boolean} useJsx (default=false) + * - {boolean} useJsx (default=false) * Configure Babel to use the preset "@vue/babel-preset-jsx", * in order to enable JSX usage in Vue components. * - * @param {function} vueLoaderOptionsCallback + * @param {Function} vueLoaderOptionsCallback * @param {object} encoreOptions * @returns {Encore} */ @@ -1280,7 +1276,7 @@ class Encore { * ``` * * @param {boolean} enabled - * @param {function} notifierPluginOptionsCallback + * @param {Function} notifierPluginOptionsCallback * @returns {Encore} */ enableBuildNotifications(enabled = true, notifierPluginOptionsCallback = () => {}) { @@ -1305,7 +1301,7 @@ class Encore { * }); * ``` * - * @param {function} callback + * @param {Function} callback * @returns {Encore} */ enableHandlebarsLoader(callback = () => {}) { @@ -1329,6 +1325,7 @@ class Encore { * * Internally, this disables the mini-css-extract-plugin * and uses the style-loader instead. + * * @param {boolean} disabled * @returns {Encore} */ @@ -1351,7 +1348,7 @@ class Encore { * }); * ``` * - * @param {function} callback + * @param {Function} callback * @returns {Encore} */ configureStyleLoader(callback) { @@ -1438,7 +1435,7 @@ class Encore { * ``` * * @param {object} options - * @param {string|object|function} ruleCallback + * @param {string|object|Function} ruleCallback * @returns {Encore} */ configureImageRule(options = {}, ruleCallback = (rule) => {}) { @@ -1455,7 +1452,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) => {}) { @@ -1479,8 +1476,8 @@ class Encore { * ``` * * @param {string} name - * @param {function} callback - * @return {Encore} + * @param {Function} callback + * @returns {Encore} */ configureLoaderRule(name, callback) { webpackConfig.configureLoaderRule(name, callback); @@ -1502,7 +1499,7 @@ class Encore { * ``` * * @param {Array} paths Paths that should be cleaned, relative to the "root" option - * @param {function} cleanWebpackPluginOptionsCallback + * @param {Function} cleanWebpackPluginOptionsCallback * @returns {Encore} */ cleanupOutputBeforeBuild(paths = ['**/*'], cleanWebpackPluginOptionsCallback = () => {}) { @@ -1589,7 +1586,7 @@ class Encore { * * @param {(function(Encore): boolean) | boolean} condition * @param {function(Encore): void} callback - * @return {Encore} + * @returns {Encore} */ when(condition, callback) { if (typeof condition === 'function' && condition(this) || typeof condition === 'boolean' && condition) { @@ -1712,6 +1709,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 index 7d11c6b23..27b46c4b3 100644 --- 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 @@ -316,8 +316,8 @@ class WebpackConfig { /** * Provide a has of entries at once, as an alternative to calling `addEntry` several times. * - * @param {Object.} entries - * @returns {Void} + * @param {Record} entries + * @returns {void} */ addEntries(entries = {}) { if (typeof entries !== 'object') { diff --git a/lib/config-generator.js b/lib/config-generator.js index 6592b8bd3..0dc50a946 100644 --- a/lib/config-generator.js +++ b/lib/config-generator.js @@ -628,8 +628,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 index afa58cacc..9f79122d6 100644 --- 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 index 9752d3b39..ac2d49747 100644 --- 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 index 3efa815a2..f2c4a17fb 100644 --- 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 = { @@ -111,7 +111,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 index b41cdd3e2..de15601e9 100644 --- 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 index 6d1c0c860..9bfbfd5c9 100644 --- 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/handlebars.js b/lib/loaders/handlebars.js index bfbe20105..8126d9727 100644 --- 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 index f49fbd90d..ed1604df8 100644 --- 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 index 72fe28295..17a7a2f18 100644 --- 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 index 3029e6dec..605966c94 100644 --- 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 index 2fd63dc7e..49b40f5e2 100644 --- 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 index 68b480f56..52592a9e6 100644 --- 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 index ca11717fe..61d63c000 100644 --- 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 index 981a7a6c0..3fb586ef0 100644 --- 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 index 651a4f1cd..c8061f794 100644 --- 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 index 0801617b0..1bc2bb28a 100644 --- 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 index 902a3034f..df2584087 100644 --- 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({ diff --git a/lib/plugins/forked-ts-types.js b/lib/plugins/forked-ts-types.js index 7930bc9ab..f7d171497 100644 --- a/lib/plugins/forked-ts-types.js +++ b/lib/plugins/forked-ts-types.js @@ -16,7 +16,7 @@ const applyOptionsCallback = require('../utils/apply-options-callback'); /** * @param {WebpackConfig} webpackConfig - * @return {void} + * @returns {void} */ module.exports = function(webpackConfig) { const config = {}; diff --git a/lib/plugins/friendly-errors.js b/lib/plugins/friendly-errors.js index a3b374add..38aec0d63 100644 --- a/lib/plugins/friendly-errors.js +++ b/lib/plugins/friendly-errors.js @@ -21,7 +21,7 @@ const applyOptionsCallback = require('../utils/apply-options-callback'); /** * @param {WebpackConfig} webpackConfig - * @return {FriendlyErrorsWebpackPlugin} + * @returns {FriendlyErrorsWebpackPlugin} */ module.exports = function(webpackConfig) { const friendlyErrorsPluginOptions = { diff --git a/lib/plugins/manifest.js b/lib/plugins/manifest.js index 3cc70cbee..56ae024b6 100644 --- a/lib/plugins/manifest.js +++ b/lib/plugins/manifest.js @@ -19,7 +19,7 @@ const manifestKeyPrefixHelper = require('../utils/manifest-key-prefix-helper'); /** * @param {Array} plugins * @param {WebpackConfig} webpackConfig - * @return {void} + * @returns {void} */ module.exports = function(plugins, webpackConfig) { let manifestPluginOptions = { diff --git a/lib/plugins/mini-css-extract.js b/lib/plugins/mini-css-extract.js index 67c44f6d1..75a3e62a1 100644 --- a/lib/plugins/mini-css-extract.js +++ b/lib/plugins/mini-css-extract.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) { // Don't add the plugin if CSS extraction is disabled diff --git a/lib/plugins/notifier.js b/lib/plugins/notifier.js index 63afc3d92..92f259529 100644 --- a/lib/plugins/notifier.js +++ b/lib/plugins/notifier.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) { if (!webpackConfig.useWebpackNotifier) { diff --git a/lib/plugins/optimize-css-assets.js b/lib/plugins/optimize-css-assets.js index 9bbc03690..586fabe4a 100644 --- a/lib/plugins/optimize-css-assets.js +++ b/lib/plugins/optimize-css-assets.js @@ -15,7 +15,7 @@ const applyOptionsCallback = require('../utils/apply-options-callback'); /** * @param {WebpackConfig} webpackConfig - * @return {object} + * @returns {object} */ module.exports = function(webpackConfig) { const minimizerPluginOptions = {}; diff --git a/lib/plugins/terser.js b/lib/plugins/terser.js index 36bac5262..536d37244 100644 --- a/lib/plugins/terser.js +++ b/lib/plugins/terser.js @@ -15,7 +15,7 @@ const applyOptionsCallback = require('../utils/apply-options-callback'); /** * @param {WebpackConfig} webpackConfig - * @return {object} + * @returns {object} */ module.exports = function(webpackConfig) { const terserPluginOptions = { diff --git a/lib/plugins/variable-provider.js b/lib/plugins/variable-provider.js index bf30432b7..1f9ae798c 100644 --- a/lib/plugins/variable-provider.js +++ b/lib/plugins/variable-provider.js @@ -16,7 +16,7 @@ const PluginPriorities = require('./plugin-priorities'); /** * @param {Array} plugins * @param {WebpackConfig} webpackConfig - * @return {void} + * @returns {void} */ module.exports = function(plugins, webpackConfig) { if (Object.keys(webpackConfig.providedVariables).length > 0) { diff --git a/lib/plugins/vue.js b/lib/plugins/vue.js index 1f264d83e..8934dd305 100644 --- a/lib/plugins/vue.js +++ b/lib/plugins/vue.js @@ -15,7 +15,7 @@ const PluginPriorities = require('./plugin-priorities'); /** * @param {Array} plugins * @param {WebpackConfig} webpackConfig - * @return {void} + * @returns {void} */ module.exports = function(plugins, webpackConfig) { if (!webpackConfig.useVueLoader) { diff --git a/lib/utils/get-vue-version.js b/lib/utils/get-vue-version.js index 084eec539..a756ac22a 100644 --- a/lib/utils/get-vue-version.js +++ b/lib/utils/get-vue-version.js @@ -16,7 +16,7 @@ const logger = require('../logger'); /** * @param {WebpackConfig} webpackConfig - * @return {int|string|null} + * @returns {number|string|null} */ module.exports = function(webpackConfig) { if (webpackConfig.vueOptions.version !== null) { diff --git a/lib/utils/manifest-key-prefix-helper.js b/lib/utils/manifest-key-prefix-helper.js index e7b2b027c..6d65ec294 100644 --- a/lib/utils/manifest-key-prefix-helper.js +++ b/lib/utils/manifest-key-prefix-helper.js @@ -15,7 +15,7 @@ const WebpackConfig = require('../WebpackConfig'); //eslint-disable-line no-unus * Helper for determining the manifest.json key prefix. * * @param {WebpackConfig} webpackConfig - * @return {string} + * @returns {string} */ module.exports = function(webpackConfig) { let manifestPrefix = webpackConfig.manifestKeyPrefix; diff --git a/lib/utils/package-up.js b/lib/utils/package-up.js index b641efb53..06097c01d 100644 --- a/lib/utils/package-up.js +++ b/lib/utils/package-up.js @@ -31,7 +31,7 @@ function toPath(urlOrPath) { * Inlined and simplified version of the package "find-up-simple" (ESM only). * * @param {string} name The name of the file to find - * @param {Object} options + * @param {object} options * @param {string} options.cwd The directory to start searching from. * @returns {string|undefined} The path to the file found or undefined if not found. */ diff --git a/lib/utils/pretty-error.js b/lib/utils/pretty-error.js index d8b9674b3..8000f0e5a 100644 --- a/lib/utils/pretty-error.js +++ b/lib/utils/pretty-error.js @@ -15,7 +15,7 @@ const PrettyError = require('pretty-error'); * Render a pretty version of the given error. * * Supported options: - * * {function} skipTrace + * - {function} skipTrace * An optional callback that defines whether * or not each line of the eventual stacktrace * should be kept. First argument is the content @@ -23,7 +23,6 @@ const PrettyError = require('pretty-error'); * * @param {*} error * @param {object} options - * * @returns {void} */ module.exports = function(error, options = {}) { diff --git a/lib/utils/regexp-escaper.js b/lib/utils/regexp-escaper.js index 64fe66782..d791c367e 100644 --- a/lib/utils/regexp-escaper.js +++ b/lib/utils/regexp-escaper.js @@ -15,7 +15,7 @@ * See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#Escaping * * @param {string} str - * @return {string} + * @returns {string} */ module.exports = function regexpEscaper(str) { return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); diff --git a/lib/utils/string-escaper.js b/lib/utils/string-escaper.js index e5b627076..465aa99b6 100644 --- a/lib/utils/string-escaper.js +++ b/lib/utils/string-escaper.js @@ -17,7 +17,7 @@ * it needs to escape the Window path slashes). * * @param {string} str - * @return {string} + * @returns {string} */ module.exports = function stringEscaper(str) { return str.replace(/\\/g, '\\\\').replace(/\x27/g, '\\\x27'); diff --git a/package.json b/package.json index a97714216..b249a4e02 100755 --- a/package.json +++ b/package.json @@ -68,6 +68,7 @@ "eslint": "^8.0.0", "eslint-plugin-header": "^3.0.0", "eslint-plugin-import": "^2.26.0", + "eslint-plugin-jsdoc": "^50.2.2", "eslint-plugin-node": "^11.1.0", "file-loader": "^6.0.0", "fork-ts-checker-webpack-plugin": "^7.0.0 || ^8.0.0 || ^9.0.0", diff --git a/test/helpers/assert.js b/test/helpers/assert.js index 37022235d..7f423f113 100644 --- a/test/helpers/assert.js +++ b/test/helpers/assert.js @@ -52,7 +52,7 @@ const getMatchedFilename = function(targetDirectory, filenameRegex) { * Returns a regex to use to match this filename * * @param {string} filename Filename with possible [hash:8] wildcard - * @return {RegExp} + * @returns {RegExp} */ const convertFilenameToMatcher = function(filename) { const hashMatch = filename.match(/\[hash:(\d+)\]/); @@ -71,7 +71,7 @@ const convertFilenameToMatcher = function(filename) { class Assert { /** - * @param {WebpackConfig} webpackConfig + * @param {import('../../lib/WebpackConfig')} webpackConfig */ constructor(webpackConfig) { this.webpackConfig = webpackConfig; @@ -176,11 +176,11 @@ class Assert { /** * - * @param {Browser} browser + * @param {import('zombie')} browser * @param {Array} expectedResourcePaths Array of expected resources, but just * their short filenames - e.g. main.css * (i.e. without the public path) - * @return {void} + * @returns {void} */ assertResourcesLoadedCorrectly(browser, expectedResourcePaths) { const actualResources = []; diff --git a/test/helpers/setup.js b/test/helpers/setup.js index 3c84fa1de..dbeb15cbf 100644 --- a/test/helpers/setup.js +++ b/test/helpers/setup.js @@ -145,7 +145,7 @@ function stopAllServers() { * @param {string} webRootDir Directory path (e.g. /path/to/public) where the web server should be rooted * @param {Array} scriptSrcs Used to create