Remove most uses of top-level, as less accurate now with command nest…

…ing. (#1230)

Readme.md

@@ -300,7 +300,7 @@ program.version('0.0.1', '-v, --vers', 'output the current version');
 
 ## Commands
 
-You can specify (sub)commands for your top-level command using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).
+You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).
 
 In the first parameter to `.command()` you specify the command name and any command arguments. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.
 
@@ -319,13 +319,13 @@ program
   });
 
 // Command implemented using stand-alone executable file (description is second parameter to `.command`)
-// Returns top-level command for adding more commands.
+// Returns `this` for adding more commands.
 program
   .command('start <service>', 'start named service')
   .command('stop [service]', 'stop named service, or all if no name supplied');
 
 // Command prepared separately.
-// Returns top-level command for adding more commands.
+// Returns `this` for adding more commands.
 program
   .addCommand(build.makeBuildCommand());
 ```
@@ -334,7 +334,7 @@ Configuration options can be passed with the call to `.command()`. Specifying `t
 
 ### Specify the argument syntax
 
-You use `.arguments` to specify the arguments for the top-level command, and for subcommands they are included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required input. Square brackets (e.g. `[optional]`) indicate optional input.
+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.
 
 ```js
 const { program } = require('commander');

index.js

@@ -153,7 +153,7 @@ class Command extends EventEmitter {
    * @param {string} nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
    * @param {Object|string} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
    * @param {Object} [execOpts] - configuration options (for executable)
-   * @return {Command} returns new command for action handler, or top-level command for executable command
+   * @return {Command} returns new command for action handler, or `this` for executable command
    * @api public
    */
 
@@ -241,7 +241,7 @@ class Command extends EventEmitter {
   };
 
   /**
-   * Define argument syntax for the top-level command.
+   * Define argument syntax for the command.
    *
    * @api public
    */

typings/index.d.ts

@@ -103,7 +103,7 @@ declare namespace commander {
     addCommand(cmd: Command): this;
 
     /**
-     * Define argument syntax for the top-level command.
+     * Define argument syntax for command.
      *
      * @returns Command for chaining
      */