Extra documentation: deprecated, undocumented, and superseded features

[shadowspawn]

We could add a separate page, outside the README, for features which are (deliberately) not covered in the README. This includes features which have been replaced by better ways, features which didn't work out and are now deprecated, and features which never got documented and may never make primetime. Sometimes referred to as legacy.

Partly so people can find documentation on old code they find in programs they are maintaining, and partly so people can find out about state of routines they discover looking in the code or through the issues. e.g.

• noHelp
• regexp validation for option value
• command('*')
• documentation for arguments (.arguments())
• .allowUnknownOptions()

[shadowspawn]

I started work on this, but having second thoughts. Migration advice might be more useful, and that is included in the Release Notes and CHANGELOG.

Adding what I wrote up so searchable in Issues, but not planning to add a separate document at this stage.

---

Unloved Features

You may come across features that are not described in the README: in existing programs, or mentioned in issues, or by inspecting the Commander code. Check here
to find out more, and whether they could be used or should be avoided.

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. Removed from README from Commander v3.

program.option('-c,--coffee <type>', 'coffee', /short-white|long-black/);

The newer functionality is the custom option processing function passed in the same parameter position.

command('*')

This was called when the command was not known:

program.command('*')

The newer functionality is setting a command as the default command using the isDefault option in the .command() parameters. Available for action handlers from Commander v5.

You can also use a listener for .on('command:*', handler) for custom processing for unknown commands.

noHelp

This was an option passed to .command() to hide the command from the built-in help:

program.command('example', 'examnple command', { noHelp: true });

The option has been renamed hidden from Commander v5.1.

Default Import

The default import was a global Command object.

const program = require('commander');

The global Command object is exported as program from Commander v5, or import the Command object.

const { program } = require('commander');
// or
const { Command } = require('commander');
comnst program = new Command()

Unloved

These legacy features have never been documented in the README. Still unsure whether there are
solid enough and useful enough to eventually be added to the README, or whether they may
be deprecated and/or replaced.

allowUnknownOptions

Used to suppress the error handling when unknown options are found:

program.allowUnknownOptions();

The main effect is simply suppressing the error handling, and the unknown options
are passed through as ordinary arguments to process yourself. Commander
does not attempt to extract (guess) the unknown options and values.

Argument Descriptions

The .description() method allows a second parameter with descriptions of the command arguments.
The parameter is a hash with key of the argument name and value of the description. Using this adds an "Arguments:" section in the built-in help.

program
  .arguments('<file>')
  .description('print target file', {
    file: 'file to process'
  });