commander 8.0.0 → 8.1.0

package/Readme.md

@@ -113,7 +113,7 @@ By default options on the command line are not positional, and can be specified
 ### Common option types, boolean and value
 
 The two most used option types are a boolean option, and an option which takes its value
-from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.  
+from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.
 
 Example file: [options-common.js](./examples/options-common.js)
 
@@ -426,7 +426,7 @@ program
   .addCommand(build.makeBuildCommand());
 ```
 
-Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will 
+Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will
 remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
 subcommand is specified ([example](./examples/defaultCommand.js)).
 
@@ -436,7 +436,7 @@ For subcommands, you can specify the argument syntax in the call to `.command()`
 is the only method usable for subcommands implemented using a stand-alone executable, but for other subcommands
 you can instead use the following method.
 
-To configure a command, you can use `.argument()` to specify each expected command-argument. 
+To configure a command, you can use `.argument()` to specify each expected command-argument.
 You supply the argument name and an optional description. The argument may be `<required>` or `[optional]`.
 You can specify a default value for an optional command-argument.
 
@@ -513,7 +513,7 @@ program
 ### Action handler
 
 The action handler gets passed a parameter for each command-argument you declared, and two additional parameters
-which are the parsed options and the command object itself. 
+which are the parsed options and the command object itself.
 
 Example file: [thank.js](./examples/thank.js)
 
@@ -630,7 +630,7 @@ shell spawn --help
 
 ### Custom help
 
-You can add extra text to be displayed along with the built-in help. 
+You can add extra text to be displayed along with the built-in help.
 
 Example file: [custom-help](./examples/custom-help)
 
@@ -664,7 +664,7 @@ The positions in order displayed are:
 - `after`: display extra information after built-in help
 - `afterAll`: add to the program for a global footer (epilog)
 
-The positions "beforeAll" and "afterAll" apply to the command and all its subcommands. 
+The positions "beforeAll" and "afterAll" apply to the command and all its subcommands.
 
 The second parameter can be a string, or a function returning a string. The function is passed a context object for your convenience. The properties are:
 
@@ -673,7 +673,7 @@ The second parameter can be a string, or a function returning a string. The func
 
 ### Display help after errors
 
-The default behaviour for usage errors is to just display a short error message. 
+The default behaviour for usage errors is to just display a short error message.
 You can change the behaviour to show the full help or a custom help message after an error.
 
 ```js
@@ -747,7 +747,7 @@ There are methods getting the visible lists of arguments, options, and subcomman
 
 Example file: [configure-help.js](./examples/configure-help.js)
 
-```
+```js
 program.configureHelp({
   sortSubcommands: true,
   subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
@@ -809,7 +809,7 @@ program subcommand -b
 
 By default options are recognised before and after command-arguments. To only process options that come
 before the command-arguments, use `.passThroughOptions()`. This lets you pass the  arguments and following options through to another program
-without needing to use `--` to end the option processing. 
+without needing to use `--` to end the option processing.
 To use pass through options in a subcommand, the program needs to enable positional options.
 
 Example file: [pass-through-options.js](./examples/pass-through-options.js)
@@ -826,7 +826,7 @@ By default the option processing shows an error for an unknown option. To have a
 By default the argument processing does not display an error for more command-arguments than expected.
 To display an error for excess arguments, use`.allowExcessArguments(false)`.
 
-### Legacy options as properties 
+### Legacy options as properties
 
 Before Commander 7, the option values were stored as properties on the command.
 This was convenient to code but the downside was possible clashes with
@@ -986,7 +986,7 @@ Examples:
   $ deploy exec sequential
   $ deploy exec async`
   );
-  
+
 program.parse(process.argv);
 ```
 

package/lib/argument.js

@@ -109,6 +109,22 @@ class Argument {
     };
     return this;
   };
+
+  /**
+   * Make option-argument required.
+   */
+  argRequired() {
+    this.required = true;
+    return this;
+  }
+
+  /**
+   * Make option-argument optional.
+   */
+  argOptional() {
+    this.required = false;
+    return this;
+  }
 }
 
 /**

package/lib/command.js

@@ -74,24 +74,52 @@ class Command extends EventEmitter {
   }
 
   /**
-   * Define a command.
+   * Copy settings that are useful to have in common across root command and subcommands.
    *
-   * There are two styles of command: pay attention to where to put the description.
+   * (Used internally when adding a command using `.command()` so subcommands inherit parent settings.)
    *
-   * Examples:
+   * @param {Command} sourceCommand
+   * @return {Command} returns `this` for executable command
+   */
+  copyInheritedSettings(sourceCommand) {
+    this._outputConfiguration = sourceCommand._outputConfiguration;
+    this._hasHelpOption = sourceCommand._hasHelpOption;
+    this._helpFlags = sourceCommand._helpFlags;
+    this._helpDescription = sourceCommand._helpDescription;
+    this._helpShortFlag = sourceCommand._helpShortFlag;
+    this._helpLongFlag = sourceCommand._helpLongFlag;
+    this._helpCommandName = sourceCommand._helpCommandName;
+    this._helpCommandnameAndArgs = sourceCommand._helpCommandnameAndArgs;
+    this._helpCommandDescription = sourceCommand._helpCommandDescription;
+    this._helpConfiguration = sourceCommand._helpConfiguration;
+    this._exitCallback = sourceCommand._exitCallback;
+    this._storeOptionsAsProperties = sourceCommand._storeOptionsAsProperties;
+    this._combineFlagAndOptionalValue = sourceCommand._combineFlagAndOptionalValue;
+    this._allowExcessArguments = sourceCommand._allowExcessArguments;
+    this._enablePositionalOptions = sourceCommand._enablePositionalOptions;
+    this._showHelpAfterError = sourceCommand._showHelpAfterError;
+
+    return this;
+  }
+
+  /**
+   * Define a command.
    *
-   *      // Command implemented using action handler (description is supplied separately to `.command`)
-   *      program
-   *        .command('clone <source> [destination]')
-   *        .description('clone a repository into a newly created directory')
-   *        .action((source, destination) => {
-   *          console.log('clone command called');
-   *        });
+   * There are two styles of command: pay attention to where to put the description.
    *
-   *      // Command implemented using separate executable file (description is second parameter to `.command`)
-   *      program
-   *        .command('start <service>', 'start named service')
-   *        .command('stop [service]', 'stop named service, or all if no name supplied');
+   * @example
+   * // Command implemented using action handler (description is supplied separately to `.command`)
+   * program
+   *   .command('clone <source> [destination]')
+   *   .description('clone a repository into a newly created directory')
+   *   .action((source, destination) => {
+   *     console.log('clone command called');
+   *   });
+   *
+   * // Command implemented using separate executable file (description is second parameter to `.command`)
+   * program
+   *   .command('start <service>', 'start named service')
+   *   .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)
@@ -108,37 +136,19 @@ class Command extends EventEmitter {
     }
     opts = opts || {};
     const [, name, args] = nameAndArgs.match(/([^ ]+) *(.*)/);
-    const cmd = this.createCommand(name);
 
+    const cmd = this.createCommand(name);
     if (desc) {
       cmd.description(desc);
       cmd._executableHandler = true;
     }
     if (opts.isDefault) this._defaultCommandName = cmd._name;
-
-    cmd._outputConfiguration = this._outputConfiguration;
-
     cmd._hidden = !!(opts.noHelp || opts.hidden); // noHelp is deprecated old name for hidden
-    cmd._hasHelpOption = this._hasHelpOption;
-    cmd._helpFlags = this._helpFlags;
-    cmd._helpDescription = this._helpDescription;
-    cmd._helpShortFlag = this._helpShortFlag;
-    cmd._helpLongFlag = this._helpLongFlag;
-    cmd._helpCommandName = this._helpCommandName;
-    cmd._helpCommandnameAndArgs = this._helpCommandnameAndArgs;
-    cmd._helpCommandDescription = this._helpCommandDescription;
-    cmd._helpConfiguration = this._helpConfiguration;
-    cmd._exitCallback = this._exitCallback;
-    cmd._storeOptionsAsProperties = this._storeOptionsAsProperties;
-    cmd._combineFlagAndOptionalValue = this._combineFlagAndOptionalValue;
-    cmd._allowExcessArguments = this._allowExcessArguments;
-    cmd._enablePositionalOptions = this._enablePositionalOptions;
-    cmd._showHelpAfterError = this._showHelpAfterError;
-
     cmd._executableFile = opts.executableFile || null; // Custom name for executable file, set missing to null to match constructor
     if (args) cmd.arguments(args);
     this.commands.push(cmd);
     cmd.parent = this;
+    cmd.copyInheritedSettings(this);
 
     if (desc) return this;
     return cmd;
@@ -190,14 +200,14 @@ class Command extends EventEmitter {
    *
    * The configuration properties are all functions:
    *
-   *    // functions to change where being written, stdout and stderr
-   *    writeOut(str)
-   *    writeErr(str)
-   *    // matching functions to specify width for wrapping help
-   *    getOutHelpWidth()
-   *    getErrHelpWidth()
-   *    // functions based on what is being written out
-   *    outputError(str, write) // used for displaying errors, and not used for displaying help
+   *     // functions to change where being written, stdout and stderr
+   *     writeOut(str)
+   *     writeErr(str)
+   *     // matching functions to specify width for wrapping help
+   *     getOutHelpWidth()
+   *     getErrHelpWidth()
+   *     // 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
@@ -278,9 +288,8 @@ class Command extends EventEmitter {
    * indicate this with <> around the name. Put [] around the name for an optional argument.
    *
    * @example
-   *
-   *     program.argument('<input-file>');
-   *     program.argument('[output-file]');
+   * program.argument('<input-file>');
+   * program.argument('[output-file]');
    *
    * @param {string} name
    * @param {string} [description]
@@ -305,8 +314,7 @@ class Command extends EventEmitter {
    * See also .argument().
    *
    * @example
-   *
-   *     program.arguments('<cmd> [env]');
+   * program.arguments('<cmd> [env]');
    *
    * @param {string} names
    * @return {Command} `this` command for chaining
@@ -438,14 +446,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Register callback `fn` for the command.
    *
-   * Examples:
-   *
-   *      program
-   *        .command('help')
-   *        .description('display verbose help')
-   *        .action(function() {
-   *           // output help here
-   *        });
+   * @example
+   * program
+   *   .command('help')
+   *   .description('display verbose help')
+   *   .action(function() {
+   *      // output help here
+   *   });
    *
    * @param {Function} fn
    * @return {Command} `this` command for chaining
@@ -584,41 +591,40 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * separated by comma, a pipe or space. The following are all valid
    * all will output this way when `--help` is used.
    *
-   *    "-p, --pepper"
-   *    "-p|--pepper"
-   *    "-p --pepper"
-   *
-   * Examples:
+   *     "-p, --pepper"
+   *     "-p|--pepper"
+   *     "-p --pepper"
    *
-   *     // simple boolean defaulting to undefined
-   *     program.option('-p, --pepper', 'add pepper');
+   * @example
+   * // simple boolean defaulting to undefined
+   * program.option('-p, --pepper', 'add pepper');
    *
-   *     program.pepper
-   *     // => undefined
+   * program.pepper
+   * // => undefined
    *
-   *     --pepper
-   *     program.pepper
-   *     // => true
+   * --pepper
+   * program.pepper
+   * // => true
    *
-   *     // simple boolean defaulting to true (unless non-negated option is also defined)
-   *     program.option('-C, --no-cheese', 'remove cheese');
+   * // simple boolean defaulting to true (unless non-negated option is also defined)
+   * program.option('-C, --no-cheese', 'remove cheese');
    *
-   *     program.cheese
-   *     // => true
+   * program.cheese
+   * // => true
    *
-   *     --no-cheese
-   *     program.cheese
-   *     // => false
+   * --no-cheese
+   * program.cheese
+   * // => false
    *
-   *     // required argument
-   *     program.option('-C, --chdir <path>', 'change the working directory');
+   * // required argument
+   * program.option('-C, --chdir <path>', 'change the working directory');
    *
-   *     --chdir /tmp
-   *     program.chdir
-   *     // => "/tmp"
+   * --chdir /tmp
+   * program.chdir
+   * // => "/tmp"
    *
-   *     // optional argument
-   *     program.option('-c, --cheese [type]', 'add cheese [marble]');
+   * // optional argument
+   * program.option('-c, --cheese [type]', 'add cheese [marble]');
    *
    * @param {string} flags
    * @param {string} [description]
@@ -651,11 +657,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Alter parsing of short flags with optional values.
    *
-   * Examples:
-   *
-   *    // for `.option('-f,--flag [value]'):
-   *    .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
-   *    .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
+   * @example
+   * // for `.option('-f,--flag [value]'):
+   * 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.
    */
@@ -824,11 +829,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * The default expectation is that the arguments are from node and have the application as argv[0]
    * and the script being run in argv[1], with user parameters after that.
    *
-   * Examples:
-   *
-   *      program.parse(process.argv);
-   *      program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * @example
+   * program.parse(process.argv);
+   * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
    *
    * @param {string[]} [argv] - optional, defaults to process.argv
    * @param {Object} [parseOptions] - optionally specify style of options with from: node/user/electron
@@ -851,11 +855,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * The default expectation is that the arguments are from node and have the application as argv[0]
    * and the script being run in argv[1], with user parameters after that.
    *
-   * Examples:
-   *
-   *      await program.parseAsync(process.argv);
-   *      await program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      await program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * @example
+   * await program.parseAsync(process.argv);
+   * await program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * await program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
    *
    * @param {string[]} [argv]
    * @param {Object} [parseOptions]
@@ -1245,11 +1248,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *
    * Examples:
    *
-   *    argv => operands, unknown
-   *    --known kkk op => [op], []
-   *    op --known kkk => [op], []
-   *    sub --unknown uuu op => [sub], [--unknown uuu op]
-   *    sub -- --unknown uuu op => [sub --unknown uuu op], []
+   *     argv => operands, unknown
+   *     --known kkk op => [op], []
+   *     op --known kkk => [op], []
+   *     sub --unknown uuu op => [sub], [--unknown uuu op]
+   *     sub -- --unknown uuu op => [sub --unknown uuu op], []
    *
    * @param {String[]} argv
    * @return {{operands: String[], unknown: String[]}}
@@ -1659,14 +1662,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     const context = this._getHelpContext(contextOptions);
 
-    const groupListeners = [];
-    let command = this;
-    while (command) {
-      groupListeners.push(command); // ordered from current command to root
-      command = command.parent;
-    }
-
-    groupListeners.slice().reverse().forEach(command => command.emit('beforeAllHelp', context));
+    getCommandAndParents(this).reverse().forEach(command => command.emit('beforeAllHelp', context));
     this.emit('beforeHelp', context);
 
     let helpInformation = this.helpInformation(context);
@@ -1680,7 +1676,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
     this.emit(this._helpLongFlag); // deprecated
     this.emit('afterHelp', context);
-    groupListeners.forEach(command => command.emit('afterAllHelp', context));
+    getCommandAndParents(this).forEach(command => command.emit('afterAllHelp', context));
   };
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",

package/typings/index.d.ts

@@ -13,9 +13,9 @@ export 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
+   * @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);
@@ -24,7 +24,7 @@ export class CommanderError extends Error {
 export class InvalidArgumentError extends CommanderError {
   /**
    * Constructs the InvalidArgumentError class
-   * @param {string} [message] explanation of why argument is invalid
+   * @param message - explanation of why argument is invalid
    * @constructor
    */
   constructor(message: string);
@@ -40,9 +40,6 @@ export class Argument {
    * Initialize a new command argument with the given name and description.
    * The default is that the argument is required, and you can explicitly
    * indicate this with <> around the name. Put [] around the name for an optional argument.
-   *
-   * @param {string} name
-   * @param {string} [description]
    */
   constructor(arg: string, description?: string);
 
@@ -66,6 +63,15 @@ export class Argument {
    */
    choices(values: string[]): this;
 
+  /**
+   * Make option-argument required.
+   */
+   argRequired(): this;
+
+  /**
+   * Make option-argument optional.
+   */
+  argOptional(): this;
   }
 
 export class Option {
@@ -241,12 +247,12 @@ export class Command {
    *
    * @example
    * ```ts
-   *  program
-   *    .command('clone <source> [destination]')
-   *    .description('clone a repository into a newly created directory')
-   *    .action((source, destination) => {
-   *      console.log('clone command called');
-   *    });
+   * program
+   *   .command('clone <source> [destination]')
+   *   .description('clone a repository into a newly created directory')
+   *   .action((source, destination) => {
+   *     console.log('clone command called');
+   *   });
    * ```
    *
    * @param nameAndArgs - command name and arguments, args are  `<required>` or `[optional]` and last may also be `variadic...`
@@ -306,9 +312,10 @@ export class Command {
    * indicate this with <> around the name. Put [] around the name for an optional argument.
    *
    * @example
-   *
-   *     program.argument('<input-file>');
-   *     program.argument('[output-file]');
+   * ```
+   * program.argument('<input-file>');
+   * program.argument('[output-file]');
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -328,8 +335,9 @@ export class Command {
    * See also .argument().
    *
    * @example
-   *
-   *     program.arguments('<cmd> [env]');
+   * ```
+   * program.arguments('<cmd> [env]');
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -338,9 +346,12 @@ export class Command {
   /**
    * Override default decision whether to add implicit help command.
    *
-   *    addHelpCommand() // force on
-   *    addHelpCommand(false); // force off
-   *    addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
+   * @example
+   * ```
+   * addHelpCommand() // force on
+   * addHelpCommand(false); // force off
+   * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -375,20 +386,28 @@ export class Command {
    * applications. You can also customise the display of errors by overriding outputError.
    *
    * The configuration properties are all functions:
-   *
-   *    // functions to change where being written, stdout and stderr
-   *    writeOut(str)
-   *    writeErr(str)
-   *    // matching functions to specify width for wrapping help
-   *    getOutHelpWidth()
-   *    getErrHelpWidth()
-   *    // functions based on what is being written out
-   *    outputError(str, write) // used for displaying errors, and not used for displaying help
+   * ```
+   * // functions to change where being written, stdout and stderr
+   * writeOut(str)
+   * writeErr(str)
+   * // matching functions to specify width for wrapping help
+   * getOutHelpWidth()
+   * getErrHelpWidth()
+   * // functions based on what is being written out
+   * outputError(str, write) // used for displaying errors, and not used for displaying help
+   * ```
    */
   configureOutput(configuration: OutputConfiguration): this;
   /** Get configuration */
   configureOutput(): OutputConfiguration;
 
+  /**
+   * Copy settings that are useful to have in common across root command and subcommands.
+   *
+   * (Used internally when adding a command using `.command()` so subcommands inherit parent settings.)
+   */
+   copyInheritedSettings(sourceCommand: Command): this;
+
   /**
    * Display the help or a custom message after an error occurs.
    */
@@ -398,12 +417,14 @@ export class Command {
    * Register callback `fn` for the command.
    *
    * @example
-   *      program
-   *        .command('help')
-   *        .description('display verbose help')
-   *        .action(function() {
-   *           // output help here
-   *        });
+   * ```
+   * program
+   *   .command('help')
+   *   .description('display verbose help')
+   *   .action(function() {
+   *     // output help here
+   *   });
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -417,37 +438,39 @@ export class Command {
    * separated by comma, a pipe or space. The following are all valid
    * all will output this way when `--help` is used.
    *
-   *    "-p, --pepper"
-   *    "-p|--pepper"
-   *    "-p --pepper"
+   *     "-p, --pepper"
+   *     "-p|--pepper"
+   *     "-p --pepper"
    *
    * @example
-   *     // simple boolean defaulting to false
-   *     program.option('-p, --pepper', 'add pepper');
+   * ```
+   * // simple boolean defaulting to false
+   *  program.option('-p, --pepper', 'add pepper');
    *
-   *     --pepper
-   *     program.pepper
-   *     // => Boolean
+   *  --pepper
+   *  program.pepper
+   *  // => Boolean
    *
-   *     // simple boolean defaulting to true
-   *     program.option('-C, --no-cheese', 'remove cheese');
+   *  // simple boolean defaulting to true
+   *  program.option('-C, --no-cheese', 'remove cheese');
    *
-   *     program.cheese
-   *     // => true
+   *  program.cheese
+   *  // => true
    *
-   *     --no-cheese
-   *     program.cheese
-   *     // => false
+   *  --no-cheese
+   *  program.cheese
+   *  // => false
    *
-   *     // required argument
-   *     program.option('-C, --chdir <path>', 'change the working directory');
+   *  // required argument
+   *  program.option('-C, --chdir <path>', 'change the working directory');
    *
-   *     --chdir /tmp
-   *     program.chdir
-   *     // => "/tmp"
+   *  --chdir /tmp
+   *  program.chdir
+   *  // => "/tmp"
    *
-   *     // optional argument
-   *     program.option('-c, --cheese [type]', 'add cheese [marble]');
+   *  // optional argument
+   *  program.option('-c, --cheese [type]', 'add cheese [marble]');
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -507,9 +530,11 @@ export class Command {
    * Alter parsing of short flags with optional values.
    *
    * @example
-   *    // for `.option('-f,--flag [value]'):
-   *   .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
-   *   .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
+   * ```
+   * // for `.option('-f,--flag [value]'):
+   * .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
+   * .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -556,11 +581,12 @@ export class Command {
    * The default expectation is that the arguments are from node and have the application as argv[0]
    * and the script being run in argv[1], with user parameters after that.
    *
-   * Examples:
-   *
-   *      program.parse(process.argv);
-   *      program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * @example
+   * ```
+   * program.parse(process.argv);
+   * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -574,11 +600,12 @@ export class Command {
    * The default expectation is that the arguments are from node and have the application as argv[0]
    * and the script being run in argv[1], with user parameters after that.
    *
-   * Examples:
-   *
-   *      program.parseAsync(process.argv);
-   *      program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * @example
+   * ```
+   * program.parseAsync(process.argv);
+   * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * ```
    *
    * @returns Promise
    */
@@ -588,12 +615,11 @@ export class Command {
    * Parse options from `argv` removing known options,
    * and return argv split into operands and unknown arguments.
    *
-   * @example
-   *    argv => operands, unknown
-   *    --known kkk op => [op], []
-   *    op --known kkk => [op], []
-   *    sub --unknown uuu op => [sub], [--unknown uuu op]
-   *    sub -- --unknown uuu op => [sub --unknown uuu op], []
+   *     argv => operands, unknown
+   *     --known kkk op => [op], []
+   *     op --known kkk => [op], []
+   *     sub --unknown uuu op => [sub], [--unknown uuu op]
+   *     sub -- --unknown uuu op => [sub --unknown uuu op], []
    */
   parseOptions(argv: string[]): ParseOptionsResult;