Follow jsdoc and tsdoc more closely, especially @example (#1562)

Author: shadowspawn

lib/command.js

@@ -107,20 +107,19 @@ class Command extends EventEmitter {
    *
    * There are two styles of command: pay attention to where to put the description.
    *
-   * Examples:
-   *
-   *      // 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');
+   * @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)
@@ -201,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
@@ -289,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]
@@ -316,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
@@ -449,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
@@ -595,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]
@@ -662,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.
    */
@@ -835,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
@@ -862,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]
@@ -1256,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[]}}