docs: Clarify assert.doesNotThrow behavior

The documentation for assert.doesNotThrow now reflects all the inputs
the function accepts, as well as the errors thrown for each combination
of parameter types.

PR-URL: https://github.com/nodejs/node/pull/2807
Reviewed-By: Rich Trott <rtrott@gmail.com>

diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown
index 4633b90..bb7a8fb 100644 (file)
--- a/doc/api/assert.markdown
+++ b/doc/api/assert.markdown
@@ -7,11 +7,13 @@ access it with `require('assert')`.
 
 ## assert.fail(actual, expected, message, operator)
 
-Throws an exception that displays the values for `actual` and `expected` separated by the provided operator.
+Throws an exception that displays the values for `actual` and `expected`
+separated by the provided operator.
 
 ## assert(value[, message]), assert.ok(value[, message])
 
-Tests if value is truthy. It is equivalent to `assert.equal(true, !!value, message)`.
+Tests if value is truthy. It is equivalent to
+`assert.equal(true, !!value, message)`.
 
 ## assert.equal(actual, expected[, message])
 
@@ -86,9 +88,31 @@ Custom error validation:
       "unexpected error"
     );
 
-## assert.doesNotThrow(block[, message])
+## assert.doesNotThrow(block[, error][, message])
 
-Expects `block` not to throw an error. See `assert.throws()` for details.
+Expects `block` not to throw an error. See [assert.throws()](#assert_assert_throws_block_error_message) for more details.
+
+If `block` throws an error and if it is of a different type from `error`, the
+thrown error will get propagated back to the caller. The following call will
+throw the `TypeError`, since we're not matching the error types in the
+assertion.
+
+    assert.doesNotThrow(
+      function() {
+        throw new TypeError("Wrong value");
+      },
+      SyntaxError
+    );
+
+In case `error` matches with the error thrown by `block`, an `AssertionError`
+is thrown instead.
+
+    assert.doesNotThrow(
+      function() {
+        throw new TypeError("Wrong value");
+      },
+      TypeError
+    );
 
 ## assert.ifError(value)