Skip to content

Commit eda273d

Browse files
sokrasokra
authored
Merge pull request webpack#7236 from webpack/lint/more-strict-jsdoc
More strict linting of jsdocs
2 parents 236bbcf + f2ad440 commit eda273d

22 files changed

+78
-65
lines changed

‎.eslintrc.js

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,20 @@ module.exports = {
2929
"no-loop-func": "warn",
3030
"indent": "off",
3131
"no-console": "off",
32-
"valid-jsdoc": "error",
32+
"valid-jsdoc": ["error", {
33+
"prefer": {
34+
"return": "returns",
35+
"memberof": "DONTUSE",
36+
"class": "DONTUSE",
37+
"inheritdoc": "DONTUSE",
38+
"description": "DONTUSE",
39+
"readonly": "DONTUSE"
40+
},
41+
"preferType": {
42+
"*": "any"
43+
},
44+
"requireReturnType": true
45+
}],
3346
"node/no-unsupported-features": "error",
3447
"node/no-deprecated-api": "error",
3548
"node/no-missing-import": "error",

‎declarations.d.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,3 +114,5 @@ declare const WebAssembly;
114114
declare const importScripts;
115115
declare const $crossOriginLoading$;
116116
declare const chunkId;
117+
118+
type TODO = any;

‎lib/ChunkGroup.js

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ const compareLocations = require("./compareLocations");
1212
/** @typedef {import("./ModuleReason")} ModuleReason */
1313

1414
/** @typedef {{id: number}} HasId */
15-
/** @typedef {{module: Module, loc: any, request: string}} OriginRecord */
15+
/** @typedef {{module: Module, loc: TODO, request: string}} OriginRecord */
1616
/** @typedef {string|{name: string}} ChunkGroupOptions */
1717

1818
let debugId = 5000;
@@ -112,7 +112,6 @@ class ChunkGroup {
112112

113113
/**
114114
* get a uniqueId for ChunkGroup, made up of its member Chunk debugId's
115-
* @readonly
116115
* @returns {string} a unique concatenation of chunk debugId's
117116
*/
118117
get debugId() {
@@ -121,7 +120,6 @@ class ChunkGroup {
121120

122121
/**
123122
* get a unique id for ChunkGroup, made up of its member Chunk id's
124-
* @readonly
125123
* @returns {string} a unique concatenation of chunk ids
126124
*/
127125
get id() {
@@ -182,7 +180,6 @@ class ChunkGroup {
182180
}
183181

184182
/**
185-
* @description
186183
* @param {Chunk} oldChunk chunk to be replaced
187184
* @param {Chunk} newChunk New chunkt that will be replaced
188185
* @returns {boolean} rerturns true for

‎lib/ChunkTemplate.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,9 @@ const { Tapable, SyncWaterfallHook, SyncHook } = require("tapable");
1616
* @property {Chunk} chunk the chunk used to render
1717
* @property {Hash} hash
1818
* @property {string} fullHash
19-
* @property {any} outputOptions
19+
* @property {TODO} outputOptions
2020
* @property {{javascript: ModuleTemplate, webassembly: ModuleTemplate}} moduleTemplates
21-
* @property {Map} dependencyTemplates
21+
* @property {Map<TODO, TODO>} dependencyTemplates
2222
*/
2323

2424
module.exports = class ChunkTemplate extends Tapable {
@@ -48,7 +48,7 @@ module.exports = class ChunkTemplate extends Tapable {
4848
/**
4949
*
5050
* @param {RenderManifestOptions} options render manifest options
51-
* @returns {any[]} returns render manifest
51+
* @returns {TODO[]} returns render manifest
5252
*/
5353
getRenderManifest(options) {
5454
const result = [];

‎lib/Entrypoint.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ class Entrypoint extends ChunkGroup {
2727

2828
/**
2929
* isInitial will always return true for Entrypoint ChunkGroup.
30-
* @return {true} returns true as all entrypoints are initial ChunkGroups
30+
* @returns {true} returns true as all entrypoints are initial ChunkGroups
3131
*/
3232
isInitial() {
3333
return true;
@@ -36,15 +36,15 @@ class Entrypoint extends ChunkGroup {
3636
/**
3737
* Sets the runtimeChunk for an entrypoint.
3838
* @param {Chunk} chunk the chunk being set as the runtime chunk.
39-
* @return {void}
39+
* @returns {void}
4040
*/
4141
setRuntimeChunk(chunk) {
4242
this.runtimeChunk = chunk;
4343
}
4444

4545
/**
4646
* Fetches the chunk reference containing the webpack bootstrap code
47-
* @return {Chunk} returns the runtime chunk or first chunk in `this.chunks`
47+
* @returns {Chunk} returns the runtime chunk or first chunk in `this.chunks`
4848
*/
4949
getRuntimeChunk() {
5050
return this.runtimeChunk || this.chunks[0];

‎lib/EvalSourceMapDevToolModuleTemplatePlugin.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ class EvalSourceMapDevToolModuleTemplatePlugin {
4040
return source;
4141
}
4242

43-
/** @type {{ [key: string]: any; }} */
43+
/** @type {{ [key: string]: TODO; }} */
4444
let sourceMap;
4545
let content;
4646
if (source.sourceAndMap) {

‎lib/Generator.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ class Generator {
1919
/**
2020
* @abstract
2121
* @param {Module} module module for which the code should be generated
22-
* @param {Map<Function, any>} dependencyTemplates mapping from dependencies to templates
22+
* @param {Map<Function, TODO>} dependencyTemplates mapping from dependencies to templates
2323
* @param {RuntimeTemplate} runtimeTemplate the runtime template
2424
* @param {string} type which kind of code should be generated
2525
* @returns {Source} generated code

‎lib/HotModuleReplacement.runtime.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -362,7 +362,7 @@ module.exports = function() {
362362
for (var id in hotUpdate) {
363363
if (Object.prototype.hasOwnProperty.call(hotUpdate, id)) {
364364
moduleId = toModuleId(id);
365-
/** @type {any} */
365+
/** @type {TODO} */
366366
var result;
367367
if (hotUpdate[id]) {
368368
result = getAffectedStuff(moduleId);

‎lib/MainTemplate.js

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ const Template = require("./Template");
2929
* @property {Chunk} chunk the chunk used to render
3030
* @property {Hash} hash
3131
* @property {string} fullHash
32-
* @property {any} outputOptions
32+
* @property {TODO} outputOptions
3333
* @property {{javascript: ModuleTemplate, webassembly: ModuleTemplate}} moduleTemplates
34-
* @property {Map} dependencyTemplates
34+
* @property {Map<TODO, TODO>} dependencyTemplates
3535
*/
3636

3737
// require function shortcuts:
@@ -53,14 +53,14 @@ const Template = require("./Template");
5353
module.exports = class MainTemplate extends Tapable {
5454
/**
5555
*
56-
* @param {any=} outputOptions output options for the MainTemplate
56+
* @param {TODO=} outputOptions output options for the MainTemplate
5757
*/
5858
constructor(outputOptions) {
5959
super();
60-
/** @type {any?} */
60+
/** @type {TODO?} */
6161
this.outputOptions = outputOptions || {};
6262
this.hooks = {
63-
/** @type {SyncWaterfallHook<any[], RenderManifestOptions>} */
63+
/** @type {SyncWaterfallHook<TODO[], RenderManifestOptions>} */
6464
renderManifest: new SyncWaterfallHook(["result", "options"]),
6565
modules: new SyncWaterfallHook([
6666
"modules",
@@ -322,7 +322,7 @@ module.exports = class MainTemplate extends Tapable {
322322
/**
323323
*
324324
* @param {RenderManifestOptions} options render manifest options
325-
* @returns {any[]} returns render manifest
325+
* @returns {TODO[]} returns render manifest
326326
*/
327327
getRenderManifest(options) {
328328
const result = [];
@@ -337,8 +337,8 @@ module.exports = class MainTemplate extends Tapable {
337337
* @param {string} hash hash to be used for render call
338338
* @param {Chunk} chunk Chunk instance
339339
* @param {ModuleTemplate} moduleTemplate ModuleTemplate instance for render
340-
* @param {any} dependencyTemplates DependencyTemplate[]s
341-
* @return {ConcatSource} the newly generated source from rendering
340+
* @param {TODO} dependencyTemplates DependencyTemplate[]s
341+
* @returns {ConcatSource} the newly generated source from rendering
342342
*/
343343
render(hash, chunk, moduleTemplate, dependencyTemplates) {
344344
const buf = [];
@@ -390,7 +390,7 @@ module.exports = class MainTemplate extends Tapable {
390390
* @param {string} hash hash for render fn
391391
* @param {Chunk} chunk Chunk instance for require
392392
* @param {(number|string)=} varModuleId module id
393-
* @return {any} the moduleRequire hook call return signature
393+
* @returns {TODO} the moduleRequire hook call return signature
394394
*/
395395
renderRequireFunctionForModule(hash, chunk, varModuleId) {
396396
return this.hooks.moduleRequire.call(
@@ -407,7 +407,7 @@ module.exports = class MainTemplate extends Tapable {
407407
* @param {Chunk} chunk Chunk instance for require add fn
408408
* @param {(string|number)=} varModuleId module id
409409
* @param {Module} varModule Module instance
410-
* @return {any} renderAddModule call
410+
* @returns {TODO} renderAddModule call
411411
*/
412412
renderAddModule(hash, chunk, varModuleId, varModule) {
413413
return this.hooks.addModule.call(
@@ -423,7 +423,7 @@ module.exports = class MainTemplate extends Tapable {
423423
*
424424
* @param {string} hash string hash
425425
* @param {number} length length
426-
* @return {any} call hook return
426+
* @returns {string} call hook return
427427
*/
428428
renderCurrentHashCode(hash, length) {
429429
length = length || Infinity;
@@ -436,7 +436,7 @@ module.exports = class MainTemplate extends Tapable {
436436
/**
437437
*
438438
* @param {object} options get public path options
439-
* @return {any} hook call
439+
* @returns {string} hook call
440440
*/
441441
getPublicPath(options) {
442442
return this.hooks.assetPath.call(

‎lib/NormalModule.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ class NonErrorEmittedError extends WebpackError {
6464

6565
/**
6666
* @typedef {Object} CachedSourceEntry
67-
* @property {any} source the generated source
67+
* @property {TODO} source the generated source
6868
* @property {string} hash the hash value
6969
*/
7070

‎lib/Parser.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -580,9 +580,9 @@ class Parser extends Tapable {
580580

581581
/**
582582
* @param {string} kind "cooked" | "raw"
583-
* @param {any[]} quasis quasis
584-
* @param {any[]} expressions expressions
585-
* @return {BasicEvaluatedExpression[]} Simplified template
583+
* @param {TODO[]} quasis quasis
584+
* @param {TODO[]} expressions expressions
585+
* @returns {BasicEvaluatedExpression[]} Simplified template
586586
*/
587587
const getSimplifiedTemplateResult = (kind, quasis, expressions) => {
588588
const parts = [];

‎lib/RuntimeTemplate.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ module.exports = class RuntimeTemplate {
2020
* @param {string=} options.chunkReason reason information of the chunk
2121
* @param {string=} options.message additional message
2222
* @param {string=} options.exportName name of the export
23-
* @return {string} comment
23+
* @returns {string} comment
2424
*/
2525
comment({ request, chunkName, chunkReason, message, exportName }) {
2626
let content;

‎lib/Template.js

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ const MATCH_PADDED_HYPHENS_REPLACE_REGEX = /^-|-$/g;
3434
/**
3535
* @param {HasId} a first id object to be sorted
3636
* @param {HasId} b second id object to be sorted against
37-
* @return {-1|0|1} the sort value
37+
* @returns {-1|0|1} the sort value
3838
*/
3939
const stringifyIdSortPredicate = (a, b) => {
4040
var aId = a.id + "";
@@ -48,7 +48,7 @@ const stringifyIdSortPredicate = (a, b) => {
4848
//https://github.com/Microsoft/TypeScript/issues/23375
4949
/**
5050
* @param {HasId} module the module to compare against
51-
* @return {boolean} return true if module.id is equal to type "number"
51+
* @returns {boolean} return true if module.id is equal to type "number"
5252
*/
5353
const moduleIdIsNumber = module => {
5454
return typeof module.id === "number";
@@ -58,7 +58,7 @@ class Template {
5858
/**
5959
*
6060
* @param {Function} fn - a runtime function (.runtime.js) "template"
61-
* @return {string} the updated and normalized function string
61+
* @returns {string} the updated and normalized function string
6262
*/
6363
static getFunctionContent(fn) {
6464
return fn
@@ -69,7 +69,7 @@ class Template {
6969
}
7070
/**
7171
* @param {string} str the string converted to identifier
72-
* @return {string} created identifier
72+
* @returns {string} created identifier
7373
*/
7474
static toIdentifier(str) {
7575
if (typeof str !== "string") return "";
@@ -80,7 +80,7 @@ class Template {
8080
/**
8181
*
8282
* @param {string} str string to be converted to commented in bundle code
83-
* @return {string} returns a commented version of string
83+
* @returns {string} returns a commented version of string
8484
*/
8585
static toComment(str) {
8686
if (!str) return "";
@@ -90,7 +90,7 @@ class Template {
9090
/**
9191
*
9292
* @param {string} str string to be converted to "normal comment"
93-
* @return {string} returns a commented version of string
93+
* @returns {string} returns a commented version of string
9494
*/
9595
static toNormalComment(str) {
9696
if (!str) return "";
@@ -99,7 +99,7 @@ class Template {
9999

100100
/**
101101
* @param {string} str string path to be normalized
102-
* @return {string} normalized bundle-safe path
102+
* @returns {string} normalized bundle-safe path
103103
*/
104104
static toPath(str) {
105105
if (typeof str !== "string") return "";
@@ -112,7 +112,7 @@ class Template {
112112
/**
113113
*
114114
* @param {number} n number to convert to ident
115-
* @return {string} returns single character ident
115+
* @returns {string} returns single character ident
116116
*/
117117
static numberToIdentifer(n) {
118118
// lower case
@@ -134,7 +134,7 @@ class Template {
134134
/**
135135
*
136136
* @param {string | string[]} str string to convert to identity
137-
* @return {string} converted identity
137+
* @returns {string} converted identity
138138
*/
139139
static indent(str) {
140140
if (Array.isArray(str)) {
@@ -151,7 +151,7 @@ class Template {
151151
*
152152
* @param {string|string[]} str string to create prefix for
153153
* @param {string} prefix prefix to compose
154-
* @return {string} returns new prefix string
154+
* @returns {string} returns new prefix string
155155
*/
156156
static prefix(str, prefix) {
157157
if (Array.isArray(str)) {
@@ -166,7 +166,7 @@ class Template {
166166
/**
167167
*
168168
* @param {string|string[]} str string or string collection
169-
* @return {string} returns a single string from array
169+
* @returns {string} returns a single string from array
170170
*/
171171
static asString(str) {
172172
if (Array.isArray(str)) {
@@ -178,7 +178,7 @@ class Template {
178178
/**
179179
*
180180
* @param {HasId[]} modules - a collection of modules to get array bounds for
181-
* @return {[number, number] | false} returns the upper and lower array bounds
181+
* @returns {[number, number] | false} returns the upper and lower array bounds
182182
* or false if not every module has a number based id
183183
*/
184184
static getModulesArrayBounds(modules) {
@@ -210,9 +210,9 @@ class Template {
210210
* @param {Chunk} chunk chunk whose modules will be rendered
211211
* @param {ModuleFilterPredicate} filterFn function used to filter modules from chunk to render
212212
* @param {ModuleTemplate} moduleTemplate ModuleTemplate instance used to render modules
213-
* @param {any | any[]} dependencyTemplates templates needed for each module to render dependencies
213+
* @param {TODO | TODO[]} dependencyTemplates templates needed for each module to render dependencies
214214
* @param {string=} prefix applying prefix strings
215-
* @return {ConcatSource} rendered chunk modules in a Source object
215+
* @returns {ConcatSource} rendered chunk modules in a Source object
216216
*/
217217
static renderChunkModules(
218218
chunk,

‎lib/debug/ProfilingPlugin.js

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -320,7 +320,8 @@ const makeInterceptorFor = (instance, tracer) => hookName => ({
320320
}
321321
});
322322

323-
/** @typedef {(...args: any[]) => void | Promise<any>} PluginFunction */
323+
// TODO improve typing
324+
/** @typedef {(...args: TODO[]) => void | Promise<TODO>} PluginFunction */
324325

325326
/**
326327
* @param {string} hookName Name of the hook to profile.
@@ -329,7 +330,7 @@ const makeInterceptorFor = (instance, tracer) => hookName => ({
329330
* @param {string} options.name Plugin name
330331
* @param {string} options.type Plugin type (sync | async | promise)
331332
* @param {PluginFunction} options.fn Plugin function
332-
* @returns {*} Chainable hooked function.
333+
* @returns {PluginFunction} Chainable hooked function.
333334
*/
334335
const makeNewProfiledTapFn = (hookName, tracer, { name, type, fn }) => {
335336
const defaultCategory = ["blink.user_timing"];

0 commit comments

Comments
 (0)