[readme] improve method docs

readme.markdown

@@ -161,22 +161,26 @@ Available `opts` options are:
 - opts.objectPrintDepth = 5. Configure max depth of expected / actual object printing. Environmental variable `NODE_TAPE_OBJECT_PRINT_DEPTH` can set the desired default depth for all tests; locally-set values will take precedence.
 - opts.todo = true/false. Test will be allowed to fail.
 
-If you forget to `t.plan()` out how many assertions you are going to run and you
-don't call `t.end()` explicitly, your test will hang.
+If you forget to `t.plan()` out how many assertions you are going to run and you don't call `t.end()` explicitly, or return a Promise that eventually settles, your test will hang.
+
+If `cb` returns a Promise, it will be implicitly awaited. If that promise rejects, the test will be failed; if it fulfills, the test will end. Explicitly calling `t.end()` while also returning a Promise that fulfills is an error.
 
 ## test.skip([name], [opts], cb)
 
 Generate a new test that will be skipped over.
 
 ## test.onFinish(fn)
 
-The onFinish hook will get invoked when ALL `tape` tests have finished
-right before `tape` is about to print the test summary.
+The onFinish hook will get invoked when ALL `tape` tests have finished right before `tape` is about to print the test summary.
+
+`fn` is called with no arguments, and its return value is ignored.
 
 ## test.onFailure(fn)
 
 The onFailure hook will get invoked whenever any `tape` tests has failed.
 
+`fn` is called with no arguments, and its return value is ignored.
+
 ## t.plan(n)
 
 Declare that `n` assertions should be run. `t.end()` will be called
@@ -185,8 +189,9 @@ the `n`th, or after `t.end()` is called, they will generate errors.
 
 ## t.end(err)
 
-Declare the end of a test explicitly. If `err` is passed in `t.end` will assert
-that it is falsey.
+Declare the end of a test explicitly. If `err` is passed in `t.end` will assert that it is falsy.
+
+Do not call `t.end()` if your test callback returns a Promise.
 
 ## t.fail(msg)
 
@@ -218,8 +223,7 @@ Aliases: `t.false()`, `t.notok()`
 
 ## t.error(err, msg)
 
-Assert that `err` is falsy. If `err` is non-falsy, use its `err.message` as the
-description message.
+Assert that `err` is falsy. If `err` is non-falsy, use its `err.message` as the description message.
 
 Aliases: `t.ifError()`, `t.ifErr()`, `t.iferror()`
 
@@ -289,16 +293,16 @@ Assert that the function call `fn()` does not throw an exception. `expected`, if
 
 ## t.test(name, [opts], cb)
 
-Create a subtest with a new test handle `st` from `cb(st)` inside the current
-test `t`. `cb(st)` will only fire when `t` finishes. Additional tests queued up
-after `t` will not be run until all subtests finish.
+Create a subtest with a new test handle `st` from `cb(st)` inside the current test `t`. `cb(st)` will only fire when `t` finishes. Additional tests queued up after `t` will not be run until all subtests finish.
 
 You may pass the same options that [`test()`](#testname-opts-cb) accepts.
 
 ## t.comment(message)
 
 Print a message without breaking the tap output. (Useful when using e.g. `tap-colorize` where output is buffered & `console.log` will print in incorrect order vis-a-vis tap output.)
 
+Multiline output will be split by `\n` characters, and each one printed as a comment.
+
 ## t.match(string, regexp, message)
 
 Assert that `string` matches the RegExp `regexp`. Will throw (not just fail) when the first two arguments are the wrong type.
@@ -309,25 +313,17 @@ Assert that `string` does not match the RegExp `regexp`. Will throw (not just fa
 
 ## var htest = test.createHarness()
 
-Create a new test harness instance, which is a function like `test()`, but with
-a new pending stack and test state.
+Create a new test harness instance, which is a function like `test()`, but with a new pending stack and test state.
 
-By default the TAP output goes to `console.log()`. You can pipe the output to
-someplace else if you `htest.createStream().pipe()` to a destination stream on
-the first tick.
+By default the TAP output goes to `console.log()`. You can pipe the output to someplace else if you `htest.createStream().pipe()` to a destination stream on the first tick.
 
 ## test.only([name], [opts], cb)
 
-Like `test([name], [opts], cb)` except if you use `.only` this is the only test case
-that will run for the entire process, all other test cases using `tape` will
-be ignored.
+Like `test([name], [opts], cb)` except if you use `.only` this is the only test case that will run for the entire process, all other test cases using `tape` will be ignored.
 
 ## var stream = test.createStream(opts)
 
-Create a stream of output, bypassing the default output stream that writes
-messages to `console.log()`. By default `stream` will be a text stream of TAP
-output, but you can get an object stream instead by setting `opts.objectMode` to
-`true`.
+Create a stream of output, bypassing the default output stream that writes messages to `console.log()`. By default `stream` will be a text stream of TAP output, but you can get an object stream instead by setting `opts.objectMode` to `true`.
 
 ### tap stream reporter
 
@@ -344,8 +340,7 @@ process.argv.slice(2).forEach(function (file) {
 });
 ```
 
-You could substitute `process.stdout` for whatever other output stream you want,
-like a network connection or a file.
+You could substitute `process.stdout` for whatever other output stream you want, like a network connection or a file.
 
 Pass in test files to run as arguments: