Skip to content

Commit b95ea44

Browse files
authored
Fix some JSDoc lint issues (#2181)
1 parent a996782 commit b95ea44

File tree

7 files changed

+50
-43
lines changed

7 files changed

+50
-43
lines changed

eslint.config.js

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ const esLintjs = require('@eslint/js');
33
const jest = require('eslint-plugin-jest');
44
const tseslint = require('typescript-eslint');
55
const prettier = require('eslint-config-prettier');
6-
//const jsdoc = require('eslint-plugin-jsdoc');
6+
// const jsdoc = require('eslint-plugin-jsdoc');
77

88
// Only run tseslint on the files that we have included for TypeScript.
99
const tsconfigTsFiles = ['**/*.{ts,mts}']; // match "include" in tsconfig.ts.json;
@@ -45,6 +45,10 @@ module.exports = tseslint.config(
4545
// 'jsdoc/require-jsdoc': 'off',
4646
// 'jsdoc/require-param-description': 'off',
4747
// 'jsdoc/require-returns-description': 'off',
48+
// 'jsdoc/require-param': ['warn', { exemptedBy: ['private'] }],
49+
// // Currently can not configure checking to allow return/returns (and don't want wide change mixed with more interesting fixes),
50+
// // and can not set options.jsdoc.mode yet to allow @remarks in typescript.
51+
// 'jsdoc/check-tag-names': 0,
4852
},
4953
languageOptions: {
5054
globals: {

lib/argument.js

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ class Argument {
5050
}
5151

5252
/**
53-
* @package internal use only
53+
* @package
5454
*/
5555

5656
_concatValue(value, previous) {
@@ -112,6 +112,8 @@ class Argument {
112112

113113
/**
114114
* Make argument required.
115+
*
116+
* @returns {Argument}
115117
*/
116118
argRequired() {
117119
this.required = true;
@@ -120,6 +122,8 @@ class Argument {
120122

121123
/**
122124
* Make argument optional.
125+
*
126+
* @returns {Argument}
123127
*/
124128
argOptional() {
125129
this.required = false;

lib/command.js

Lines changed: 35 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -135,8 +135,8 @@ class Command extends EventEmitter {
135135
* .command('stop [service]', 'stop named service, or all if no name supplied');
136136
*
137137
* @param {string} nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
138-
* @param {(Object|string)} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
139-
* @param {Object} [execOpts] - configuration options (for executable)
138+
* @param {(object | string)} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
139+
* @param {object} [execOpts] - configuration options (for executable)
140140
* @return {Command} returns new command for action handler, or `this` for executable command
141141
*/
142142

@@ -196,8 +196,8 @@ class Command extends EventEmitter {
196196
* You can customise the help by overriding Help properties using configureHelp(),
197197
* or with a subclass of Help by overriding createHelp().
198198
*
199-
* @param {Object} [configuration] - configuration options
200-
* @return {(Command|Object)} `this` command for chaining, or stored configuration
199+
* @param {object} [configuration] - configuration options
200+
* @return {(Command | object)} `this` command for chaining, or stored configuration
201201
*/
202202

203203
configureHelp(configuration) {
@@ -222,8 +222,8 @@ class Command extends EventEmitter {
222222
* // functions based on what is being written out
223223
* outputError(str, write) // used for displaying errors, and not used for displaying help
224224
*
225-
* @param {Object} [configuration] - configuration options
226-
* @return {(Command|Object)} `this` command for chaining, or stored configuration
225+
* @param {object} [configuration] - configuration options
226+
* @return {(Command | object)} `this` command for chaining, or stored configuration
227227
*/
228228

229229
configureOutput(configuration) {
@@ -262,7 +262,7 @@ class Command extends EventEmitter {
262262
* See .command() for creating an attached subcommand which inherits settings from its parent.
263263
*
264264
* @param {Command} cmd - new subcommand
265-
* @param {Object} [opts] - configuration options
265+
* @param {object} [opts] - configuration options
266266
* @return {Command} `this` command for chaining
267267
*/
268268

@@ -587,7 +587,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
587587
* Register option if no conflicts found, or throw on conflict.
588588
*
589589
* @param {Option} option
590-
* @api private
590+
* @private
591591
*/
592592

593593
_registerOption(option) {
@@ -611,7 +611,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
611611
* Register command if no conflicts found, or throw on conflict.
612612
*
613613
* @param {Command} command
614-
* @api private
614+
* @private
615615
*/
616616

617617
_registerCommand(command) {
@@ -707,6 +707,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
707707
/**
708708
* Internal implementation shared by .option() and .requiredOption()
709709
*
710+
* @return {Command} `this` command for chaining
710711
* @private
711712
*/
712713
_optionEx(config, flags, description, fn, defaultValue) {
@@ -791,7 +792,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
791792
* program.combineFlagAndOptionalValue(true); // `-f80` is treated like `--flag=80`, this is the default behaviour
792793
* program.combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
793794
*
794-
* @param {boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag.
795+
* @param {boolean} [combine] - if `true` or omitted, an optional value can be specified directly after the flag.
796+
* @return {Command} `this` command for chaining
795797
*/
796798
combineFlagAndOptionalValue(combine = true) {
797799
this._combineFlagAndOptionalValue = !!combine;
@@ -801,8 +803,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
801803
/**
802804
* Allow unknown options on the command line.
803805
*
804-
* @param {boolean} [allowUnknown=true] - if `true` or omitted, no error will be thrown
805-
* for unknown options.
806+
* @param {boolean} [allowUnknown] - if `true` or omitted, no error will be thrown for unknown options.
807+
* @return {Command} `this` command for chaining
806808
*/
807809
allowUnknownOption(allowUnknown = true) {
808810
this._allowUnknownOption = !!allowUnknown;
@@ -812,8 +814,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
812814
/**
813815
* Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
814816
*
815-
* @param {boolean} [allowExcess=true] - if `true` or omitted, no error will be thrown
816-
* for excess arguments.
817+
* @param {boolean} [allowExcess] - if `true` or omitted, no error will be thrown for excess arguments.
818+
* @return {Command} `this` command for chaining
817819
*/
818820
allowExcessArguments(allowExcess = true) {
819821
this._allowExcessArguments = !!allowExcess;
@@ -825,7 +827,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
825827
* subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions.
826828
* The default behaviour is non-positional and global options may appear anywhere on the command line.
827829
*
828-
* @param {boolean} [positional=true]
830+
* @param {boolean} [positional]
831+
* @return {Command} `this` command for chaining
829832
*/
830833
enablePositionalOptions(positional = true) {
831834
this._enablePositionalOptions = !!positional;
@@ -838,8 +841,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
838841
* positional options to have been enabled on the program (parent commands).
839842
* The default behaviour is non-positional and options may appear before or after command-arguments.
840843
*
841-
* @param {boolean} [passThrough=true]
842-
* for unknown options.
844+
* @param {boolean} [passThrough] for unknown options.
845+
* @return {Command} `this` command for chaining
843846
*/
844847
passThroughOptions(passThrough = true) {
845848
this._passThroughOptions = !!passThrough;
@@ -888,7 +891,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
888891
* Retrieve option value.
889892
*
890893
* @param {string} key
891-
* @return {Object} value
894+
* @return {object} value
892895
*/
893896

894897
getOptionValue(key) {
@@ -902,7 +905,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
902905
* Store option value.
903906
*
904907
* @param {string} key
905-
* @param {Object} value
908+
* @param {object} value
906909
* @return {Command} `this` command for chaining
907910
*/
908911

@@ -914,7 +917,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
914917
* Store option value and where the value came from.
915918
*
916919
* @param {string} key
917-
* @param {Object} value
920+
* @param {object} value
918921
* @param {string} source - expected values are default/config/env/cli/implied
919922
* @return {Command} `this` command for chaining
920923
*/
@@ -1050,9 +1053,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
10501053
* program.parse(process.argv); // assume argv[0] is app and argv[1] is script
10511054
* program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
10521055
*
1053-
* @param {string[]} [argv]
1054-
* @param {object} [parseOptions]
1055-
* @param {string} parseOptions.from - one of 'node', 'user', 'electron'
1056+
* @param {string[]} [argv] - optional, defaults to process.argv
1057+
* @param {object} [parseOptions] - optionally specify style of options with from: node/user/electron
1058+
* @param {string} [parseOptions.from] - where the args are from: 'node', 'user', 'electron'
10561059
* @return {Command} `this` command for chaining
10571060
*/
10581061

@@ -1080,7 +1083,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
10801083
*
10811084
* @param {string[]} [argv]
10821085
* @param {object} [parseOptions]
1083-
* @param {string} parseOptions.from - one of 'node', 'user', 'electron'
1086+
* @param {string} parseOptions.from - where the args are from: 'node', 'user', 'electron'
10841087
* @return {Promise}
10851088
*/
10861089

@@ -1186,6 +1189,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
11861189
signals.forEach((signal) => {
11871190
process.on(signal, () => {
11881191
if (proc.killed === false && proc.exitCode === null) {
1192+
// @ts-ignore because signals not typed to known strings
11891193
proc.kill(signal);
11901194
}
11911195
});
@@ -1538,6 +1542,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
15381542
* Find matching command.
15391543
*
15401544
* @private
1545+
* @return {Command | undefined}
15411546
*/
15421547
_findCommand(name) {
15431548
if (!name) return undefined;
@@ -1551,7 +1556,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
15511556
*
15521557
* @param {string} arg
15531558
* @return {Option}
1554-
* @package internal use only
1559+
* @package
15551560
*/
15561561

15571562
_findOption(arg) {
@@ -1766,7 +1771,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
17661771
/**
17671772
* Return an object containing local option values as key-value pairs.
17681773
*
1769-
* @return {Object}
1774+
* @return {object}
17701775
*/
17711776
opts() {
17721777
if (this._storeOptionsAsProperties) {
@@ -1788,7 +1793,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
17881793
/**
17891794
* Return an object containing merged local and global option values as key-value pairs.
17901795
*
1791-
* @return {Object}
1796+
* @return {object}
17921797
*/
17931798
optsWithGlobals() {
17941799
// globals overwrite locals
@@ -1802,7 +1807,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
18021807
* Display error message and exit (or call exitOverride).
18031808
*
18041809
* @param {string} message
1805-
* @param {Object} [errorOptions]
1810+
* @param {object} [errorOptions]
18061811
* @param {string} [errorOptions.code] - an id string representing the error
18071812
* @param {number} [errorOptions.exitCode] - used with process.exit
18081813
*/
@@ -2081,7 +2086,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
20812086
* Set the description.
20822087
*
20832088
* @param {string} [str]
2084-
* @param {Object} [argsDescription]
2089+
* @param {object} [argsDescription]
20852090
* @return {(string|Command)}
20862091
*/
20872092
description(str, argsDescription) {
@@ -2355,7 +2360,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
23552360
* Returns null if has been disabled with .helpOption(false).
23562361
*
23572362
* @returns {(Option | null)} the help option
2358-
* @package internal use only
2363+
* @package
23592364
*/
23602365
_getHelpOption() {
23612366
// Lazy create help option on demand.

lib/error.js

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
/**
22
* CommanderError class
3-
* @class
43
*/
54
class CommanderError extends Error {
65
/**
76
* Constructs the CommanderError class
87
* @param {number} exitCode suggested exit code which could be used with process.exit
98
* @param {string} code an id string representing the error
109
* @param {string} message human-readable description of the error
11-
* @constructor
1210
*/
1311
constructor(exitCode, code, message) {
1412
super(message);
@@ -23,13 +21,11 @@ class CommanderError extends Error {
2321

2422
/**
2523
* InvalidArgumentError class
26-
* @class
2724
*/
2825
class InvalidArgumentError extends CommanderError {
2926
/**
3027
* Constructs the InvalidArgumentError class
3128
* @param {string} [message] explanation of why argument is invalid
32-
* @constructor
3329
*/
3430
constructor(message) {
3531
super(1, 'commander.invalidArgument', message);

lib/help.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ class Help {
4444
*
4545
* @param {Option} a
4646
* @param {Option} b
47-
* @returns number
47+
* @returns {number}
4848
*/
4949
compareOptions(a, b) {
5050
const getSortKey = (option) => {

lib/option.js

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ class Option {
9393
* .addOption(new Option('--log', 'write logging information to file'))
9494
* .addOption(new Option('--trace', 'log extra details').implies({ log: 'trace.txt' }));
9595
*
96-
* @param {Object} impliedOptionValues
96+
* @param {object} impliedOptionValues
9797
* @return {Option}
9898
*/
9999
implies(impliedOptionValues) {
@@ -158,7 +158,7 @@ class Option {
158158
}
159159

160160
/**
161-
* @package internal use only
161+
* @package
162162
*/
163163

164164
_concatValue(value, previous) {
@@ -221,7 +221,7 @@ class Option {
221221
*
222222
* @param {string} arg
223223
* @return {boolean}
224-
* @package internal use only
224+
* @package
225225
*/
226226

227227
is(arg) {
@@ -234,7 +234,7 @@ class Option {
234234
* Options are one of boolean, negated, required argument, or optional argument.
235235
*
236236
* @return {boolean}
237-
* @package internal use only
237+
* @package
238238
*/
239239

240240
isBoolean() {

typings/index.d.ts

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,6 @@ export class CommanderError extends Error {
2626
* @param exitCode - suggested exit code which could be used with process.exit
2727
* @param code - an id string representing the error
2828
* @param message - human-readable description of the error
29-
* @constructor
3029
*/
3130
constructor(exitCode: number, code: string, message: string);
3231
}
@@ -35,7 +34,6 @@ export class InvalidArgumentError extends CommanderError {
3534
/**
3635
* Constructs the InvalidArgumentError class
3736
* @param message - explanation of why argument is invalid
38-
* @constructor
3937
*/
4038
constructor(message: string);
4139
}

0 commit comments

Comments
 (0)