fix(docs): formalize existing callback argument to showHelp (#1386)

docs/api.md

@@ -914,7 +914,7 @@ To submit a new translation for yargs:
 <a name="middleware"></a>.middleware(callbacks, [applyBeforeValidation])
 ------------------------------------
 
-Define global middleware functions to be called first, in list order, for all cli command.  
+Define global middleware functions to be called first, in list order, for all cli command.
 
 The `callbacks` parameter can be a function or a list of functions.  Each callback gets passed a reference to argv.
 
@@ -1291,25 +1291,31 @@ Generate a bash completion script. Users of your application can install this
 script in their `.bashrc`, and yargs will provide completion shortcuts for
 commands and options.
 
-.showHelp(consoleLevel='error')
+.showHelp([consoleLevel | printCallback])
 ---------------------------
 
-Print the usage data using the [`console`](https://nodejs.org/api/console.html) function `consoleLevel` for printing.
+Print the usage data.
 
-Example:
+If no argument is provided, usage data is printed using `console.error`.
 
 ```js
 var yargs = require("yargs")
   .usage("$0 -operand1 number -operand2 number -operation [add|subtract]");
 yargs.showHelp(); //prints to stderr using console.error()
 ```
 
-Or, to print the usage data to `stdout` instead, you can specify the use of `console.log`:
+If a string is specified, usage data is printed using the [`console`](https://nodejs.org/api/console.html) function `consoleLevel`.
 
 ```js
 yargs.showHelp("log"); //prints to stdout using console.log()
 ```
 
+If a function is specified, it is called with a single argument - the usage data as a string.
+
+```js
+yargs.showHelp(s => myStream.write(s)); //prints to myStream
+```
+
 Later on, `argv` can be retrieved with `yargs.argv`.
 
 .showHelpOnFail(enable, [message])

test/usage.js

@@ -2414,7 +2414,27 @@ describe('usage tests', () => {
       ])
     })
 
-    it('should call the correct console.log method', () => {
+    it('should print the help using console.error when no arguments were specified', () => {
+      const r = checkUsage(() => {
+        const y = yargs(['--foo'])
+          .options('foo', {
+            alias: 'f',
+            describe: 'foo option'
+          })
+          .wrap(null)
+
+        y.showHelp()
+      })
+
+      r.errors.join('\n').split(/\n+/).should.deep.equal([
+        'Options:',
+        '  --help     Show help  [boolean]',
+        '  --version  Show version number  [boolean]',
+        '  --foo, -f  foo option'
+      ])
+    })
+
+    it('should call the correct console.log method when specified', () => {
       const r = checkUsage(() => {
         const y = yargs(['--foo'])
           .options('foo', {
@@ -2435,16 +2455,16 @@ describe('usage tests', () => {
       ])
     })
 
-    it('should provide a help string to handler when provided', (done) => {
+    it('should call the callback to print when specified', (done) => {
       const y = yargs(['--foo'])
         .options('foo', {
           alias: 'f',
           describe: 'foo option'
         })
         .wrap(null)
 
-      y.showHelp(testHandler)
-      function testHandler (msg) {
+      y.showHelp(printCallback)
+      function printCallback (msg) {
         msg.split(/\n+/).should.deep.equal([
           'Options:',
           '  --help     Show help  [boolean]',