From 5076dda8500cbeef5b2e82c1546ac874364c581b Mon Sep 17 00:00:00 2001
From: John Gee <john@ruru.gen.nz>
Date: Fri, 11 Sep 2020 21:14:53 +1200
Subject: [PATCH] Document and test description of arguments (#1353)

* Add test for command-arguments description in help

* Remove blank line after Arguments: to match Options and Commands

* Add argument decription to README and example

* Put back extra line so no chnage in code
---
 Readme.md                  |  5 +++++
 examples/env               |  9 +++++++++
 tests/command.help.test.js | 19 +++++++++++++++++++
 3 files changed, 33 insertions(+)

diff --git a/Readme.md b/Readme.md
index c44f2ccb2..a809dea3b 100644
--- a/Readme.md
+++ b/Readme.md
@@ -368,6 +368,7 @@ Configuration options can be passed with the call to `.command()` and `.addComma
 ### Specify the argument syntax
 
 You use `.arguments` to specify the arguments for the top-level command, and for subcommands they are usually included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required input. Square brackets (e.g. `[optional]`) indicate optional input.
+You can optionally describe the arguments in the help by supplying a hash as second parameter to `.description()`.
 
 Example file: [env](./examples/env)
 
@@ -375,6 +376,10 @@ Example file: [env](./examples/env)
 program
   .version('0.1.0')
   .arguments('<cmd> [env]')
+  .description('test command', {
+    cmd: 'command to run',
+    env: 'environment to run test in'
+  })
   .action(function (cmd, env) {
     console.log('command:', cmd);
     console.log('environment:', env || 'no environment given');
diff --git a/examples/env b/examples/env
index ba91bfdc4..836a72c13 100755
--- a/examples/env
+++ b/examples/env
@@ -12,9 +12,18 @@ let envValue;
 program
   .version('0.0.1')
   .arguments('<cmd> [env]')
+  .description('test command', {
+    cmd: 'command to run',
+    env: 'environment to run test in'
+  })
   .action(function(cmdValue, envValue) {
     console.log('command:', cmdValue);
     console.log('environment:', envValue || 'no environment given');
   });
 
 program.parse(process.argv);
+
+// Try the following:
+//    node env --help
+//    node env add
+//    node env add browser
diff --git a/tests/command.help.test.js b/tests/command.help.test.js
index c2ed34b3c..32c58b329 100644
--- a/tests/command.help.test.js
+++ b/tests/command.help.test.js
@@ -139,3 +139,22 @@ test('when no options then Options not includes in helpInformation', () => {
   const helpInformation = program.helpInformation();
   expect(helpInformation).not.toMatch('Options');
 });
+
+test('when arguments then included in helpInformation', () => {
+  const program = new commander.Command();
+  program
+    .name('foo')
+    .arguments('<file>');
+  const helpInformation = program.helpInformation();
+  expect(helpInformation).toMatch('Usage: foo [options] <file>');
+});
+
+test('when arguments described then included in helpInformation', () => {
+  const program = new commander.Command();
+  program
+    .arguments('<file>')
+    .helpOption(false)
+    .description('description', { file: 'input source' });
+  const helpInformation = program.helpInformation();
+  expect(helpInformation).toMatch(/Arguments:\n\n +file +input source/); // [sic], extra line
+});