Added documentation for #795, --no-* improvements

CHANGELOG.md

@@ -11,6 +11,10 @@
   * Add parent command as prefix of subcommand in help (#980)
   * Add optional custom description to `.version` (#963)
   * Add `.helpOption(flags, description)` routine to customise help flags and description (#963)
+  * Fix behavior of --no-* options (#795)
+    * can now define both `--foo` and `--no-foo`
+    * custom event listeners: `--no-foo` on cli now emits `option:no-foo` (previously `option:foo`)
+    * default value: defining `--no-foo` after defining `--foo` leaves the default value unchanged (previously set it to false)
 
 2.20.0 / 2019-04-02
 ==================

Readme.md

@@ -99,30 +99,37 @@ cheese: stilton
 
 ### Other option types, negatable boolean and flag|value
 
-You can specify a boolean option long name with a leading `no-` to make it true by default and able to be negated.
+You can specify a boolean option long name with a leading `no-` to set the option value to false when used.
+Defined alone this also makes the option true by default.
+If you define `foo` first, adding `--no-foo` does not change the default value.
 
 
 ```js
 const program = require('commander');
 
 program
-  .option('-n, --no-sauce', 'Remove sauce')
+  .option('--no-sauce', 'Remove sauce')
+  .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
+  .option('--no-cheese', 'plain with no cheese')
   .parse(process.argv);
 
-if (program.sauce) console.log('you ordered a pizza with sauce');
-else console.log('you ordered a pizza without sauce');
+const sauceStr = program.sauce ? 'sauce' : 'no sauce';
+const cheeseStr = (program.cheese === false) ? 'no cheese' : `${program.cheese} cheese`;
+console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);
 ```
 
 ```bash
-$ pizza-options
-you ordered a pizza with sauce
+$ pizza-options 
+You ordered a pizza with sauce and mozzarella cheese
 $ pizza-options --sauce
 error: unknown option '--sauce'
-$ pizza-options --no-sauce
-you ordered a pizza without sauce
+$ pizza-options --cheese=blue
+You ordered a pizza with sauce and blue cheese
+$ pizza-options --no-sauce --no-cheese
+You ordered a pizza with no sauce and no cheese
 ```
-You can specify an option which functions as a flag but may also take a value (declared using square brackets).
 
+You can specify an option which functions as a flag but may also take a value (declared using square brackets).
 
 ```js
 const program = require('commander');

examples/options-negatable.js

@@ -6,19 +6,24 @@
 //
 // Example output pretending command called pizza-options (or try directly with `node options-negatable.js`)
 //
-// $ pizza-options
-// you ordered a pizza with sauce
+// $ pizza-options 
+// You ordered a pizza with sauce and mozzarella cheese
 // $ pizza-options --sauce
 // error: unknown option '--sauce'
-// $ pizza-options --no-sauce
-// you ordered a pizza without sauce
+// $ pizza-options --cheese=blue
+// You ordered a pizza with sauce and blue cheese
+// $ pizza-options --no-sauce --no-cheese
+// You ordered a pizza with no sauce and no cheese
 
 const commander = require('commander');
 const program = new commander.Command();
 
 program
-  .option('-n, --no-sauce', 'Remove sauce')
+  .option('--no-sauce', 'Remove sauce')
+  .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
+  .option('--no-cheese', 'plain with no cheese')
   .parse(process.argv);
 
-if (program.sauce) console.log('you ordered a pizza with sauce');
-else console.log('you ordered a pizza without sauce');
+const sauceStr = program.sauce ? 'sauce' : 'no sauce';
+const cheeseStr = (program.cheese === false) ? 'no cheese' : `${program.cheese} cheese`;
+console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);