From c5c1dc5ddaaaf228dc76b365a2d20a54f33aa97e Mon Sep 17 00:00:00 2001
From: Oleg Slobodskoi <oleg008@gmail.com>
Date: Thu, 2 Dec 2010 11:07:47 -0800
Subject: [PATCH] docs for assert.throws

---
 doc/api/assert.markdown | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/doc/api/assert.markdown b/doc/api/assert.markdown
index e6511445ff..24685ebf38 100644
--- a/doc/api/assert.markdown
+++ b/doc/api/assert.markdown
@@ -37,11 +37,44 @@ Tests strict non-equality, as determined by the strict not equal operator ( `!==
 
 ### assert.throws(block, [error], [message])
 
-Expects `block` to throw an error.
+Expects `block` to throw an error. `error` can be constructor, regexp or 
+validation function.
+
+Validate instanceof using constructor:
+
+    assert.throws(
+      function() {
+        throw new Error("Wrong value");
+      },
+      Error
+    );
+
+Validate error message using RegExp:
+
+    assert.throws(
+      function() {
+        throw new Error("Wrong value");
+      },
+      /value/
+    );
+
+Custom error validation:
+
+    assert.throws(
+      function() {
+        throw new Error("Wrong value");
+      },
+      function(err) {
+        if ( !(err instanceof Error) || !/value/.test(err) ) {
+          return false;
+        }
+      },
+      "unexpected error"
+    );
 
 ### assert.doesNotThrow(block, [error], [message])
 
-Expects `block` not to throw an error.
+Expects `block` not to throw an error, see assert.throws for details.
 
 ### assert.ifError(value)