Triage: Confusion between action and executable command handlers

[shadowspawn]

There is a silent change in behaviour based on whether a description parameter is added to the .command definition. This is a common cause of confusion. Opened this issue to collect the related issues found during triage.

Issues:

• Having a lot of difficulty getting nested commands #511 Having a lot of difficulty getting nested commands
• Subcommand not registered if no description provided during the setup #633 Subcommand not registered if no description provided during the setup
• executeSubCommand() shouldn't be called if I provide action #706 executeSubCommand() shouldn't be called if I provide action
• Specifying command description forces lookup of command in separate file #715 Specifying command description forces lookup of command in separate file
• Handle git-style commands programmatically #767 Handle git-style commands programmatically
• Having multiple commands with .action() fires all of the command's actions. #770 Having multiple commands with .action() fires all of the command's actions.
• Make it clear that you can't pipe action to command that was invoked with description #776 Make it clear that you can't pipe action to command that was invoked with description
• (1) does not exist, try --help #786 (1) does not exist, try --help
• I use "yyy" command in any "xxx" file,there will be a error: con't find module "/path/to/xxx-yyy" #815 I use "yyy" command in any "xxx" file,there will be a error: con't find module "/path/to/xxx-yyy"
• Commander always executes the first registered command #825 Commander always executes the first registered command
• Passing description to the "command()" method causes error being produced in runtime #976 Passing description to the "command()" method causes error being produced in runtime

Pull Requests:

• invoke git-style sub commands only when required #810 invoke git-style sub commands only when required

[shadowspawn]

Couple of documentation areas for improving status quo:

• be more explicit with parameter names that appear in IDE autocompletion (JSDoc, TypeScript)
• rewrite command section of README and cover different styles explicitly

[shadowspawn]

First steps are looking to resolve #706, and improving documentation (README, JSDoc, TypeScript).

[shadowspawn]

Pull request including JSDoc and TypeScript improvements underway: #990

[shadowspawn]

This issue will be resolved when v3.0.0 is released. Available now as a prerelease. See #1001

Reworked the README and JSDoc and TypeScript to hopefully make the two modes of operation clearer. Have not changed the runtime, but will close this issue and see how the changes help.

[shadowspawn]

Reworked the README and JSDoc and TypeScript to hopefully make the two modes of operation clearer. Have not changed the runtime, but will close this issue and see how the changes help.

Shipped in v3: https://github.com/tj/commander.js/releases/tag/v3.0.0

[shadowspawn]

Further reports: #1154 #1644