diff --git a/docs/api.md b/docs/api.md
index 0d7f3e7b2..1a9176e51 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -74,11 +74,7 @@ For example: `--foo foo bar -- val` will be parsed as
 <a name="boolean"></a>.boolean(key)
 -------------
 
-Interpret `key` as a boolean. If a non-flag option follows `key` in
-`process.argv`, that string won't get set as the value of `key`.
-
-`key` will default to `false`, unless a `default(key, undefined)` is
-explicitly set.
+Interpret `key` as a boolean. If a non-flag option - unless `true` or `false` - follows `key` in `process.argv`, that string won't get set as the value of `key`.
 
 `key` can be set false explicitly using the `--no-` prefix, [more](/docs/tricks.md#negate).
 
diff --git a/docs/examples.md b/docs/examples.md
index b50cf9f50..84fd351ac 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -233,17 +233,17 @@ boolean_single.js:
 ````javascript
 #!/usr/bin/env node
 var argv = require('yargs')
-    .boolean('v')
+    .boolean(['r','v'])
     .argv
 ;
-console.dir(argv.v);
+console.dir([ argv.r, argv.v ]);
 console.dir(argv._);
 ````
 
 ***
 
-    $ ./boolean_single.js -v "me hearties" yo ho
-    true
+    $ ./boolean_single.js -r false -v "me hearties" yo ho
+    [ false, true ]
     [ 'me hearties', 'yo', 'ho' ]
 
 
@@ -262,7 +262,7 @@ console.dir(argv._);
 ***
 
     $ ./boolean_double.js -x -z one two three
-    [ true, false, true ]
+    [ true, undefined, true ]
     [ 'one', 'two', 'three' ]
 
 Yargs is here to help you...
diff --git a/example/boolean_single.js b/example/boolean_single.js
index 62ec4ee12..51cf3cbec 100644
--- a/example/boolean_single.js
+++ b/example/boolean_single.js
@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 var argv = require('yargs')
-    .boolean('v')
+    .boolean(['r','v'])
     .argv
 ;
-console.dir(argv.v);
+console.dir([ argv.r, argv.v ]);
 console.dir(argv._);