Skip to content

Commit e85e05a

Browse files
authored
Rework option inline doc (#2009)
1 parent c7d39ca commit e85e05a

File tree

2 files changed

+27
-79
lines changed

2 files changed

+27
-79
lines changed

lib/command.js

Lines changed: 15 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -632,57 +632,29 @@ Expecting one of '${allowedValues.join("', '")}'`);
632632
}
633633

634634
/**
635-
* Define option with `flags`, `description` and optional
636-
* coercion `fn`.
635+
* Define option with `flags`, `description`, and optional argument parsing function or `defaultValue` or both.
637636
*
638-
* The `flags` string contains the short and/or long flags,
639-
* separated by comma, a pipe or space. The following are all valid
640-
* all will output this way when `--help` is used.
637+
* The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. A required
638+
* option-argument is indicated by `<>` and an optional option-argument by `[]`.
641639
*
642-
* "-p, --pepper"
643-
* "-p|--pepper"
644-
* "-p --pepper"
640+
* See the README for more details, and see also addOption() and requiredOption().
645641
*
646642
* @example
647-
* // simple boolean defaulting to undefined
648-
* program.option('-p, --pepper', 'add pepper');
649-
*
650-
* program.pepper
651-
* // => undefined
652-
*
653-
* --pepper
654-
* program.pepper
655-
* // => true
656-
*
657-
* // simple boolean defaulting to true (unless non-negated option is also defined)
658-
* program.option('-C, --no-cheese', 'remove cheese');
659-
*
660-
* program.cheese
661-
* // => true
662-
*
663-
* --no-cheese
664-
* program.cheese
665-
* // => false
666-
*
667-
* // required argument
668-
* program.option('-C, --chdir <path>', 'change the working directory');
669-
*
670-
* --chdir /tmp
671-
* program.chdir
672-
* // => "/tmp"
673-
*
674-
* // optional argument
675-
* program.option('-c, --cheese [type]', 'add cheese [marble]');
643+
* program
644+
* .option('-p, --pepper', 'add pepper')
645+
* .option('-p, --pizza-type <TYPE>', 'type of pizza') // required option-argument
646+
* .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default
647+
* .option('-t, --tip <VALUE>', 'add tip to purchase cost', parseFloat) // custom parse function
676648
*
677649
* @param {string} flags
678650
* @param {string} [description]
679-
* @param {Function|*} [fn] - custom option processing function or default value
651+
* @param {Function|*} [parseArg] - custom option processing function or default value
680652
* @param {*} [defaultValue]
681653
* @return {Command} `this` command for chaining
682654
*/
683655

684-
option(flags, description, fn, defaultValue) {
685-
return this._optionEx({}, flags, description, fn, defaultValue);
656+
option(flags, description, parseArg, defaultValue) {
657+
return this._optionEx({}, flags, description, parseArg, defaultValue);
686658
}
687659

688660
/**
@@ -693,13 +665,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
693665
*
694666
* @param {string} flags
695667
* @param {string} [description]
696-
* @param {Function|*} [fn] - custom option processing function or default value
668+
* @param {Function|*} [parseArg] - custom option processing function or default value
697669
* @param {*} [defaultValue]
698670
* @return {Command} `this` command for chaining
699671
*/
700672

701-
requiredOption(flags, description, fn, defaultValue) {
702-
return this._optionEx({ mandatory: true }, flags, description, fn, defaultValue);
673+
requiredOption(flags, description, parseArg, defaultValue) {
674+
return this._optionEx({ mandatory: true }, flags, description, parseArg, defaultValue);
703675
}
704676

705677
/**

typings/index.d.ts

Lines changed: 12 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -510,51 +510,27 @@ export class Command {
510510
action(fn: (...args: any[]) => void | Promise<void>): this;
511511

512512
/**
513-
* Define option with `flags`, `description` and optional
514-
* coercion `fn`.
513+
* Define option with `flags`, `description`, and optional argument parsing function or `defaultValue` or both.
515514
*
516-
* The `flags` string contains the short and/or long flags,
517-
* separated by comma, a pipe or space. The following are all valid
518-
* all will output this way when `--help` is used.
515+
* The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. A required
516+
* option-argument is indicated by `<>` and an optional option-argument by `[]`.
519517
*
520-
* "-p, --pepper"
521-
* "-p|--pepper"
522-
* "-p --pepper"
518+
* See the README for more details, and see also addOption() and requiredOption().
523519
*
524520
* @example
525-
* ```
526-
* // simple boolean defaulting to false
527-
* program.option('-p, --pepper', 'add pepper');
528-
*
529-
* --pepper
530-
* program.pepper
531-
* // => Boolean
532-
*
533-
* // simple boolean defaulting to true
534-
* program.option('-C, --no-cheese', 'remove cheese');
535-
*
536-
* program.cheese
537-
* // => true
538521
*
539-
* --no-cheese
540-
* program.cheese
541-
* // => false
542-
*
543-
* // required argument
544-
* program.option('-C, --chdir <path>', 'change the working directory');
545-
*
546-
* --chdir /tmp
547-
* program.chdir
548-
* // => "/tmp"
549-
*
550-
* // optional argument
551-
* program.option('-c, --cheese [type]', 'add cheese [marble]');
522+
* ```js
523+
* program
524+
* .option('-p, --pepper', 'add pepper')
525+
* .option('-p, --pizza-type <TYPE>', 'type of pizza') // required option-argument
526+
* .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default
527+
* .option('-t, --tip <VALUE>', 'add tip to purchase cost', parseFloat) // custom parse function
552528
* ```
553529
*
554530
* @returns `this` command for chaining
555531
*/
556532
option(flags: string, description?: string, defaultValue?: string | boolean | string[]): this;
557-
option<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
533+
option<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this;
558534
/** @deprecated since v7, instead use choices or a custom function */
559535
option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this;
560536

@@ -565,7 +541,7 @@ export class Command {
565541
* The `flags` string contains the short and/or long flags, separated by comma, a pipe or space.
566542
*/
567543
requiredOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): this;
568-
requiredOption<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
544+
requiredOption<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this;
569545
/** @deprecated since v7, instead use choices or a custom function */
570546
requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this;
571547

0 commit comments

Comments
 (0)