diff --git a/eslint.config.js b/eslint.config.js index 742a7ef35..4105ecb8d 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -3,7 +3,7 @@ const esLintjs = require('@eslint/js'); const jest = require('eslint-plugin-jest'); const tseslint = require('typescript-eslint'); const prettier = require('eslint-config-prettier'); -//const jsdoc = require('eslint-plugin-jsdoc'); +// const jsdoc = require('eslint-plugin-jsdoc'); // Only run tseslint on the files that we have included for TypeScript. const tsconfigTsFiles = ['**/*.{ts,mts}']; // match "include" in tsconfig.ts.json; @@ -45,6 +45,10 @@ module.exports = tseslint.config( // 'jsdoc/require-jsdoc': 'off', // 'jsdoc/require-param-description': 'off', // 'jsdoc/require-returns-description': 'off', + // 'jsdoc/require-param': ['warn', { exemptedBy: ['private'] }], + // // Currently can not configure checking to allow return/returns (and don't want wide change mixed with more interesting fixes), + // // and can not set options.jsdoc.mode yet to allow @remarks in typescript. + // 'jsdoc/check-tag-names': 0, }, languageOptions: { globals: { diff --git a/lib/argument.js b/lib/argument.js index 6d0153a71..ee46c365a 100644 --- a/lib/argument.js +++ b/lib/argument.js @@ -50,7 +50,7 @@ class Argument { } /** - * @package internal use only + * @package */ _concatValue(value, previous) { @@ -112,6 +112,8 @@ class Argument { /** * Make argument required. + * + * @returns {Argument} */ argRequired() { this.required = true; @@ -120,6 +122,8 @@ class Argument { /** * Make argument optional. + * + * @returns {Argument} */ argOptional() { this.required = false; diff --git a/lib/command.js b/lib/command.js index f9bf5eb1c..20ced4b82 100644 --- a/lib/command.js +++ b/lib/command.js @@ -135,8 +135,8 @@ 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 `` or `[optional]` and last may also be `variadic...` - * @param {(Object|string)} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable) - * @param {Object} [execOpts] - configuration options (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 */ @@ -196,8 +196,8 @@ class Command extends EventEmitter { * You can customise the help by overriding Help properties using configureHelp(), * or with a subclass of Help by overriding createHelp(). * - * @param {Object} [configuration] - configuration options - * @return {(Command|Object)} `this` command for chaining, or stored configuration + * @param {object} [configuration] - configuration options + * @return {(Command | object)} `this` command for chaining, or stored configuration */ configureHelp(configuration) { @@ -222,8 +222,8 @@ class Command extends EventEmitter { * // functions based on what is being written out * 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 + * @param {object} [configuration] - configuration options + * @return {(Command | object)} `this` command for chaining, or stored configuration */ configureOutput(configuration) { @@ -262,7 +262,7 @@ class Command extends EventEmitter { * See .command() for creating an attached subcommand which inherits settings from its parent. * * @param {Command} cmd - new subcommand - * @param {Object} [opts] - configuration options + * @param {object} [opts] - configuration options * @return {Command} `this` command for chaining */ @@ -587,7 +587,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Register option if no conflicts found, or throw on conflict. * * @param {Option} option - * @api private + * @private */ _registerOption(option) { @@ -611,7 +611,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Register command if no conflicts found, or throw on conflict. * * @param {Command} command - * @api private + * @private */ _registerCommand(command) { @@ -707,6 +707,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Internal implementation shared by .option() and .requiredOption() * + * @return {Command} `this` command for chaining * @private */ _optionEx(config, flags, description, fn, defaultValue) { @@ -791,7 +792,8 @@ 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] - if `true` or omitted, an optional value can be specified directly after the flag. + * @return {Command} `this` command for chaining */ combineFlagAndOptionalValue(combine = true) { this._combineFlagAndOptionalValue = !!combine; @@ -801,8 +803,8 @@ 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 - * for unknown options. + * @param {boolean} [allowUnknown] - if `true` or omitted, no error will be thrown for unknown options. + * @return {Command} `this` command for chaining */ allowUnknownOption(allowUnknown = true) { this._allowUnknownOption = !!allowUnknown; @@ -812,8 +814,8 @@ 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 - * for excess arguments. + * @param {boolean} [allowExcess] - if `true` or omitted, no error will be thrown for excess arguments. + * @return {Command} `this` command for chaining */ allowExcessArguments(allowExcess = true) { this._allowExcessArguments = !!allowExcess; @@ -825,7 +827,8 @@ 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] + * @return {Command} `this` command for chaining */ enablePositionalOptions(positional = true) { this._enablePositionalOptions = !!positional; @@ -838,8 +841,8 @@ 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] - * for unknown options. + * @param {boolean} [passThrough] for unknown options. + * @return {Command} `this` command for chaining */ passThroughOptions(passThrough = true) { this._passThroughOptions = !!passThrough; @@ -888,7 +891,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Retrieve option value. * * @param {string} key - * @return {Object} value + * @return {object} value */ getOptionValue(key) { @@ -902,7 +905,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Store option value. * * @param {string} key - * @param {Object} value + * @param {object} value * @return {Command} `this` command for chaining */ @@ -914,7 +917,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Store option value and where the value came from. * * @param {string} key - * @param {Object} value + * @param {object} value * @param {string} source - expected values are default/config/env/cli/implied * @return {Command} `this` command for chaining */ @@ -1050,9 +1053,9 @@ Expecting one of '${allowedValues.join("', '")}'`); * program.parse(process.argv); // assume argv[0] is app and argv[1] is script * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0] * - * @param {string[]} [argv] - * @param {object} [parseOptions] - * @param {string} parseOptions.from - one of 'node', 'user', 'electron' + * @param {string[]} [argv] - optional, defaults to process.argv + * @param {object} [parseOptions] - optionally specify style of options with from: node/user/electron + * @param {string} [parseOptions.from] - where the args are from: 'node', 'user', 'electron' * @return {Command} `this` command for chaining */ @@ -1080,7 +1083,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * * @param {string[]} [argv] * @param {object} [parseOptions] - * @param {string} parseOptions.from - one of 'node', 'user', 'electron' + * @param {string} parseOptions.from - where the args are from: 'node', 'user', 'electron' * @return {Promise} */ @@ -1186,6 +1189,7 @@ Expecting one of '${allowedValues.join("', '")}'`); signals.forEach((signal) => { process.on(signal, () => { if (proc.killed === false && proc.exitCode === null) { + // @ts-ignore because signals not typed to known strings proc.kill(signal); } }); @@ -1538,6 +1542,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Find matching command. * * @private + * @return {Command | undefined} */ _findCommand(name) { if (!name) return undefined; @@ -1551,7 +1556,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * * @param {string} arg * @return {Option} - * @package internal use only + * @package */ _findOption(arg) { @@ -1766,7 +1771,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Return an object containing local option values as key-value pairs. * - * @return {Object} + * @return {object} */ opts() { if (this._storeOptionsAsProperties) { @@ -1788,7 +1793,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Return an object containing merged local and global option values as key-value pairs. * - * @return {Object} + * @return {object} */ optsWithGlobals() { // globals overwrite locals @@ -1802,7 +1807,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Display error message and exit (or call exitOverride). * * @param {string} message - * @param {Object} [errorOptions] + * @param {object} [errorOptions] * @param {string} [errorOptions.code] - an id string representing the error * @param {number} [errorOptions.exitCode] - used with process.exit */ @@ -2081,7 +2086,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Set the description. * * @param {string} [str] - * @param {Object} [argsDescription] + * @param {object} [argsDescription] * @return {(string|Command)} */ description(str, argsDescription) { @@ -2355,7 +2360,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Returns null if has been disabled with .helpOption(false). * * @returns {(Option | null)} the help option - * @package internal use only + * @package */ _getHelpOption() { // Lazy create help option on demand. diff --git a/lib/error.js b/lib/error.js index a0263b501..7b5b0d399 100644 --- a/lib/error.js +++ b/lib/error.js @@ -1,6 +1,5 @@ /** * CommanderError class - * @class */ class CommanderError extends Error { /** @@ -8,7 +7,6 @@ class CommanderError extends Error { * @param {number} exitCode suggested exit code which could be used with process.exit * @param {string} code an id string representing the error * @param {string} message human-readable description of the error - * @constructor */ constructor(exitCode, code, message) { super(message); @@ -23,13 +21,11 @@ class CommanderError extends Error { /** * InvalidArgumentError class - * @class */ class InvalidArgumentError extends CommanderError { /** * Constructs the InvalidArgumentError class * @param {string} [message] explanation of why argument is invalid - * @constructor */ constructor(message) { super(1, 'commander.invalidArgument', message); diff --git a/lib/help.js b/lib/help.js index 9e93e817a..ed6f9916b 100644 --- a/lib/help.js +++ b/lib/help.js @@ -44,7 +44,7 @@ class Help { * * @param {Option} a * @param {Option} b - * @returns number + * @returns {number} */ compareOptions(a, b) { const getSortKey = (option) => { diff --git a/lib/option.js b/lib/option.js index 09359621d..bded840ae 100644 --- a/lib/option.js +++ b/lib/option.js @@ -93,7 +93,7 @@ class Option { * .addOption(new Option('--log', 'write logging information to file')) * .addOption(new Option('--trace', 'log extra details').implies({ log: 'trace.txt' })); * - * @param {Object} impliedOptionValues + * @param {object} impliedOptionValues * @return {Option} */ implies(impliedOptionValues) { @@ -158,7 +158,7 @@ class Option { } /** - * @package internal use only + * @package */ _concatValue(value, previous) { @@ -221,7 +221,7 @@ class Option { * * @param {string} arg * @return {boolean} - * @package internal use only + * @package */ is(arg) { @@ -234,7 +234,7 @@ class Option { * Options are one of boolean, negated, required argument, or optional argument. * * @return {boolean} - * @package internal use only + * @package */ isBoolean() { diff --git a/typings/index.d.ts b/typings/index.d.ts index 29c5365dc..528dcd0f4 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -26,7 +26,6 @@ export class CommanderError extends Error { * @param exitCode - suggested exit code which could be used with process.exit * @param code - an id string representing the error * @param message - human-readable description of the error - * @constructor */ constructor(exitCode: number, code: string, message: string); } @@ -35,7 +34,6 @@ export class InvalidArgumentError extends CommanderError { /** * Constructs the InvalidArgumentError class * @param message - explanation of why argument is invalid - * @constructor */ constructor(message: string); }