Skip to content

Commit 32c05a8

Browse files
authored
Improve JSDoc (#2103)
1 parent 066e381 commit 32c05a8

File tree

2 files changed

+33
-33
lines changed

2 files changed

+33
-33
lines changed

lib/command.js

Lines changed: 32 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ class Command extends EventEmitter {
5252
this._enablePositionalOptions = false;
5353
this._passThroughOptions = false;
5454
this._lifeCycleHooks = {}; // a hash of arrays
55-
/** @type {boolean | string} */
55+
/** @type {(boolean | string)} */
5656
this._showHelpAfterError = false;
5757
this._showSuggestionAfterError = true;
5858

@@ -141,7 +141,7 @@ class Command extends EventEmitter {
141141
* .command('stop [service]', 'stop named service, or all if no name supplied');
142142
*
143143
* @param {string} nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
144-
* @param {Object|string} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
144+
* @param {(Object|string)} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
145145
* @param {Object} [execOpts] - configuration options (for executable)
146146
* @return {Command} returns new command for action handler, or `this` for executable command
147147
*/
@@ -203,7 +203,7 @@ class Command extends EventEmitter {
203203
* or with a subclass of Help by overriding createHelp().
204204
*
205205
* @param {Object} [configuration] - configuration options
206-
* @return {Command|Object} `this` command for chaining, or stored configuration
206+
* @return {(Command|Object)} `this` command for chaining, or stored configuration
207207
*/
208208

209209
configureHelp(configuration) {
@@ -229,7 +229,7 @@ class Command extends EventEmitter {
229229
* outputError(str, write) // used for displaying errors, and not used for displaying help
230230
*
231231
* @param {Object} [configuration] - configuration options
232-
* @return {Command|Object} `this` command for chaining, or stored configuration
232+
* @return {(Command|Object)} `this` command for chaining, or stored configuration
233233
*/
234234

235235
configureOutput(configuration) {
@@ -242,7 +242,7 @@ class Command extends EventEmitter {
242242
/**
243243
* Display the help or a custom message after an error occurs.
244244
*
245-
* @param {boolean|string} [displayHelp]
245+
* @param {(boolean|string)} [displayHelp]
246246
* @return {Command} `this` command for chaining
247247
*/
248248
showHelpAfterError(displayHelp = true) {
@@ -316,7 +316,7 @@ class Command extends EventEmitter {
316316
*
317317
* @param {string} name
318318
* @param {string} [description]
319-
* @param {Function|*} [fn] - custom argument processing function
319+
* @param {(Function|*)} [fn] - custom argument processing function
320320
* @param {*} [defaultValue]
321321
* @return {Command} `this` command for chaining
322322
*/
@@ -517,7 +517,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
517517
/**
518518
* Wrap parseArgs to catch 'commander.invalidArgument'.
519519
*
520-
* @param {Option | Argument} target
520+
* @param {(Option | Argument)} target
521521
* @param {string} value
522522
* @param {*} previous
523523
* @param {string} invalidArgumentMessage
@@ -691,7 +691,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
691691
*
692692
* @param {string} flags
693693
* @param {string} [description]
694-
* @param {Function|*} [parseArg] - custom option processing function or default value
694+
* @param {(Function|*)} [parseArg] - custom option processing function or default value
695695
* @param {*} [defaultValue]
696696
* @return {Command} `this` command for chaining
697697
*/
@@ -708,7 +708,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
708708
*
709709
* @param {string} flags
710710
* @param {string} [description]
711-
* @param {Function|*} [parseArg] - custom option processing function or default value
711+
* @param {(Function|*)} [parseArg] - custom option processing function or default value
712712
* @param {*} [defaultValue]
713713
* @return {Command} `this` command for chaining
714714
*/
@@ -725,7 +725,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
725725
* program.combineFlagAndOptionalValue(true); // `-f80` is treated like `--flag=80`, this is the default behaviour
726726
* program.combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
727727
*
728-
* @param {Boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag.
728+
* @param {boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag.
729729
*/
730730
combineFlagAndOptionalValue(combine = true) {
731731
this._combineFlagAndOptionalValue = !!combine;
@@ -735,7 +735,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
735735
/**
736736
* Allow unknown options on the command line.
737737
*
738-
* @param {Boolean} [allowUnknown=true] - if `true` or omitted, no error will be thrown
738+
* @param {boolean} [allowUnknown=true] - if `true` or omitted, no error will be thrown
739739
* for unknown options.
740740
*/
741741
allowUnknownOption(allowUnknown = true) {
@@ -746,7 +746,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
746746
/**
747747
* Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
748748
*
749-
* @param {Boolean} [allowExcess=true] - if `true` or omitted, no error will be thrown
749+
* @param {boolean} [allowExcess=true] - if `true` or omitted, no error will be thrown
750750
* for excess arguments.
751751
*/
752752
allowExcessArguments(allowExcess = true) {
@@ -759,7 +759,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
759759
* subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions.
760760
* The default behaviour is non-positional and global options may appear anywhere on the command line.
761761
*
762-
* @param {Boolean} [positional=true]
762+
* @param {boolean} [positional=true]
763763
*/
764764
enablePositionalOptions(positional = true) {
765765
this._enablePositionalOptions = !!positional;
@@ -772,7 +772,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
772772
* positional options to have been enabled on the program (parent commands).
773773
* The default behaviour is non-positional and options may appear before or after command-arguments.
774774
*
775-
* @param {Boolean} [passThrough=true]
775+
* @param {boolean} [passThrough=true]
776776
* for unknown options.
777777
*/
778778
passThroughOptions(passThrough = true) {
@@ -1229,9 +1229,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
12291229
/**
12301230
* Once we have a promise we chain, but call synchronously until then.
12311231
*
1232-
* @param {Promise|undefined} promise
1232+
* @param {(Promise|undefined)} promise
12331233
* @param {Function} fn
1234-
* @return {Promise|undefined}
1234+
* @return {(Promise|undefined)}
12351235
* @private
12361236
*/
12371237

@@ -1247,9 +1247,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
12471247

12481248
/**
12491249
*
1250-
* @param {Promise|undefined} promise
1250+
* @param {(Promise|undefined)} promise
12511251
* @param {string} event
1252-
* @return {Promise|undefined}
1252+
* @return {(Promise|undefined)}
12531253
* @private
12541254
*/
12551255

@@ -1278,10 +1278,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
12781278

12791279
/**
12801280
*
1281-
* @param {Promise|undefined} promise
1281+
* @param {(Promise|undefined)} promise
12821282
* @param {Command} subCommand
12831283
* @param {string} event
1284-
* @return {Promise|undefined}
1284+
* @return {(Promise|undefined)}
12851285
* @private
12861286
*/
12871287

@@ -1477,8 +1477,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
14771477
* sub --unknown uuu op => [sub], [--unknown uuu op]
14781478
* sub -- --unknown uuu op => [sub --unknown uuu op], []
14791479
*
1480-
* @param {String[]} argv
1481-
* @return {{operands: String[], unknown: String[]}}
1480+
* @param {string[]} argv
1481+
* @return {{operands: string[], unknown: string[]}}
14821482
*/
14831483

14841484
parseOptions(argv) {
@@ -1857,7 +1857,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
18571857
* @param {string} [str]
18581858
* @param {string} [flags]
18591859
* @param {string} [description]
1860-
* @return {this | string | undefined} `this` command for chaining, or version string if no arguments
1860+
* @return {(this | string | undefined)} `this` command for chaining, or version string if no arguments
18611861
*/
18621862

18631863
version(str, flags, description) {
@@ -1881,7 +1881,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
18811881
*
18821882
* @param {string} [str]
18831883
* @param {Object} [argsDescription]
1884-
* @return {string|Command}
1884+
* @return {(string|Command)}
18851885
*/
18861886
description(str, argsDescription) {
18871887
if (str === undefined && argsDescription === undefined) return this._description;
@@ -1896,7 +1896,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
18961896
* Set the summary. Used when listed as subcommand of parent.
18971897
*
18981898
* @param {string} [str]
1899-
* @return {string|Command}
1899+
* @return {(string|Command)}
19001900
*/
19011901
summary(str) {
19021902
if (str === undefined) return this._summary;
@@ -1910,7 +1910,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
19101910
* You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help.
19111911
*
19121912
* @param {string} [alias]
1913-
* @return {string|Command}
1913+
* @return {(string|Command)}
19141914
*/
19151915

19161916
alias(alias) {
@@ -1941,7 +1941,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
19411941
* Only the first alias is shown in the auto-generated help.
19421942
*
19431943
* @param {string[]} [aliases]
1944-
* @return {string[]|Command}
1944+
* @return {(string[]|Command)}
19451945
*/
19461946

19471947
aliases(aliases) {
@@ -1956,7 +1956,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
19561956
* Set / get the command usage `str`.
19571957
*
19581958
* @param {string} [str]
1959-
* @return {String|Command}
1959+
* @return {(string|Command)}
19601960
*/
19611961

19621962
usage(str) {
@@ -1981,7 +1981,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
19811981
* Get or set the name of the command.
19821982
*
19831983
* @param {string} [str]
1984-
* @return {string|Command}
1984+
* @return {(string|Command)}
19851985
*/
19861986

19871987
name(str) {
@@ -2018,7 +2018,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
20182018
* program.executableDir('subcommands');
20192019
*
20202020
* @param {string} [path]
2021-
* @return {string|null|Command}
2021+
* @return {(string|null|Command)}
20222022
*/
20232023

20242024
executableDir(path) {
@@ -2100,7 +2100,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
21002100
* flags and help description for your command. Pass in false to
21012101
* disable the built-in help option.
21022102
*
2103-
* @param {string | boolean} [flags]
2103+
* @param {(string | boolean)} [flags]
21042104
* @param {string} [description]
21052105
* @return {Command} `this` command for chaining
21062106
*/
@@ -2145,7 +2145,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
21452145
* and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.
21462146
*
21472147
* @param {string} position - before or after built-in help
2148-
* @param {string | Function} text - string to add, or a function returning a string
2148+
* @param {(string | Function)} text - string to add, or a function returning a string
21492149
* @return {Command} `this` command for chaining
21502150
*/
21512151
addHelpText(position, text) {

lib/option.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ class Option {
7474
* new Option('--rgb').conflicts('cmyk');
7575
* new Option('--js').conflicts(['ts', 'jsx']);
7676
*
77-
* @param {string | string[]} names
77+
* @param {(string | string[])} names
7878
* @return {Option}
7979
*/
8080

0 commit comments

Comments
 (0)