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

@@ -368,13 +368,18 @@ 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)
 
 ```js
 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');

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

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
+});