More consistent way of adding command arguments

CHANGELOG.md

@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
-## [7.2.0] (2021-03-26)
+## [7.2.0] (2021-03-22)
 
 ### Added
 

Readme.md

@@ -428,27 +428,34 @@ subcommand is specified ([example](./examples/defaultCommand.js)).
 
 ### Specify the argument syntax
 
-You use `.arguments` to specify the expected command-arguments for the top-level command, and for subcommands they are usually
-included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required command-arguments.
-Square brackets (e.g. `[optional]`) indicate optional command-arguments.
-You can optionally describe the arguments in the help by supplying a hash as second parameter to `.description()`.
+You use `.argument` to specify the expected command-arguments.
+Angle brackets around the name indicate a required command-argument (e.g. `<required>`).
+Square brackets indicate an optional command-argument (e.g. `[optional]`). The description parameter is optional.
 
-Example file: [arguments.js](./examples/arguments.js)
+Example file: [argument.js](./examples/argument.js)
 
 ```js
 program
   .version('0.1.0')
-  .arguments('<username> [password]')
-  .description('test command', {
-    username: 'user to login',
-    password: 'password for user, if required'
-  })
+  .argument('<username>', 'user to login')
+  .argument('[password]', 'password for user, if required')
   .action((username, password) => {
     console.log('username:', username);
-    console.log('environment:', password || 'no password given');
+    console.log('password:', password || 'no password given');
   });
 ```
 
+There are two ways to specify all the arguments at once, but these do not allow argument descriptions.
+
+```js
+program
+  .command('add <number> <number>');
+
+program
+  .command('fraction')
+  .arguments('<numerator> <denominator>');
+```
+
  The last argument of a command can be variadic, and only the last argument.  To make an argument variadic you
  append `...` to the argument name. For example:
 
@@ -463,7 +470,7 @@ program
   });
 ```
 
-The variadic argument is passed to the action handler as an array.
+A variadic argument is passed to the action handler as an array.
 
 ### Action handler
 
@@ -474,7 +481,7 @@ Example file: [thank.js](./examples/thank.js)
 
 ```js
 program
-  .arguments('<name>')
+  .argument('<name>')
   .option('-t, --title <honorific>', 'title to use before name')
   .option('-d, --debug', 'display some debugging')
   .action((name, options, command) => {

docs/deprecated.md

@@ -86,3 +86,28 @@ Examples:
 ```
 
 Deprecated from Commander v7. 
+
+## cmd.description(cmdDescription, argDescriptions)
+
+This was used to add command argument descriptions for the help.
+
+```js
+program
+  .command('price <book>')
+  .description('show price of book', {
+    book: 'ISBN number for book'
+  });
+```
+
+The new approach is to use the `.argument()` method.
+
+```js
+program
+  .command('price')
+  .description('show price of book')
+  .argument('<book>', 'ISBN number for book');
+```
+
+
+Deprecated from Commander v8.
+

docs/options-taking-varying-arguments.md

@@ -5,7 +5,7 @@ and subtle issues in depth.
 
 - [Options taking varying numbers of option-arguments](#options-taking-varying-numbers-of-option-arguments)
   - [Parsing ambiguity](#parsing-ambiguity)
-    - [Alternative: Make  `--` part of your syntax](#alternative-make----part-of-your-syntax)
+    - [Alternative: Make  `--` part of your syntax](#alternative-make-----part-of-your-syntax)
     - [Alternative: Put options last](#alternative-put-options-last)
     - [Alternative: Use options instead of command-arguments](#alternative-use-options-instead-of-command-arguments)
   - [Combining short options, and options taking arguments](#combining-short-options-and-options-taking-arguments)
@@ -34,7 +34,7 @@ intend the argument following the option as a command or command-argument.
 ```js
 program
   .name('cook')
-  .arguments('[technique]')
+  .argument('[technique]')
   .option('-i, --ingredient [ingredient]', 'add cheese or given ingredient')
   .action((technique, options) => {
     console.log(`technique: ${technique}`);

docs/zh-CN/可变参数的选项.md

@@ -31,7 +31,7 @@ Commander 首先解析选项的参数，而用户有可能想将选项后面跟
 ```js
 program
   .name('cook')
-  .arguments('[technique]')
+  .argument('[technique]')
   .option('-i, --ingredient [ingredient]', 'add cheese or given ingredient')
   .action((technique, options) => {
     console.log(`technique: ${technique}`);
@@ -190,4 +190,4 @@ halal servings: true
 ```js
 .combineFlagAndOptionalValue(true)  // `-v45` 被视为 `--vegan=45`，这是默认的行为
 .combineFlagAndOptionalValue(false) // `-vl` 被视为 `-v -l`
-```
+```

examples/argument.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+// This example shows specifying the arguments using argument() function.
+
+// const { Command } = require('commander'); // (normal include)
+const { Command } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
+
+program
+  .version('0.1.0')
+  .argument('<username>', 'user to login')
+  .argument('[password]', 'password for user, if required')
+  .description('example program for argument')
+  .action((username, password) => {
+    console.log('username:', username);
+    console.log('password:', password || 'no password given');
+  });
+
+program.parse();
+
+// Try the following:
+//    node arguments.js --help
+//    node arguments.js user
+//    node arguments.js user secret

examples/arguments.js

@@ -15,7 +15,7 @@ program
   })
   .action((username, password) => {
     console.log('username:', username);
-    console.log('environment:', password || 'no password given');
+    console.log('password:', password || 'no password given');
   });
 
 program.parse();

examples/pass-through-options.js

@@ -5,7 +5,8 @@ const { Command } = require('../'); // include commander in git clone of command
 const program = new Command();
 
 program
-  .arguments('<utility> [args...]')
+  .argument('<utility>')
+  .argument('[args...]')
   .passThroughOptions()
   .option('-d, --dry-run')
   .action((utility, args, options) => {

examples/thank.js

@@ -7,7 +7,7 @@ const { Command } = require('../'); // include commander in git clone of command
 const program = new Command();
 
 program
-  .arguments('<name>')
+  .argument('<name>')
   .option('-t, --title <honorific>', 'title to use before name')
   .option('-d, --debug', 'display some debugging')
   .action((name, options, command) => {