doc: improve assert documentation

This adds a example to `assert.throws` to document checking against
error instances. It also makes it clearer what some arguments can
receive as input.

doc/api/assert.md

@@ -394,6 +394,9 @@ is little benefit by catching a rejection and then rejecting it again. Instead,
 consider adding a comment next to the specific code path that should not reject
 and keep error messages as expressive as possible.
 
+If specified, `error` can be a [`Class`][], [`RegExp`][] or a validation
+function. See [`assert.throws()`][] for more details.
+
 Besides the async nature to await the completion behaves identically to
 [`assert.doesNotThrow()`][].
 
@@ -430,8 +433,7 @@ changes:
 * `error` {RegExp|Function}
 * `message` {any}
 
-Asserts that the function `block` does not throw an error. See
-[`assert.throws()`][] for more details.
+Asserts that the function `block` does not throw an error.
 
 Please note: Using `assert.doesNotThrow()` is actually not useful because there
 is no benefit by catching an error and then rethrowing it. Instead, consider
@@ -446,6 +448,9 @@ parameter, then an `AssertionError` is thrown. If the error is of a different
 type, or if the `error` parameter is undefined, the error is propagated back
 to the caller.
 
+If specified, `error` can be a [`Class`][], [`RegExp`][] or a validation
+function. See [`assert.throws()`][] for more details.
+
 The following, for instance, will throw the [`TypeError`][] because there is no
 matching error type in the assertion:
 
@@ -482,7 +487,7 @@ assert.doesNotThrow(
   () => {
     throw new TypeError('Wrong value');
   },
-  TypeError,
+  /Wrong value/,
   'Whoops'
 );
 // Throws: AssertionError: Got unwanted exception (TypeError). Whoops
@@ -915,7 +920,7 @@ assert(0);
 added: REPLACEME
 -->
 * `block` {Function|Promise}
-* `error` {RegExp|Function|Object}
+* `error` {RegExp|Function|Object|Error}
 * `message` {any}
 
 Awaits the `block` promise or, if `block` is a function, immediately call the
@@ -928,8 +933,10 @@ rejected directly without checking the `error` handler.
 Besides the async nature to await the completion behaves identically to
 [`assert.throws()`][].
 
-If specified, `error` can be a constructor, [`RegExp`][], a validation
-function, or an object where each property will be tested for.
+If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function,
+an object where each property will be tested for or an instance of error where
+each property will be tested for including the non-enumerable `message` and
+`name` properties.
 
 If specified, `message` will be the message provided by the `AssertionError` if
 the block fails to reject.
@@ -1009,13 +1016,15 @@ changes:
     description: The `error` parameter can now be an arrow function.
 -->
 * `block` {Function}
-* `error` {RegExp|Function|Object}
+* `error` {RegExp|Function|Object|Error}
 * `message` {any}
 
 Expects the function `block` to throw an error.
 
-If specified, `error` can be a constructor, [`RegExp`][], a validation
-function, or an object where each property will be tested for.
+If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function,
+an object where each property will be tested for or an instance of error where
+each property will be tested for including the non-enumerable `message` and
+`name` properties.
 
 If specified, `message` will be the message provided by the `AssertionError` if
 the block fails to throw.
@@ -1064,10 +1073,11 @@ assert.throws(
 Custom error object / error instance:
 
 ```js
+const err = new TypeError('Wrong value');
+err.code = 404;
+
 assert.throws(
   () => {
-    const err = new TypeError('Wrong value');
-    err.code = 404;
     throw err;
   },
   {
@@ -1076,6 +1086,16 @@ assert.throws(
     // Note that only properties on the error object will be tested!
   }
 );
+
+// Fails due to the different `message` and `name` properties:
+assert.throws(
+  () => {
+    const otherErr = new Error('Not found');
+    otherErr.code = 404;
+    throw otherErr;
+  },
+  err // This tests for `message`, `name` and `code`.
+);
 ```
 
 Note that `error` cannot be a string. If a string is provided as the second
@@ -1116,6 +1136,7 @@ assert.throws(throwingFirst, /Second$/);
 Due to the confusing notation, it is recommended not to use a string as the
 second argument. This might lead to difficult-to-spot errors.
 
+[`Class`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
 [`Error.captureStackTrace`]: errors.html#errors_error_capturestacktrace_targetobject_constructoropt
 [`Error`]: errors.html#errors_class_error
 [`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map