From 2bdb7380ae77864c7b08352fff6fc92bd63cd95b Mon Sep 17 00:00:00 2001
From: Domenic Denicola <d@domenic.me>
Date: Mon, 29 Feb 2016 11:48:14 -0500
Subject: [PATCH] Add t.step_func_done documentation

Also cleans up a bit around that area, e.g. replacing an assert_true(true) with assert_true(e.a) so that people are hopefully less likely to think that assert_true(true) is a good way to say "this test passed".
---
 docs/api.md | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 1405cfd..f274f82 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -76,23 +76,26 @@ Assertions can be added to the test by calling the step method of the test
 object with a function containing the test assertions:
 
 ```js
-t.step(function() {assert_true(true)});
+t.step(function() {assert_equals(1+1, 2)});
 ```
 
-When all the steps are complete, the done() method must be called:
+When all the steps are complete, the `done()` method must be called:
 
 ```js
 t.done();
 ```
 
-As a convenience, async_test can also takes a function as first argument.
+As a convenience, `async_test` can also takes a function as first argument.
 This function is called with the test object as both its `this` object and
-first argument. The above example can be rewritten as:
+first argument. Thus we can write:
 
 ```js
 async_test(function(t) {
-    object.some_event = function() {
-        t.step(function (){assert_true(true); t.done();});
+    object.some_event = function(e) {
+        t.step(function() {
+          assert_true(e.a);
+          t.done();
+        });
     };
 }, "Simple async test");
 ```
@@ -120,6 +123,14 @@ object.some_event = t.unreached_func("some_event should not fire");
 Keep in mind that other tests could start executing before an Asynchronous
 Test is finished.
 
+Finally, for cases where you want to simply pass the test when a callback is
+called, there is `step_func_done`, which will generate a step function that
+calls `done()`. For example:
+
+```js
+object.some_event = t.step_func_done();
+```
+
 ## Promise Tests ##
 
 `promise_test` can be used to test APIs that are based on Promises: