Skip to content

Commit

Permalink
Follow jsdoc and tsdoc more closely, especially @example (#1562)
Browse files Browse the repository at this point in the history
  • Loading branch information
@shadowspawn
shadowspawn committed Jul 9, 2021
1 parent 5517d25 commit 56c4108
Show file tree
Hide file tree
Showing 2 changed files with 160 additions and 158 deletions.
154 changes: 73 additions & 81 deletions lib/command.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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]
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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
Expand All @@ -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]
Expand Down Expand Up @@ -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[]}}
Expand Down

0 comments on commit 56c4108

Please sign in to comment.