Deprecated functionality (#1349)

* Add documentation on deprecated routines

* Tidy up deprecated and link from README.

Readme.md

@@ -43,6 +43,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [Node options such as `--harmony`](#node-options-such-as---harmony)
     - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
     - [Override exit handling](#override-exit-handling)
+    - [Additional documentation](#additional-documentation)
   - [Examples](#examples)
   - [Support](#support)
     - [Commander for enterprise](#commander-for-enterprise)
@@ -762,6 +763,13 @@ try {
 }
 ```
 
+### Additional documentation
+
+There is more information available about:
+
+- [deprecated](./docs/deprecated.md) features still supported for backwards compatibility
+- [options taking varying arguments](./docs/options-taking-varying-arguments.md)
+
 ## Examples
 
 Example file: [deploy](./examples/deploy)

docs/deprecated.md

@@ -0,0 +1,88 @@
+# Deprecated
+
+These features are deprecated, which means they may go away in a future major version of Commander.
+They are currently still available for backwards compatibility, but should not be used in new code.
+
+## RegExp .option() parameter
+
+The `.option()` method allowed a RegExp as the third parameter to restrict what values were accepted.
+
+```js
+program.option('-c,--coffee <type>', 'coffee', /short-white|long-black/);
+```
+
+Removed from README in Commander v3. Deprecated from Commander v7.
+
+The newer functionality is the Option `.choices()' method, or using a custom option processing function.
+
+## noHelp
+
+This was an option passed to `.command()` to hide the command from the built-in help:
+
+```js
+program.command('example', 'examnple command', { noHelp: true });
+```
+
+The option was renamed `hidden` in Commander v5.1. Deprecated from Commander v7. 
+
+## Default import of global Command object
+
+The default import was a global Command object.
+
+```js
+const program = require('commander');
+```
+
+The global Command object is exported as `program` from Commander v5, or import the Command object.
+
+```js
+const { program } = require('commander');
+// or
+const { Command } = require('commander');
+comnst program = new Command()
+```
+
+Removed from README in Commander v5. Deprecated from Commander v7. 
+
+## Callback to .help() and .outputHelp()
+
+These routines allowed a callback parameter to process the built-in help before display.
+
+```js
+program.outputHelp((text) => {
+  return colors.red(text);
+});
+```
+
+The newer approach is to directly access the built-in help text using `.helpInformation()`.
+
+```js
+console.error(colors.red(program.helpInformation()));
+```
+
+Deprecated from Commander v7.
+
+## .on('--help')
+
+This was the way to add custom help after the built-in help. From Commander v3.0.0 this used the custom long help option flags, if changed.
+
+```js
+program.on('--help', function() {
+  console.log('')
+  console.log('Examples:');
+  console.log('  $ custom-help --help');
+  console.log('  $ custom-help -h');
+});
+```
+
+The replacement is `.addHelpText()`:
+
+```js
+program.addHelpText('after', `
+Examples:
+  $ custom-help --help
+  $ custom-help -h`
+);
+```
+
+Deprecated from Commander v7. 

index.js

@@ -300,7 +300,7 @@ class Command extends EventEmitter {
     }
     if (opts.isDefault) this._defaultCommandName = cmd._name;
 
-    cmd._hidden = !!(opts.noHelp || opts.hidden);
+    cmd._hidden = !!(opts.noHelp || opts.hidden); // noHelp is deprecated old name for hidden
     cmd._hasHelpOption = this._hasHelpOption;
     cmd._helpFlags = this._helpFlags;
     cmd._helpDescription = this._helpDescription;

typings/index.d.ts

@@ -447,9 +447,10 @@ declare namespace commander {
   type CommandConstructor = new (name?: string) => Command;
 
   interface CommandOptions {
-    noHelp?: boolean; // old name for hidden
     hidden?: boolean;
     isDefault?: boolean;
+    /** @deprecated since v7, replaced by hidden */
+    noHelp?: boolean;
   }
   interface ExecutableCommandOptions extends CommandOptions {
     executableFile?: string;