Skip to content

Commit cc2db5b

Browse files
authoredMay 18, 2022
Add optional summary for short form of subcommand description. (#1726)
For backwards compatibility, the description is used for the subcommand listing if the summary is missing. So by default there is no change in existing programs.
1 parent d660967 commit cc2db5b

8 files changed

+97
-26
lines changed
 

‎Readme.md

+18-2
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
3535
- [Display help from code](#display-help-from-code)
3636
- [.name](#name)
3737
- [.usage](#usage)
38+
- [.description and .summary](#description-and-summary)
3839
- [.helpOption(flags, description)](#helpoptionflags-description)
3940
- [.addHelpCommand()](#addhelpcommand)
4041
- [More configuration](#more-configuration-2)
@@ -814,10 +815,11 @@ error: unknown option '--unknown'
814815
(add --help for additional information)
815816
```
816817

817-
You can also show suggestions after an error for an unknown command or option.
818+
The default behaviour is to suggest correct spelling after an error for an unknown command or option. You
819+
can disable this.
818820

819821
```js
820-
program.showSuggestionAfterError();
822+
program.showSuggestionAfterError(false);
821823
```
822824

823825
```console
@@ -866,6 +868,20 @@ The help will start with:
866868
Usage: my-command [global options] command
867869
```
868870

871+
### .description and .summary
872+
873+
The description appears in the help for the command. You can optionally supply a shorter
874+
summary to use when listed as a subcommand of the program.
875+
876+
```js
877+
program
878+
.command("duplicate")
879+
.summary("make a copy")
880+
.description(`Make a copy of the current project.
881+
This may require additional disk space.
882+
`);
883+
```
884+
869885
### .helpOption(flags, description)
870886

871887
By default every command has a help option. You may change the default help flags and description. Pass false to disable the built-in help option.

‎lib/command.js

+14-1
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ class Command extends EventEmitter {
4848
this._aliases = [];
4949
this._combineFlagAndOptionalValue = true;
5050
this._description = '';
51+
this._summary = '';
5152
this._argsDescription = undefined; // legacy
5253
this._enablePositionalOptions = false;
5354
this._passThroughOptions = false;
@@ -1767,7 +1768,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
17671768
}
17681769

17691770
/**
1770-
* Set the description to `str`.
1771+
* Set the description.
17711772
*
17721773
* @param {string} [str]
17731774
* @param {Object} [argsDescription]
@@ -1782,6 +1783,18 @@ Expecting one of '${allowedValues.join("', '")}'`);
17821783
return this;
17831784
}
17841785

1786+
/**
1787+
* Set the summary. Used when listed as subcommand of parent.
1788+
*
1789+
* @param {string} [str]
1790+
* @return {string|Command}
1791+
*/
1792+
summary(str) {
1793+
if (str === undefined) return this._summary;
1794+
this._summary = str;
1795+
return this;
1796+
}
1797+
17851798
/**
17861799
* Set an alias for the command.
17871800
*

‎lib/help.js

+3-2
Original file line numberDiff line numberDiff line change
@@ -215,15 +215,16 @@ class Help {
215215
}
216216

217217
/**
218-
* Get the command description to show in the list of subcommands.
218+
* Get the subcommand summary to show in the list of subcommands.
219+
* (Fallback to description for backwards compatiblity.)
219220
*
220221
* @param {Command} cmd
221222
* @returns {string}
222223
*/
223224

224225
subcommandDescription(cmd) {
225226
// @ts-ignore: overloaded return type
226-
return cmd.description();
227+
return cmd.summary() || cmd.description();
227228
}
228229

229230
/**

‎tests/command.summary.test.js

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
const commander = require('../');
2+
3+
test('when set summary then get summary', () => {
4+
const program = new commander.Command();
5+
const summary = 'abcdef';
6+
program.summary(summary);
7+
expect(program.summary()).toMatch(summary);
8+
});

‎tests/help.commandDescription.test.js

-20
This file was deleted.
+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
const commander = require('../');
2+
3+
// These are tests of the Help class, not of the Command help.
4+
// There is some overlap with the higher level Command tests (which predate Help).
5+
6+
describe('subcommandDescription', () => {
7+
test('when program has no summary or description then empty string', () => {
8+
const program = new commander.Command();
9+
const helper = new commander.Help();
10+
expect(helper.subcommandDescription(program)).toEqual('');
11+
});
12+
13+
test('when program has summary then return summary', () => {
14+
const summary = 'summary';
15+
const program = new commander.Command();
16+
program.summary(summary);
17+
const helper = new commander.Help();
18+
expect(helper.subcommandDescription(program)).toEqual(summary);
19+
});
20+
21+
test('when program has description then return description', () => {
22+
const description = 'description';
23+
const program = new commander.Command();
24+
program.description(description);
25+
const helper = new commander.Help();
26+
expect(helper.subcommandDescription(program)).toEqual(description);
27+
});
28+
29+
test('when program has summary and description then return summary', () => {
30+
const summary = 'summary';
31+
const program = new commander.Command();
32+
program.summary(summary);
33+
program.description('description');
34+
const helper = new commander.Help();
35+
expect(helper.subcommandDescription(program)).toEqual(summary);
36+
});
37+
});

‎typings/index.d.ts

+13-1
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ export class Help {
202202

203203
/** Get the command term to show in the list of subcommands. */
204204
subcommandTerm(cmd: Command): string;
205-
/** Get the command description to show in the list of subcommands. */
205+
/** Get the command summary to show in the list of subcommands. */
206206
subcommandDescription(cmd: Command): string;
207207
/** Get the option term to show in the list of options. */
208208
optionTerm(option: Option): string;
@@ -718,6 +718,18 @@ export class Command {
718718
*/
719719
description(): string;
720720

721+
/**
722+
* Set the summary. Used when listed as subcommand of parent.
723+
*
724+
* @returns `this` command for chaining
725+
*/
726+
727+
summary(str: string): this;
728+
/**
729+
* Get the summary.
730+
*/
731+
summary(): string;
732+
721733
/**
722734
* Set an alias for the command.
723735
*

‎typings/index.test-d.ts

+4
Original file line numberDiff line numberDiff line change
@@ -239,6 +239,10 @@ expectType<commander.Command>(program.description('my description'));
239239
expectType<string>(program.description());
240240
expectType<commander.Command>(program.description('my description of command with arg foo', { foo: 'foo description' })); // deprecated
241241

242+
// summary
243+
expectType<commander.Command>(program.summary('my summary'));
244+
expectType<string>(program.summary());
245+
242246
// alias
243247
expectType<commander.Command>(program.alias('my alias'));
244248
expectType<string>(program.alias());

0 commit comments

Comments
 (0)
Please sign in to comment.