From a5914251635284b5c1a12cfd60ebc47b3235e7fb Mon Sep 17 00:00:00 2001 From: John Gee Date: Fri, 15 Sep 2023 21:27:24 +1200 Subject: [PATCH] Switch @api private to official JSDoc --- lib/argument.js | 4 +-- lib/command.js | 95 ++++++++++++++++++++++++------------------------- lib/option.js | 11 +++--- 3 files changed, 54 insertions(+), 56 deletions(-) diff --git a/lib/argument.js b/lib/argument.js index c16430250..bcdba6de3 100644 --- a/lib/argument.js +++ b/lib/argument.js @@ -52,7 +52,7 @@ class Argument { } /** - * @api private + * @package internal use only */ _concatValue(value, previous) { @@ -132,7 +132,7 @@ class Argument { * * @param {Argument} arg * @return {string} - * @api private + * @private */ function humanReadableArgName(arg) { diff --git a/lib/command.js b/lib/command.js index a6291bcf7..544f8c353 100644 --- a/lib/command.js +++ b/lib/command.js @@ -111,7 +111,7 @@ class Command extends EventEmitter { /** * @returns {Command[]} - * @api private + * @private */ _getCommandAndAncestors() { @@ -395,7 +395,7 @@ class Command extends EventEmitter { /** * @return {boolean} - * @api private + * @package internal use only */ _hasImplicitHelpCommand() { @@ -456,7 +456,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * @param {string} code an id string representing the error * @param {string} message human-readable description of the error * @return never - * @api private + * @private */ _exit(exitCode, code, message) { @@ -522,7 +522,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * @param {string} value * @param {any} previous * @param {string} invalidArgumentMessage - * @api private + * @private */ _callParseArg(target, value, previous, invalidArgumentMessage) { @@ -608,7 +608,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Internal implementation shared by .option() and .requiredOption() * - * @api private + * @private */ _optionEx(config, flags, description, fn, defaultValue) { if (typeof flags === 'object' && flags instanceof Option) { @@ -769,7 +769,7 @@ Expecting one of '${allowedValues.join("', '")}'`); } /** - * @api private + * @private */ _checkForBrokenPassThrough() { @@ -877,7 +877,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Get user arguments from implied or explicit arguments. * Side-effects: set _scriptPath if args included script. Used for default program name, and subcommand searches. * - * @api private + * @private */ _prepareUserArgs(argv, parseOptions) { @@ -980,7 +980,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Execute a sub-command executable. * - * @api private + * @private */ _executeSubCommand(subcommand, args) { @@ -1105,7 +1105,7 @@ Expecting one of '${allowedValues.join("', '")}'`); } /** - * @api private + * @private */ _dispatchSubcommand(commandName, operands, unknown) { @@ -1128,7 +1128,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Invoke help directly if possible, or dispatch if necessary. * e.g. help foo * - * @api private + * @private */ _dispatchHelpCommand(subcommandName) { @@ -1149,7 +1149,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Check this.args against expected this._args. * - * @api private + * @private */ _checkNumberOfArguments() { @@ -1171,7 +1171,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Process this.args using this._args and save as this.processedArgs! * - * @api private + * @private */ _processArguments() { @@ -1219,7 +1219,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * @param {Promise|undefined} promise * @param {Function} fn * @return {Promise|undefined} - * @api private + * @private */ _chainOrCall(promise, fn) { @@ -1237,7 +1237,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * @param {Promise|undefined} promise * @param {string} event * @return {Promise|undefined} - * @api private + * @private */ _chainOrCallHooks(promise, event) { @@ -1269,7 +1269,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * @param {Command} subCommand * @param {string} event * @return {Promise|undefined} - * @api private + * @private */ _chainOrCallSubCommandHook(promise, subCommand, event) { @@ -1288,7 +1288,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Process arguments in context of this command. * Returns action result, in case it is a promise. * - * @api private + * @private */ _parseCommand(operands, unknown) { @@ -1306,7 +1306,7 @@ Expecting one of '${allowedValues.join("', '")}'`); return this._dispatchHelpCommand(operands[1]); } if (this._defaultCommandName) { - outputHelpIfRequested(this, unknown); // Run the help for default command from parent rather than passing to default command + this._outputHelpIfRequested(unknown); // Run the help for default command from parent rather than passing to default command return this._dispatchSubcommand(this._defaultCommandName, operands, unknown); } if (this.commands.length && this.args.length === 0 && !this._actionHandler && !this._defaultCommandName) { @@ -1314,7 +1314,7 @@ Expecting one of '${allowedValues.join("', '")}'`); this.help({ error: true }); } - outputHelpIfRequested(this, parsed.unknown); + this._outputHelpIfRequested(parsed.unknown); this._checkForMissingMandatoryOptions(); this._checkForConflictingOptions(); @@ -1372,7 +1372,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Find matching command. * - * @api private + * @private */ _findCommand(name) { if (!name) return undefined; @@ -1384,7 +1384,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * * @param {string} arg * @return {Option} - * @api private + * @package internal use only */ _findOption(arg) { @@ -1395,7 +1395,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Display an error message if a mandatory option does not have a value. * Called after checking for help flags in leaf subcommand. * - * @api private + * @private */ _checkForMissingMandatoryOptions() { @@ -1412,7 +1412,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Display an error message if conflicting options are used together in this. * - * @api private + * @private */ _checkForConflictingLocalOptions() { const definedNonDefaultOptions = this.options.filter( @@ -1443,7 +1443,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Display an error message if conflicting options are used together. * Called after checking for help flags in leaf subcommand. * - * @api private + * @private */ _checkForConflictingOptions() { // Walk up hierarchy so can call in subcommand after checking for displaying help. @@ -1647,7 +1647,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Apply any option related environment variables, if option does * not have a value from cli or client code. * - * @api private + * @private */ _parseOptionsEnv() { this.options.forEach((option) => { @@ -1670,7 +1670,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Apply any implied option values, if option is undefined or default value. * - * @api private + * @private */ _parseOptionsImplied() { const dualHelper = new DualOptions(this.options); @@ -1694,7 +1694,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Argument `name` is missing. * * @param {string} name - * @api private + * @private */ missingArgument(name) { @@ -1706,7 +1706,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * `Option` is missing an argument. * * @param {Option} option - * @api private + * @private */ optionMissingArgument(option) { @@ -1718,7 +1718,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * `Option` does not have a value, and is a mandatory option. * * @param {Option} option - * @api private + * @private */ missingMandatoryOptionValue(option) { @@ -1731,7 +1731,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * * @param {Option} option * @param {Option} conflictingOption - * @api private + * @private */ _conflictingOption(option, conflictingOption) { // The calling code does not know whether a negated option is the source of the @@ -1768,7 +1768,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Unknown option `flag`. * * @param {string} flag - * @api private + * @private */ unknownOption(flag) { @@ -1797,7 +1797,7 @@ Expecting one of '${allowedValues.join("', '")}'`); * Excess arguments, more than expected. * * @param {string[]} receivedArgs - * @api private + * @private */ _excessArguments(receivedArgs) { @@ -1813,7 +1813,7 @@ Expecting one of '${allowedValues.join("', '")}'`); /** * Unknown command. * - * @api private + * @private */ unknownCommand() { @@ -2023,7 +2023,7 @@ Expecting one of '${allowedValues.join("', '")}'`); } /** - * @api private + * @private */ _getHelpContext(contextOptions) { @@ -2149,22 +2149,21 @@ Expecting one of '${allowedValues.join("', '")}'`); }); return this; } -} -/** - * Output help information if help flags specified - * - * @param {Command} cmd - command to output help for - * @param {Array} args - array of options to search for help flags - * @api private - */ + /** + * Output help information if help flags specified + * + * @param {Array} args - array of options to search for help flags + * @private + */ -function outputHelpIfRequested(cmd, args) { - const helpOption = cmd._hasHelpOption && args.find(arg => arg === cmd._helpLongFlag || arg === cmd._helpShortFlag); - if (helpOption) { - cmd.outputHelp(); - // (Do not have all displayed text available so only passing placeholder.) - cmd._exit(0, 'commander.helpDisplayed', '(outputHelp)'); + _outputHelpIfRequested(args) { + const helpOption = this._hasHelpOption && args.find(arg => arg === this._helpLongFlag || arg === this._helpShortFlag); + if (helpOption) { + this.outputHelp(); + // (Do not have all displayed text available so only passing placeholder.) + this._exit(0, 'commander.helpDisplayed', '(outputHelp)'); + } } } @@ -2173,7 +2172,7 @@ function outputHelpIfRequested(cmd, args) { * * @param {string[]} args - array of arguments from node.execArgv * @returns {string[]} - * @api private + * @private */ function incrementNodeInspectorPort(args) { diff --git a/lib/option.js b/lib/option.js index d61fc5f2f..42f38826d 100644 --- a/lib/option.js +++ b/lib/option.js @@ -160,7 +160,7 @@ class Option { } /** - * @api private + * @package internal use only */ _concatValue(value, previous) { @@ -210,7 +210,6 @@ class Option { * as a object attribute key. * * @return {string} - * @api private */ attributeName() { @@ -222,7 +221,7 @@ class Option { * * @param {string} arg * @return {boolean} - * @api private + * @package internal use only */ is(arg) { @@ -235,7 +234,7 @@ class Option { * Options are one of boolean, negated, required argument, or optional argument. * * @return {boolean} - * @api private + * @package internal use only */ isBoolean() { @@ -295,7 +294,7 @@ class DualOptions { * * @param {string} str * @return {string} - * @api private + * @private */ function camelcase(str) { @@ -307,7 +306,7 @@ function camelcase(str) { /** * Split the short and long flag out of something like '-m,--mixed ' * - * @api private + * @private */ function splitOptionFlags(flags) {