Fix some JSDoc lint issues (#2181)

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: {

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;

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 `<required>` 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.

lib/error.js

@@ -1,14 +1,12 @@
 /**
  * CommanderError class
- * @class
  */
 class CommanderError extends Error {
   /**
    * Constructs the CommanderError class
    * @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);

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) => {

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() {

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);
 }