Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve jsdoc #2103

Merged
merged 1 commit into from
Dec 16, 2023
Merged

Improve jsdoc #2103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 32 additions & 32 deletions lib/command.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ class Command extends EventEmitter {
this._enablePositionalOptions = false;
this._passThroughOptions = false;
this._lifeCycleHooks = {}; // a hash of arrays
/** @type {boolean | string} */
/** @type {(boolean | string)} */
this._showHelpAfterError = false;
this._showSuggestionAfterError = true;

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

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

configureOutput(configuration) {
Expand All @@ -242,7 +242,7 @@ class Command extends EventEmitter {
/**
* Display the help or a custom message after an error occurs.
*
* @param {boolean|string} [displayHelp]
* @param {(boolean|string)} [displayHelp]
* @return {Command} `this` command for chaining
*/
showHelpAfterError(displayHelp = true) {
Expand Down Expand Up @@ -316,7 +316,7 @@ class Command extends EventEmitter {
*
* @param {string} name
* @param {string} [description]
* @param {Function|*} [fn] - custom argument processing function
* @param {(Function|*)} [fn] - custom argument processing function
* @param {*} [defaultValue]
* @return {Command} `this` command for chaining
*/
Expand Down Expand Up @@ -517,7 +517,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
/**
* Wrap parseArgs to catch 'commander.invalidArgument'.
*
* @param {Option | Argument} target
* @param {(Option | Argument)} target
* @param {string} value
* @param {*} previous
* @param {string} invalidArgumentMessage
Expand Down Expand Up @@ -691,7 +691,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
*
* @param {string} flags
* @param {string} [description]
* @param {Function|*} [parseArg] - custom option processing function or default value
* @param {(Function|*)} [parseArg] - custom option processing function or default value
* @param {*} [defaultValue]
* @return {Command} `this` command for chaining
*/
Expand All @@ -708,7 +708,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
*
* @param {string} flags
* @param {string} [description]
* @param {Function|*} [parseArg] - custom option processing function or default value
* @param {(Function|*)} [parseArg] - custom option processing function or default value
* @param {*} [defaultValue]
* @return {Command} `this` command for chaining
*/
Expand All @@ -725,7 +725,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
* program.combineFlagAndOptionalValue(true); // `-f80` is treated like `--flag=80`, this is the default behaviour
* program.combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
*
* @param {Boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag.
* @param {boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag.
*/
combineFlagAndOptionalValue(combine = true) {
this._combineFlagAndOptionalValue = !!combine;
Expand All @@ -735,7 +735,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
/**
* Allow unknown options on the command line.
*
* @param {Boolean} [allowUnknown=true] - if `true` or omitted, no error will be thrown
* @param {boolean} [allowUnknown=true] - if `true` or omitted, no error will be thrown
* for unknown options.
*/
allowUnknownOption(allowUnknown = true) {
Expand All @@ -746,7 +746,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
/**
* Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
*
* @param {Boolean} [allowExcess=true] - if `true` or omitted, no error will be thrown
* @param {boolean} [allowExcess=true] - if `true` or omitted, no error will be thrown
* for excess arguments.
*/
allowExcessArguments(allowExcess = true) {
Expand All @@ -759,7 +759,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
* subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions.
* The default behaviour is non-positional and global options may appear anywhere on the command line.
*
* @param {Boolean} [positional=true]
* @param {boolean} [positional=true]
*/
enablePositionalOptions(positional = true) {
this._enablePositionalOptions = !!positional;
Expand All @@ -772,7 +772,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
* positional options to have been enabled on the program (parent commands).
* The default behaviour is non-positional and options may appear before or after command-arguments.
*
* @param {Boolean} [passThrough=true]
* @param {boolean} [passThrough=true]
* for unknown options.
*/
passThroughOptions(passThrough = true) {
Expand Down Expand Up @@ -1229,9 +1229,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
/**
* Once we have a promise we chain, but call synchronously until then.
*
* @param {Promise|undefined} promise
* @param {(Promise|undefined)} promise
* @param {Function} fn
* @return {Promise|undefined}
* @return {(Promise|undefined)}
* @private
*/

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

/**
*
* @param {Promise|undefined} promise
* @param {(Promise|undefined)} promise
* @param {string} event
* @return {Promise|undefined}
* @return {(Promise|undefined)}
* @private
*/

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

/**
*
* @param {Promise|undefined} promise
* @param {(Promise|undefined)} promise
* @param {Command} subCommand
* @param {string} event
* @return {Promise|undefined}
* @return {(Promise|undefined)}
* @private
*/

Expand Down Expand Up @@ -1477,8 +1477,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
* sub --unknown uuu op => [sub], [--unknown uuu op]
* sub -- --unknown uuu op => [sub --unknown uuu op], []
*
* @param {String[]} argv
* @return {{operands: String[], unknown: String[]}}
* @param {string[]} argv
* @return {{operands: string[], unknown: string[]}}
*/

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

version(str, flags, description) {
Expand All @@ -1881,7 +1881,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
*
* @param {string} [str]
* @param {Object} [argsDescription]
* @return {string|Command}
* @return {(string|Command)}
*/
description(str, argsDescription) {
if (str === undefined && argsDescription === undefined) return this._description;
Expand All @@ -1896,7 +1896,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
* Set the summary. Used when listed as subcommand of parent.
*
* @param {string} [str]
* @return {string|Command}
* @return {(string|Command)}
*/
summary(str) {
if (str === undefined) return this._summary;
Expand All @@ -1910,7 +1910,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
* You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help.
*
* @param {string} [alias]
* @return {string|Command}
* @return {(string|Command)}
*/

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

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

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

name(str) {
Expand Down Expand Up @@ -2018,7 +2018,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
* program.executableDir('subcommands');
*
* @param {string} [path]
* @return {string|null|Command}
* @return {(string|null|Command)}
*/

executableDir(path) {
Expand Down Expand Up @@ -2100,7 +2100,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
* flags and help description for your command. Pass in false to
* disable the built-in help option.
*
* @param {string | boolean} [flags]
* @param {(string | boolean)} [flags]
* @param {string} [description]
* @return {Command} `this` command for chaining
*/
Expand Down Expand Up @@ -2145,7 +2145,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
* and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.
*
* @param {string} position - before or after built-in help
* @param {string | Function} text - string to add, or a function returning a string
* @param {(string | Function)} text - string to add, or a function returning a string
* @return {Command} `this` command for chaining
*/
addHelpText(position, text) {
Expand Down
2 changes: 1 addition & 1 deletion lib/option.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ class Option {
* new Option('--rgb').conflicts('cmyk');
* new Option('--js').conflicts(['ts', 'jsx']);
*
* @param {string | string[]} names
* @param {(string | string[])} names
* @return {Option}
*/

Expand Down