Merge pull request #7236 from webpack/lint/more-strict-jsdoc

More strict linting of jsdocs

.eslintrc.js

@@ -29,7 +29,20 @@ module.exports = {
 		"no-loop-func": "warn",
 		"indent": "off",
 		"no-console": "off",
-		"valid-jsdoc": "error",
+		"valid-jsdoc": ["error", {
+			"prefer": {
+				"return": "returns",
+				"memberof": "DONTUSE",
+				"class": "DONTUSE",
+				"inheritdoc": "DONTUSE",
+				"description": "DONTUSE",
+				"readonly": "DONTUSE"
+			},
+			"preferType": {
+				"*": "any"
+			},
+			"requireReturnType": true
+		}],
 		"node/no-unsupported-features": "error",
 		"node/no-deprecated-api": "error",
 		"node/no-missing-import": "error",

declarations.d.ts

@@ -114,3 +114,5 @@ declare const WebAssembly;
 declare const importScripts;
 declare const $crossOriginLoading$;
 declare const chunkId;
+
+type TODO = any;

lib/ChunkGroup.js

@@ -12,7 +12,7 @@ const compareLocations = require("./compareLocations");
 /** @typedef {import("./ModuleReason")} ModuleReason */
 
 /** @typedef {{id: number}} HasId */
-/** @typedef {{module: Module, loc: any, request: string}} OriginRecord */
+/** @typedef {{module: Module, loc: TODO, request: string}} OriginRecord */
 /** @typedef {string|{name: string}} ChunkGroupOptions */
 
 let debugId = 5000;
@@ -112,7 +112,6 @@ class ChunkGroup {
 
 	/**
 	 * get a uniqueId for ChunkGroup, made up of its member Chunk debugId's
-	 * @readonly
 	 * @returns {string} a unique concatenation of chunk debugId's
 	 */
 	get debugId() {
@@ -121,7 +120,6 @@ class ChunkGroup {
 
 	/**
 	 * get a unique id for ChunkGroup, made up of its member Chunk id's
-	 * @readonly
 	 * @returns {string} a unique concatenation of chunk ids
 	 */
 	get id() {
@@ -182,7 +180,6 @@ class ChunkGroup {
 	}
 
 	/**
-	 * @description
 	 * @param {Chunk} oldChunk chunk to be replaced
 	 * @param {Chunk} newChunk New chunkt that will be replaced
 	 * @returns {boolean} rerturns true for

lib/ChunkTemplate.js

@@ -16,9 +16,9 @@ const { Tapable, SyncWaterfallHook, SyncHook } = require("tapable");
  * @property {Chunk} chunk the chunk used to render
  * @property {Hash} hash
  * @property {string} fullHash
- * @property {any} outputOptions
+ * @property {TODO} outputOptions
  * @property {{javascript: ModuleTemplate, webassembly: ModuleTemplate}} moduleTemplates
- * @property {Map} dependencyTemplates
+ * @property {Map<TODO, TODO>} dependencyTemplates
  */
 
 module.exports = class ChunkTemplate extends Tapable {
@@ -48,7 +48,7 @@ module.exports = class ChunkTemplate extends Tapable {
 	/**
 	 *
 	 * @param {RenderManifestOptions} options render manifest options
-	 * @returns {any[]} returns render manifest
+	 * @returns {TODO[]} returns render manifest
 	 */
 	getRenderManifest(options) {
 		const result = [];

lib/Entrypoint.js

@@ -27,7 +27,7 @@ class Entrypoint extends ChunkGroup {
 
 	/**
 	 * isInitial will always return true for Entrypoint ChunkGroup.
-	 * @return {true} returns true as all entrypoints are initial ChunkGroups
+	 * @returns {true} returns true as all entrypoints are initial ChunkGroups
 	 */
 	isInitial() {
 		return true;
@@ -36,7 +36,7 @@ class Entrypoint extends ChunkGroup {
 	/**
 	 * Sets the runtimeChunk for an entrypoint.
 	 * @param {Chunk} chunk the chunk being set as the runtime chunk.
-	 * @return {void}
+	 * @returns {void}
 	 */
 	setRuntimeChunk(chunk) {
 		this.runtimeChunk = chunk;
@@ -44,7 +44,7 @@ class Entrypoint extends ChunkGroup {
 
 	/**
 	 * Fetches the chunk reference containing the webpack bootstrap code
-	 * @return {Chunk} returns the runtime chunk or first chunk in `this.chunks`
+	 * @returns {Chunk} returns the runtime chunk or first chunk in `this.chunks`
 	 */
 	getRuntimeChunk() {
 		return this.runtimeChunk || this.chunks[0];

lib/EvalSourceMapDevToolModuleTemplatePlugin.js

@@ -40,7 +40,7 @@ class EvalSourceMapDevToolModuleTemplatePlugin {
 					return source;
 				}
 
-				/** @type {{ [key: string]: any; }} */
+				/** @type {{ [key: string]: TODO; }} */
 				let sourceMap;
 				let content;
 				if (source.sourceAndMap) {

lib/Generator.js

@@ -19,7 +19,7 @@ class Generator {
 	/**
 	 * @abstract
 	 * @param {Module} module module for which the code should be generated
-	 * @param {Map<Function, any>} dependencyTemplates mapping from dependencies to templates
+	 * @param {Map<Function, TODO>} dependencyTemplates mapping from dependencies to templates
 	 * @param {RuntimeTemplate} runtimeTemplate the runtime template
 	 * @param {string} type which kind of code should be generated
 	 * @returns {Source} generated code

lib/HotModuleReplacement.runtime.js

@@ -362,7 +362,7 @@ module.exports = function() {
 		for (var id in hotUpdate) {
 			if (Object.prototype.hasOwnProperty.call(hotUpdate, id)) {
 				moduleId = toModuleId(id);
-				/** @type {any} */
+				/** @type {TODO} */
 				var result;
 				if (hotUpdate[id]) {
 					result = getAffectedStuff(moduleId);

lib/MainTemplate.js

@@ -29,9 +29,9 @@ const Template = require("./Template");
  * @property {Chunk} chunk the chunk used to render
  * @property {Hash} hash
  * @property {string} fullHash
- * @property {any} outputOptions
+ * @property {TODO} outputOptions
  * @property {{javascript: ModuleTemplate, webassembly: ModuleTemplate}} moduleTemplates
- * @property {Map} dependencyTemplates
+ * @property {Map<TODO, TODO>} dependencyTemplates
  */
 
 // require function shortcuts:
@@ -53,14 +53,14 @@ const Template = require("./Template");
 module.exports = class MainTemplate extends Tapable {
 	/**
 	 *
-	 * @param {any=} outputOptions output options for the MainTemplate
+	 * @param {TODO=} outputOptions output options for the MainTemplate
 	 */
 	constructor(outputOptions) {
 		super();
-		/** @type {any?} */
+		/** @type {TODO?} */
 		this.outputOptions = outputOptions || {};
 		this.hooks = {
-			/** @type {SyncWaterfallHook<any[], RenderManifestOptions>} */
+			/** @type {SyncWaterfallHook<TODO[], RenderManifestOptions>} */
 			renderManifest: new SyncWaterfallHook(["result", "options"]),
 			modules: new SyncWaterfallHook([
 				"modules",
@@ -322,7 +322,7 @@ module.exports = class MainTemplate extends Tapable {
 	/**
 	 *
 	 * @param {RenderManifestOptions} options render manifest options
-	 * @returns {any[]} returns render manifest
+	 * @returns {TODO[]} returns render manifest
 	 */
 	getRenderManifest(options) {
 		const result = [];
@@ -337,8 +337,8 @@ module.exports = class MainTemplate extends Tapable {
 	 * @param {string} hash hash to be used for render call
 	 * @param {Chunk} chunk Chunk instance
 	 * @param {ModuleTemplate} moduleTemplate ModuleTemplate instance for render
-	 * @param {any} dependencyTemplates DependencyTemplate[]s
+	 * @param {TODO} dependencyTemplates DependencyTemplate[]s
-	 * @return {ConcatSource} the newly generated source from rendering
+	 * @returns {ConcatSource} the newly generated source from rendering
 	 */
 	render(hash, chunk, moduleTemplate, dependencyTemplates) {
 		const buf = [];
@@ -390,7 +390,7 @@ module.exports = class MainTemplate extends Tapable {
 	 * @param {string} hash hash for render fn
 	 * @param {Chunk} chunk Chunk instance for require
 	 * @param {(number|string)=} varModuleId module id
-	 * @return {any} the moduleRequire hook call return signature
+	 * @returns {TODO} the moduleRequire hook call return signature
 	 */
 	renderRequireFunctionForModule(hash, chunk, varModuleId) {
 		return this.hooks.moduleRequire.call(
@@ -407,7 +407,7 @@ module.exports = class MainTemplate extends Tapable {
 	 * @param {Chunk} chunk Chunk instance for require add fn
 	 * @param {(string|number)=} varModuleId module id
 	 * @param {Module} varModule Module instance
-	 * @return {any} renderAddModule call
+	 * @returns {TODO} renderAddModule call
 	 */
 	renderAddModule(hash, chunk, varModuleId, varModule) {
 		return this.hooks.addModule.call(
@@ -423,7 +423,7 @@ module.exports = class MainTemplate extends Tapable {
 	 *
 	 * @param {string} hash string hash
 	 * @param {number} length length
-	 * @return {any} call hook return
+	 * @returns {string} call hook return
 	 */
 	renderCurrentHashCode(hash, length) {
 		length = length || Infinity;
@@ -436,7 +436,7 @@ module.exports = class MainTemplate extends Tapable {
 	/**
 	 *
 	 * @param {object} options get public path options
-	 * @return {any} hook call
+	 * @returns {string} hook call
 	 */
 	getPublicPath(options) {
 		return this.hooks.assetPath.call(

lib/NormalModule.js

@@ -64,7 +64,7 @@ class NonErrorEmittedError extends WebpackError {
 
 /**
  * @typedef {Object} CachedSourceEntry
- * @property {any} source the generated source
+ * @property {TODO} source the generated source
  * @property {string} hash the hash value
  */
 

lib/Parser.js

@@ -580,9 +580,9 @@ class Parser extends Tapable {
 
 		/**
 		 * @param {string} kind "cooked" | "raw"
-		 * @param {any[]} quasis quasis
+		 * @param {TODO[]} quasis quasis
-		 * @param {any[]} expressions expressions
+		 * @param {TODO[]} expressions expressions
-		 * @return {BasicEvaluatedExpression[]} Simplified template
+		 * @returns {BasicEvaluatedExpression[]} Simplified template
 		 */
 		const getSimplifiedTemplateResult = (kind, quasis, expressions) => {
 			const parts = [];

lib/RuntimeTemplate.js

@@ -20,7 +20,7 @@ module.exports = class RuntimeTemplate {
 	 * @param {string=} options.chunkReason reason information of the chunk
 	 * @param {string=} options.message additional message
 	 * @param {string=} options.exportName name of the export
-	 * @return {string} comment
+	 * @returns {string} comment
 	 */
 	comment({ request, chunkName, chunkReason, message, exportName }) {
 		let content;

lib/Template.js

@@ -34,7 +34,7 @@ const MATCH_PADDED_HYPHENS_REPLACE_REGEX = /^-|-$/g;
 /**
  * @param {HasId} a first id object to be sorted
  * @param {HasId} b second id object to be sorted against
- * @return {-1|0|1} the sort value
+ * @returns {-1|0|1} the sort value
  */
 const stringifyIdSortPredicate = (a, b) => {
 	var aId = a.id + "";
@@ -48,7 +48,7 @@ const stringifyIdSortPredicate = (a, b) => {
 //https://github.com/Microsoft/TypeScript/issues/23375
 /**
  * @param {HasId} module the module to compare against
- * @return {boolean} return true if module.id is equal to type "number"
+ * @returns {boolean} return true if module.id is equal to type "number"
  */
 const moduleIdIsNumber = module => {
 	return typeof module.id === "number";
@@ -58,7 +58,7 @@ class Template {
 	/**
 	 *
 	 * @param {Function} fn - a runtime function (.runtime.js) "template"
-	 * @return {string} the updated and normalized function string
+	 * @returns {string} the updated and normalized function string
 	 */
 	static getFunctionContent(fn) {
 		return fn
@@ -69,7 +69,7 @@ class Template {
 	}
 	/**
 	 * @param {string} str the string converted to identifier
-	 * @return {string} created identifier
+	 * @returns {string} created identifier
 	 */
 	static toIdentifier(str) {
 		if (typeof str !== "string") return "";
@@ -80,7 +80,7 @@ class Template {
 	/**
 	 *
 	 * @param {string} str string to be converted to commented in bundle code
-	 * @return {string} returns a commented version of string
+	 * @returns {string} returns a commented version of string
 	 */
 	static toComment(str) {
 		if (!str) return "";
@@ -90,7 +90,7 @@ class Template {
 	/**
 	 *
 	 * @param {string} str string to be converted to "normal comment"
-	 * @return {string} returns a commented version of string
+	 * @returns {string} returns a commented version of string
 	 */
 	static toNormalComment(str) {
 		if (!str) return "";
@@ -99,7 +99,7 @@ class Template {
 
 	/**
 	 * @param {string} str string path to be normalized
-	 * @return {string} normalized bundle-safe path
+	 * @returns {string} normalized bundle-safe path
 	 */
 	static toPath(str) {
 		if (typeof str !== "string") return "";
@@ -112,7 +112,7 @@ class Template {
 	/**
 	 *
 	 * @param {number} n number to convert to ident
-	 * @return {string} returns single character ident
+	 * @returns {string} returns single character ident
 	 */
 	static numberToIdentifer(n) {
 		// lower case
@@ -134,7 +134,7 @@ class Template {
 	/**
 	 *
 	 * @param {string | string[]} str string to convert to identity
-	 * @return {string} converted identity
+	 * @returns {string} converted identity
 	 */
 	static indent(str) {
 		if (Array.isArray(str)) {
@@ -151,7 +151,7 @@ class Template {
 	 *
 	 * @param {string|string[]} str string to create prefix for
 	 * @param {string} prefix prefix to compose
-	 * @return {string} returns new prefix string
+	 * @returns {string} returns new prefix string
 	 */
 	static prefix(str, prefix) {
 		if (Array.isArray(str)) {
@@ -166,7 +166,7 @@ class Template {
 	/**
 	 *
 	 * @param {string|string[]} str string or string collection
-	 * @return {string} returns a single string from array
+	 * @returns {string} returns a single string from array
 	 */
 	static asString(str) {
 		if (Array.isArray(str)) {
@@ -178,7 +178,7 @@ class Template {
 	/**
 	 *
 	 * @param {HasId[]} modules - a collection of modules to get array bounds for
-	 * @return {[number, number] | false} returns the upper and lower array bounds
+	 * @returns {[number, number] | false} returns the upper and lower array bounds
 	 * or false if not every module has a number based id
 	 */
 	static getModulesArrayBounds(modules) {
@@ -210,9 +210,9 @@ class Template {
 	 * @param {Chunk} chunk chunk whose modules will be rendered
 	 * @param {ModuleFilterPredicate} filterFn function used to filter modules from chunk to render
 	 * @param {ModuleTemplate} moduleTemplate ModuleTemplate instance used to render modules
-	 * @param {any | any[]} dependencyTemplates templates needed for each module to render dependencies
+	 * @param {TODO | TODO[]} dependencyTemplates templates needed for each module to render dependencies
 	 * @param {string=} prefix applying prefix strings
-	 * @return {ConcatSource} rendered chunk modules in a Source object
+	 * @returns {ConcatSource} rendered chunk modules in a Source object
 	 */
 	static renderChunkModules(
 		chunk,

lib/debug/ProfilingPlugin.js

@@ -320,7 +320,8 @@ const makeInterceptorFor = (instance, tracer) => hookName => ({
 	}
 });
 
-/** @typedef {(...args: any[]) => void | Promise<any>} PluginFunction */
+// TODO improve typing
+/** @typedef {(...args: TODO[]) => void | Promise<TODO>} PluginFunction */
 
 /**
  * @param {string} hookName Name of the hook to profile.
@@ -329,7 +330,7 @@ const makeInterceptorFor = (instance, tracer) => hookName => ({
  * @param {string} options.name Plugin name
  * @param {string} options.type Plugin type (sync | async | promise)
  * @param {PluginFunction} options.fn Plugin function
- * @returns {*} Chainable hooked function.
+ * @returns {PluginFunction} Chainable hooked function.
  */
 const makeNewProfiledTapFn = (hookName, tracer, { name, type, fn }) => {
 	const defaultCategory = ["blink.user_timing"];

lib/dependencies/ContextDependencyHelpers.js

@@ -9,7 +9,7 @@ const ContextDependencyHelpers = exports;
 /**
  * Escapes regular expression metacharacters
  * @param {string} str String to quote
- * @return {string} Escaped string
+ * @returns {string} Escaped string
  */
 const quotemeta = str => {
 	return str.replace(/[-[\]\\/{}()*+?.^$|]/g, "\\$&");

lib/util/Queue.js

@@ -16,7 +16,7 @@ class Queue {
 
 	/**
 	 * Returns the number of elements in this queue.
-	 * @return {number} The number of elements in this queue.
+	 * @returns {number} The number of elements in this queue.
 	 */
 	get length() {
 		return this.set.size;
@@ -25,7 +25,7 @@ class Queue {
 	/**
 	 * Appends the specified element to this queue.
 	 * @param {T} item The element to add.
-	 * @return {void}
+	 * @returns {void}
 	 */
 	enqueue(item) {
 		this.set.add(item);
@@ -33,7 +33,7 @@ class Queue {
 
 	/**
 	 * Retrieves and removes the head of this queue.
-	 * @return {T | undefined} The head of the queue of `undefined` if this queue is empty.
+	 * @returns {T | undefined} The head of the queue of `undefined` if this queue is empty.
 	 */
 	dequeue() {
 		const result = this.iterator.next();

lib/util/SetHelpers.js

@@ -3,7 +3,7 @@
 /**
  * intersect creates Set containing the intersection of elements between all sets
  * @param {Set[]} sets an array of sets being checked for shared elements
- * @returns {Set} returns a new Set containing the intersecting items
+ * @returns {Set<TODO>} returns a new Set containing the intersecting items
  */
 function intersect(sets) {
 	if (sets.length === 0) return new Set();
@@ -32,8 +32,8 @@ function intersect(sets) {
 
 /**
  * Checks if a set is the subset of another set
- * @param {Set} bigSet a Set which contains the original elements to compare against
+ * @param {Set<TODO>} bigSet a Set which contains the original elements to compare against
- * @param {Set} smallSet the set whos elements might be contained inside of bigSet
+ * @param {Set<TODO>} smallSet the set whos elements might be contained inside of bigSet
  * @returns {boolean} returns true if smallSet contains all elements inside of the bigSet
  */
 function isSubset(bigSet, smallSet) {

lib/util/SortableSet.js

@@ -12,7 +12,7 @@ class SortableSet extends Set {
 	}
 
 	/**
-	 * @param {any} value - value to add to set
+	 * @param {TODO} value - value to add to set
 	 * @returns {this} - returns itself
 	 */
 	add(value) {
@@ -35,7 +35,7 @@ class SortableSet extends Set {
 		return super.clear();
 	}
 
-	sortWith(/** @type {(a: any, b: any) => number} */ sortFn) {
+	sortWith(/** @type {(a: TODO, b: TODO) => number} */ sortFn) {
 		if (this.size <= 1 || sortFn === this._lastActiveSortFn) {
 			// already sorted - nothing to do
 			return;
@@ -59,7 +59,7 @@ class SortableSet extends Set {
 
 	/**
 	 * @param {Function} fn - function to calculate value
-	 * @returns {any} - returns result of fn(this), cached until set changes
+	 * @returns {TODO} - returns result of fn(this), cached until set changes
 	 */
 	getFromCache(fn) {
 		if (this._cache === undefined) {
@@ -77,7 +77,7 @@ class SortableSet extends Set {
 
 	/**
 	 * @param {Function} fn - function to calculate value
-	 * @returns {any} - returns result of fn(this), cached until set changes
+	 * @returns {TODO} - returns result of fn(this), cached until set changes
 	 */
 	getFromUnorderedCache(fn) {
 		if (this._cacheOrderIndependent === undefined) {

lib/util/StackedSetMap.js

@@ -92,7 +92,7 @@ class StackedSetMap {
 		return Array.from(
 			this.map.entries(),
 			pair =>
-				/** @type {[any, any]} */ (pair[1] === UNDEFINED_MARKER
+				/** @type {[TODO, TODO]} */ (pair[1] === UNDEFINED_MARKER
 					? [pair[0], undefined]
 					: pair)
 		);

lib/util/identifier.js

@@ -9,7 +9,7 @@ const path = require("path");
 /**
  *
  * @param {string} maybeAbsolutePath path to check
- * @return {boolean} returns true if path is "Absolute Path"-like
+ * @returns {boolean} returns true if path is "Absolute Path"-like
  */
 const looksLikeAbsolutePath = maybeAbsolutePath => {
 	return /^(?:[a-z]:\\|\/)/i.test(maybeAbsolutePath);
@@ -18,7 +18,7 @@ const looksLikeAbsolutePath = maybeAbsolutePath => {
 /**
  *
  * @param {string} p path to normalize
- * @return {string} normalized version of path
+ * @returns {string} normalized version of path
  */
 const normalizePathSeparator = p => p.replace(/\\/g, "/");
 
@@ -26,7 +26,7 @@ const normalizePathSeparator = p => p.replace(/\\/g, "/");
  *
  * @param {string} context context for relative path
  * @param {string} identifier identifier for path
- * @return {string} a converted relative path
+ * @returns {string} a converted relative path
  */
 const _makePathsRelative = (context, identifier) => {
 	return identifier
@@ -45,7 +45,7 @@ const _makePathsRelative = (context, identifier) => {
  * @param {string} context context used to create relative path
  * @param {string} identifier identifier used to create relative path
  * @param {MakeRelativePathsCache=} cache the cache object being set
- * @return {string} the returned relative path
+ * @returns {string} the returned relative path
  */
 exports.makePathsRelative = (context, identifier, cache) => {
 	if (!cache) return _makePathsRelative(context, identifier);

lib/util/objectToMap.js

@@ -3,7 +3,7 @@
  * into an ES6 map
  *
  * @param {object} obj - any object type that works with Object.keys()
- * @returns {Map} an ES6 Map of KV pairs
+ * @returns {Map<TODO, TODO>} an ES6 Map of KV pairs
  */
 module.exports = function objectToMap(obj) {
 	return new Map(

lib/wasm/WebAssemblyGenerator.js

@@ -179,7 +179,7 @@ const rewriteImportedGlobals = state => bin => {
  * @param {Object} state transformation state
  * @param {t.IndexLiteral} state.startAtFuncIndex index of the start function
  * @param {t.ModuleImport[]} state.importedGlobals list of imported globals
- * @param {*} state.funcSectionMetadata ??
+ * @param {TODO} state.funcSectionMetadata ??
  * @param {t.IndexLiteral} state.nextFuncIndex index of the next function
  * @param {t.IndexLiteral} state.nextTypeIndex index of the next type
  * @returns {ArrayBufferTransform} transform