From 3d8bb683c6f9202b3aaa87e0cae2cd8545b6654a Mon Sep 17 00:00:00 2001
From: Brian White <mscdex@mscdex.net>
Date: Thu, 21 Jul 2016 01:04:09 -0400
Subject: [PATCH 1/3] doc: reorganize assert link references

---
 doc/api/assert.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/api/assert.md b/doc/api/assert.md
index bc5c0b833ae5aa..5a4cdab45429be 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -461,11 +461,12 @@ assert.throws(myFunction, 'missing foo', 'did not throw with expected message');
 assert.throws(myFunction, /missing foo/, 'did not throw with expected message');
 ```
 
-[Locked]: documentation.html#documentation_stability_index
 [`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message
 [`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message
 [`assert.ok()`]: #assert_assert_ok_value_message
 [`assert.throws()`]: #assert_assert_throws_block_error_message
 [`Error`]: errors.html#errors_class_error
-[`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
 [`TypeError`]: errors.html#errors_class_typeerror
+
+[Locked]: documentation.html#documentation_stability_index
+[`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions

From 51c532243ddc46e932cfcc7ef28a710ffcac4977 Mon Sep 17 00:00:00 2001
From: Brian White <mscdex@mscdex.net>
Date: Thu, 21 Jul 2016 01:10:12 -0400
Subject: [PATCH 2/3] doc: improve assert code examples

---
 doc/api/assert.md | 237 +++++++++++++++++++++++++---------------------
 1 file changed, 131 insertions(+), 106 deletions(-)

diff --git a/doc/api/assert.md b/doc/api/assert.md
index 5a4cdab45429be..8409ab758b011f 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -17,20 +17,7 @@ the module.
 added: v0.5.9
 -->
 
-An alias of [`assert.ok()`][] .
-
-```js
-const assert = require('assert');
-
-assert(true);  // OK
-assert(1);     // OK
-assert(false);
-  // throws "AssertionError: false == true"
-assert(0);
-  // throws "AssertionError: 0 == true"
-assert(false, 'it\'s false');
-  // throws "AssertionError: it's false"
-```
+An alias of [`assert.ok()`].
 
 ## assert.deepEqual(actual, expected[, message])
 <!-- YAML
@@ -46,7 +33,12 @@ non-enumerable properties. This can lead to some potentially surprising
 results. For example, the following example does not throw an `AssertionError`
 because the properties on the [`Error`][] object are non-enumerable:
 
+Example: The following does not throw an `AssertionError` because the properties
+on the [`Error`] object are non-enumerable
+
 ```js
+const assert = require('assert');
+
 // WARNING: This does not throw an AssertionError!
 assert.deepEqual(Error('a'), Error('b'));
 ```
@@ -54,39 +46,41 @@ assert.deepEqual(Error('a'), Error('b'));
 "Deep" equality means that the enumerable "own" properties of child objects
 are evaluated also:
 
+Examples:
+
 ```js
 const assert = require('assert');
 
 const obj1 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj2 = {
-  a : {
-    b : 2
+  a: {
+    b: 2
   }
 };
 const obj3 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj4 = Object.create(obj1);
 
+// OK
 assert.deepEqual(obj1, obj1);
-  // OK, object is equal to itself
-
-assert.deepEqual(obj1, obj2);
-  // AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
-  // values of b are different
 
+// OK
 assert.deepEqual(obj1, obj3);
-  // OK, objects are equal
 
+// Throws an exception: AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
+// The reason for this is that the values of `b` are different
+assert.deepEqual(obj1, obj2);
+
+// Throws an exception: AssertionError: { a: { b: 1 } } deepEqual {}
+// The reason for this is that prototypes are ignored
 assert.deepEqual(obj1, obj4);
-  // AssertionError: { a: { b: 1 } } deepEqual {}
-  // Prototypes are ignored
 ```
 
 If the values are not equal, an `AssertionError` is thrown with a `message`
@@ -102,15 +96,20 @@ Generally identical to `assert.deepEqual()` with two exceptions. First,
 primitive values are compared using the strict equality operator ( `===` ).
 Second, object comparisons include a strict equality check of their prototypes.
 
+Example:
+
 ```js
 const assert = require('assert');
 
-assert.deepEqual({a:1}, {a:'1'});
-  // OK, because 1 == '1'
+const obj1 = {
+  a: 1
+};
+const obj2 = {
+  a: '1'
+};
 
-assert.deepStrictEqual({a:1}, {a:'1'});
-  // AssertionError: { a: 1 } deepStrictEqual { a: '1' }
-  // because 1 !== '1' using strict equality
+// Throws an exception: AssertionError: { a: 1 } deepStrictEqual { a: '1' }
+assert.deepStrictEqual(obj1, obj2);
 ```
 
 If the values are not equal, an `AssertionError` is thrown with a `message`
@@ -133,35 +132,28 @@ 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.
 
-The following, for instance, will throw the [`TypeError`][] because there is no
-matching error type in the assertion:
+Examples:
 
 ```js
+const assert = require('assert');
+
+// Throws an exception: TypeError: Wrong value
 assert.doesNotThrow(
   () => {
     throw new TypeError('Wrong value');
   },
   SyntaxError
 );
-```
 
-However, the following will result in an `AssertionError` with the message
-'Got unwanted exception (TypeError)..':
-
-```js
+// Throws an exception: AssertionError: Got unwanted exception (TypeError)..
 assert.doesNotThrow(
   () => {
     throw new TypeError('Wrong value');
   },
   TypeError
 );
-```
-
-If an `AssertionError` is thrown and a value is provided for the `message`
-parameter, the value of `message` will be appended to the `AssertionError`
-message:
 
-```js
+// Throws an exception: AssertionError: Got unwanted exception (TypeError). Whoops
 assert.doesNotThrow(
   () => {
     throw new TypeError('Wrong value');
@@ -169,7 +161,6 @@ assert.doesNotThrow(
   TypeError,
   'Whoops'
 );
-// Throws: AssertionError: Got unwanted exception (TypeError). Whoops
 ```
 
 ## assert.equal(actual, expected[, message])
@@ -180,18 +171,22 @@ added: v0.1.21
 Tests shallow, coercive equality between the `actual` and `expected` parameters
 using the equal comparison operator ( `==` ).
 
+Examples:
+
 ```js
 const assert = require('assert');
 
+// OK
 assert.equal(1, 1);
-  // OK, 1 == 1
+
+// OK
 assert.equal(1, '1');
-  // OK, 1 == '1'
 
+// Throws an exception: AssertionError: 1 == 2
 assert.equal(1, 2);
-  // AssertionError: 1 == 2
+
+// Throws an exception: AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
 assert.equal({a: {b: 1}}, {a: {b: 1}});
-  //AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
 ```
 
 If the values are not equal, an `AssertionError` is thrown with a `message`
@@ -207,14 +202,16 @@ Throws an `AssertionError`. If `message` is falsy, the error message is set as
 the values of `actual` and `expected` separated by the provided `operator`.
 Otherwise, the error message is the value of `message`.
 
+Examples:
+
 ```js
 const assert = require('assert');
 
+// Throws an exception: AssertionError: 1 > 2
 assert.fail(1, 2, undefined, '>');
-  // AssertionError: 1 > 2
 
+// Throws an exception: AssertionError: whoops
 assert.fail(1, 2, 'whoops', '>');
-  // AssertionError: whoops
 ```
 
 ## assert.ifError(value)
@@ -225,13 +222,22 @@ added: v0.1.97
 Throws `value` if `value` is truthy. This is useful when testing the `error`
 argument in callbacks.
 
+Examples:
+
 ```js
 const assert = require('assert');
 
-assert.ifError(0); // OK
+// OK
+assert.ifError(0);
+
+// Throws an exception: 1
 assert.ifError(1); // Throws 1
-assert.ifError('error'); // Throws 'error'
-assert.ifError(new Error()); // Throws Error
+
+// Throws an exception: error
+assert.ifError('error');
+
+// Throws an exception: Error
+assert.ifError(new Error());
 ```
 
 ## assert.notDeepEqual(actual, expected[, message])
@@ -241,37 +247,39 @@ added: v0.1.21
 
 Tests for any deep inequality. Opposite of [`assert.deepEqual()`][].
 
+Examples:
+
 ```js
 const assert = require('assert');
 
 const obj1 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
 };
 const obj2 = {
-  a : {
-    b : 2
+  a: {
+    b: 2
   }
 };
 const obj3 = {
-  a : {
-    b : 1
+  a: {
+    b: 1
   }
-}
+};
 const obj4 = Object.create(obj1);
 
-assert.notDeepEqual(obj1, obj1);
-  // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
-
+// OK
 assert.notDeepEqual(obj1, obj2);
-  // OK, obj1 and obj2 are not deeply equal
-
-assert.notDeepEqual(obj1, obj3);
-  // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
 
+// OK
 assert.notDeepEqual(obj1, obj4);
-  // OK, obj1 and obj2 are not deeply equal
+
+// Throws an exception: AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
+assert.notDeepEqual(obj1, obj1);
+
+// Throws an exception: AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
+assert.notDeepEqual(obj1, obj3);
 ```
 
 If the values are deeply equal, an `AssertionError` is thrown with a `message`
@@ -285,14 +293,20 @@ added: v1.2.0
 
 Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
 
+Examples:
+
 ```js
 const assert = require('assert');
 
-assert.notDeepEqual({a:1}, {a:'1'});
-  // AssertionError: { a: 1 } notDeepEqual { a: '1' }
+const obj1 = {
+  a: 1
+};
+const obj2 = {
+  a: '1'
+};
 
-assert.notDeepStrictEqual({a:1}, {a:'1'});
-  // OK
+// OK
+assert.notDeepStrictEqual(obj1, obj2);
 ```
 
 If the values are deeply and strictly equal, an `AssertionError` is thrown
@@ -307,17 +321,19 @@ added: v0.1.21
 Tests shallow, coercive inequality with the not equal comparison operator
 ( `!=` ).
 
+Examples:
+
 ```js
 const assert = require('assert');
 
+// OK
 assert.notEqual(1, 2);
-  // OK
 
+// Throws an exception: AssertionError: 1 != 1
 assert.notEqual(1, 1);
-  // AssertionError: 1 != 1
 
+// Throws an exception: AssertionError: 1 != '1'
 assert.notEqual(1, '1');
-  // AssertionError: 1 != '1'
 ```
 
 If the values are equal, an `AssertionError` is thrown with a `message`
@@ -332,22 +348,20 @@ added: v0.1.21
 Tests strict inequality as determined by the strict not equal operator
 ( `!==` ).
 
+Examples:
+
 ```js
 const assert = require('assert');
 
+// OK
 assert.notStrictEqual(1, 2);
-  // OK
-
-assert.notStrictEqual(1, 1);
-  // AssertionError: 1 != 1
 
+// OK
 assert.notStrictEqual(1, '1');
-  // OK
-```
 
-If the values are strictly equal, an `AssertionError` is thrown with a
-`message` property set equal to the value of the `message` parameter. If the
-`message` parameter is undefined, a default error message is assigned.
+// Throws an exception: AssertionError: 1 != 1
+assert.notStrictEqual(1, 1);
+```
 
 ## assert.ok(value[, message])
 <!-- YAML
@@ -361,17 +375,25 @@ If `value` is not truthy, an `AssertionError` is thrown with a `message`
 property set equal to the value of the `message` parameter. If the `message`
 parameter is `undefined`, a default error message is assigned.
 
+Examples:
+
 ```js
 const assert = require('assert');
 
-assert.ok(true);  // OK
-assert.ok(1);     // OK
+// OK
+assert.ok(true);
+
+// OK
+assert.ok(1);
+
+// Throws an exception: AssertionError: false == true
 assert.ok(false);
-  // throws "AssertionError: false == true"
+
+// Throws an exception: AssertionError: 0 == true
 assert.ok(0);
-  // throws "AssertionError: 0 == true"
-assert.ok(false, 'it\'s false');
-  // throws "AssertionError: it's false"
+
+// Throws an exception: AssertionError: it's false
+assert.ok(false, 'it is false');
 ```
 
 ## assert.strictEqual(actual, expected[, message])
@@ -381,17 +403,19 @@ added: v0.1.21
 
 Tests strict equality as determined by the strict equality operator ( `===` ).
 
+Examples:
+
 ```js
 const assert = require('assert');
 
-assert.strictEqual(1, 2);
-  // AssertionError: 1 === 2
-
+// OK
 assert.strictEqual(1, 1);
-  // OK
 
+// Throws an exception: AssertionError: 1 === 2
+assert.strictEqual(1, 2);
+
+// Throws an exception: AssertionError: 1 === '1'
 assert.strictEqual(1, '1');
-  // AssertionError: 1 === '1'
 ```
 
 If the values are not strictly equal, an `AssertionError` is thrown with a
@@ -410,8 +434,7 @@ function.
 
 If specified, `message` will be the message provided by the `AssertionError` if
 the block fails to throw.
-
-Validate instanceof using constructor:
+Example: Match a thrown exception by constructor
 
 ```js
 assert.throws(
@@ -422,7 +445,7 @@ assert.throws(
 );
 ```
 
-Validate error message using [`RegExp`][]:
+Example: Match a thrown exception by testing its message with a [`RegExp`]
 
 ```js
 assert.throws(
@@ -433,15 +456,15 @@ assert.throws(
 );
 ```
 
-Custom error validation:
+Example: Match a thrown exception using a custom validation function
 
 ```js
 assert.throws(
   () => {
     throw new Error('Wrong value');
   },
-  function(err) {
-    if ( (err instanceof Error) && /value/.test(err) ) {
+  (err) => {
+    if ((err instanceof Error) && /value/.test(err)) {
       return true;
     }
   },
@@ -451,13 +474,15 @@ assert.throws(
 
 Note that `error` can not be a string. If a string is provided as the second
 argument, then `error` is assumed to be omitted and the string will be used for
-`message` instead. This can lead to easy-to-miss mistakes:
+`message` instead. This can lead to easy-to-miss mistakes.
+
+Example:
 
 ```js
 // THIS IS A MISTAKE! DO NOT DO THIS!
 assert.throws(myFunction, 'missing foo', 'did not throw with expected message');
 
-// Do this instead.
+// Do this instead
 assert.throws(myFunction, /missing foo/, 'did not throw with expected message');
 ```
 

From 9921539ce474b25cd0b6e9f02597521d2a226039 Mon Sep 17 00:00:00 2001
From: Brian White <mscdex@mscdex.net>
Date: Thu, 21 Jul 2016 01:11:05 -0400
Subject: [PATCH 3/3] doc: improve assert function descriptions

This commit uses more consistent language in function descriptions
and adds function parameter and return type information.
---
 doc/api/assert.md | 206 ++++++++++++++++++++++++++++++----------------
 1 file changed, 134 insertions(+), 72 deletions(-)

diff --git a/doc/api/assert.md b/doc/api/assert.md
index 8409ab758b011f..877bb1de89f02f 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -8,9 +8,8 @@ used in application code via `require('assert')`. However, `assert` is not a
 testing framework, and is not intended to be used as a general purpose assertion
 library.
 
-The API for the `assert` module is [Locked][]. This means that there will be no
-additions or changes to any of the methods implemented and exposed by
-the module.
+The API for the `assert` module is [Locked]. This means that there will be no
+additions or changes to any of the methods implemented and exposed by this module.
 
 ## assert(value[, message])
 <!-- YAML
@@ -24,14 +23,21 @@ An alias of [`assert.ok()`].
 added: v0.1.21
 -->
 
-Tests for deep equality between the `actual` and `expected` parameters.
-Primitive values are compared with the equal comparison operator ( `==` ).
+* `actual` {mixed} A value to check
+* `expected` {mixed} The expected value of `actual`
+* `message` {String} The exception message to use when `actual` and `expected`
+  are not equal. If not supplied, then a generated message containing `actual`
+  and `expected` is used.
+* Return: `undefined`
 
-Only enumerable "own" properties are considered. The `deepEqual()`
+Tests *deep* equality between `actual` and `expected` as determined by the `==`
+operator. If `actual` and `expected` are not equal, then an `AssertionError`
+exception is thrown.
+
+Only enumerable "own" properties are considered. The `assert.deepEqual()`
 implementation does not test object prototypes, attached symbols, or
 non-enumerable properties. This can lead to some potentially surprising
-results. For example, the following example does not throw an `AssertionError`
-because the properties on the [`Error`][] object are non-enumerable:
+results.
 
 Example: The following does not throw an `AssertionError` because the properties
 on the [`Error`] object are non-enumerable
@@ -44,7 +50,7 @@ assert.deepEqual(Error('a'), Error('b'));
 ```
 
 "Deep" equality means that the enumerable "own" properties of child objects
-are evaluated also:
+are evaluated as well.
 
 Examples:
 
@@ -83,18 +89,22 @@ assert.deepEqual(obj1, obj2);
 assert.deepEqual(obj1, obj4);
 ```
 
-If the values are not equal, an `AssertionError` is thrown with a `message`
-property set equal to the value of the `message` parameter. If the `message`
-parameter is undefined, a default error message is assigned.
-
 ## assert.deepStrictEqual(actual, expected[, message])
 <!-- YAML
 added: v1.2.0
 -->
 
-Generally identical to `assert.deepEqual()` with two exceptions. First,
-primitive values are compared using the strict equality operator ( `===` ).
-Second, object comparisons include a strict equality check of their prototypes.
+* `actual` {mixed} A value to check
+* `expected` {mixed} The expected value of `actual`
+* `message` {String} The exception message to use when `actual` and `expected`
+  are not equal. If not supplied, then a generated message containing `actual`
+  and `expected` is used.
+
+Tests *deep* equality between `actual` and `expected` as determined by the `===`
+operator. If `actual` and `expected` are not equal, then an `AssertionError`
+exception is thrown.
+
+Object comparisons include a strict equal check of their prototypes.
 
 Example:
 
@@ -112,25 +122,24 @@ const obj2 = {
 assert.deepStrictEqual(obj1, obj2);
 ```
 
-If the values are not equal, an `AssertionError` is thrown with a `message`
-property set equal to the value of the `message` parameter. If the `message`
-parameter is undefined, a default error message is assigned.
-
 ## assert.doesNotThrow(block[, error][, message])
 <!-- YAML
 added: v0.1.21
 -->
 
-Asserts that the function `block` does not throw an error. See
-[`assert.throws()`][] for more details.
+* `block` {Function} A function that is not expected to throw an exception
+* `error` {Function | RegExp} A constructor, regular expression, or validation
+  function to be used when matching an exception thrown by `block`
+* `message` {String} A message that is appended to the exception thrown when
+  `block` fails to throw an exception.
+* Return: `undefined`
 
-When `assert.doesNotThrow()` is called, it will immediately call the `block`
-function.
+Calls the function `block`, not expecting an exception to be thrown. If `block`
+throws an exception that matches `error`, an `AssertionError` exception is thrown.
+If the exception does *not* match `error` (or `error` is not supplied), then the
+original exception is re-thrown.
 
-If an error is thrown and it is the same type as that specified by the `error`
-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.
+This function is the opposite of [`assert.throws()`].
 
 Examples:
 
@@ -168,8 +177,16 @@ assert.doesNotThrow(
 added: v0.1.21
 -->
 
-Tests shallow, coercive equality between the `actual` and `expected` parameters
-using the equal comparison operator ( `==` ).
+* `actual` {mixed} A value to check
+* `expected` {mixed} The expected value of `actual`
+* `message` {String} The exception message to use when `actual` and `expected`
+  are not equal. If not supplied, then a generated message containing `actual`
+  and `expected` is used.
+* Return: `undefined`
+
+Tests equality between `actual` and `expected` as determined by the (shallow
+and coercive) `==` operator. If `actual` and `expected` are not equal, then an
+`AssertionError` exception is thrown.
 
 Examples:
 
@@ -189,18 +206,21 @@ assert.equal(1, 2);
 assert.equal({a: {b: 1}}, {a: {b: 1}});
 ```
 
-If the values are not equal, an `AssertionError` is thrown with a `message`
-property set equal to the value of the `message` parameter. If the `message`
-parameter is undefined, a default error message is assigned.
-
 ## assert.fail(actual, expected, message, operator)
 <!-- YAML
 added: v0.1.21
 -->
 
-Throws an `AssertionError`. If `message` is falsy, the error message is set as
-the values of `actual` and `expected` separated by the provided `operator`.
-Otherwise, the error message is the value of `message`.
+* `actual` {mixed} A value to check
+* `expected` {mixed} The expected value of `actual`
+* `message` {String} The exception message to use. If not supplied, then a
+  generated message containing `actual` and `expected` is used.
+* `operator` {String} If `message` is not specified, this is a comparison operator
+  that is inserted between `actual` and `expected` in the generated exception
+  message.
+* Return: `undefined`
+
+Always throws an `AssertionError`.
 
 Examples:
 
@@ -219,8 +239,11 @@ assert.fail(1, 2, 'whoops', '>');
 added: v0.1.97
 -->
 
-Throws `value` if `value` is truthy. This is useful when testing the `error`
-argument in callbacks.
+* `value` {mixed}
+* Return: `undefined`
+
+Throws `value` if `value` evaluates to `true`. This is useful when testing the
+error argument in callbacks.
 
 Examples:
 
@@ -245,7 +268,22 @@ assert.ifError(new Error());
 added: v0.1.21
 -->
 
-Tests for any deep inequality. Opposite of [`assert.deepEqual()`][].
+* `actual` {mixed} A value to check
+* `expected` {mixed} The expected value of `actual`
+* `message` {String} The exception message to use when `actual` and `expected`
+  are equal. If not supplied, then a generated message containing `actual` and
+  `expected` is used.
+
+Tests *deep* inequality between `actual` and `expected` as determined by the `!=`
+operator. If `actual` and `expected` are equal, then an `AssertionError`
+exception is thrown.
+
+Only enumerable "own" properties are considered. The `assert.notDeepEqual()`
+implementation does not test object prototypes, attached symbols, or
+non-enumerable properties. This can lead to some potentially surprising
+results.
+
+This function is the opposite of [`assert.deepEqual()`].
 
 Examples:
 
@@ -282,16 +320,24 @@ assert.notDeepEqual(obj1, obj1);
 assert.notDeepEqual(obj1, obj3);
 ```
 
-If the values are deeply equal, an `AssertionError` is thrown with a `message`
-property set equal to the value of the `message` parameter. If the `message`
-parameter is undefined, a default error message is assigned.
-
 ## assert.notDeepStrictEqual(actual, expected[, message])
 <!-- YAML
 added: v1.2.0
 -->
 
-Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
+* `actual` {mixed} A value to check
+* `expected` {mixed} The expected value of `actual`
+* `message` {String} The exception message to use when `actual` and `expected`
+  are equal. If not supplied, then a generated message containing `actual` and
+  `expected` is used.
+
+Tests *deep* inequality between `actual` and `expected` as determined by the `!==`
+operator. If `actual` and `expected` are equal, then an `AssertionError`
+exception is thrown.
+
+Object comparisons include a not strict equal check of their prototypes.
+
+This function is the opposite of [`assert.deepStrictEqual()`].
 
 Examples:
 
@@ -309,17 +355,20 @@ const obj2 = {
 assert.notDeepStrictEqual(obj1, obj2);
 ```
 
-If the values are deeply and strictly equal, an `AssertionError` is thrown
-with a `message` property set equal to the value of the `message` parameter. If
-the `message` parameter is undefined, a default error message is assigned.
-
 ## assert.notEqual(actual, expected[, message])
 <!-- YAML
 added: v0.1.21
 -->
 
-Tests shallow, coercive inequality with the not equal comparison operator
-( `!=` ).
+* `actual` {mixed} A value to check
+* `expected` {mixed} The expected value of `actual`
+* `message` {String} The exception message to use when `actual` and `expected`
+  are equal. If not supplied, then a generated message containing `actual` and
+  `expected` is used.
+
+Tests inequality between `actual` and `expected` as determined by the (shallow
+and coercive) `!=` operator. If `actual` and `expected` are equal, then an
+`AssertionError` exception is thrown.
 
 Examples:
 
@@ -336,17 +385,20 @@ assert.notEqual(1, 1);
 assert.notEqual(1, '1');
 ```
 
-If the values are equal, an `AssertionError` is thrown with a `message`
-property set equal to the value of the `message` parameter. If the `message`
-parameter is undefined, a default error message is assigned.
-
 ## assert.notStrictEqual(actual, expected[, message])
 <!-- YAML
 added: v0.1.21
 -->
 
-Tests strict inequality as determined by the strict not equal operator
-( `!==` ).
+* `actual` {mixed} A value to check
+* `expected` {mixed} The expected value of `actual`
+* `message` {String} The exception message to use when `actual` and `expected`
+  are equal. If not supplied, then a generated message containing `actual` and
+  `expected` is used.
+
+Tests inequality between `actual` and `expected` as determined by the `!==`
+operator. If `actual` and `expected` are equal, then an `AssertionError` exception
+is thrown.
 
 Examples:
 
@@ -368,12 +420,15 @@ assert.notStrictEqual(1, 1);
 added: v0.1.21
 -->
 
-Tests if `value` is truthy. It is equivalent to
-`assert.equal(!!value, true, message)`.
+* `value` {mixed} A value to check
+* `message` {String} The exception message to use when `value` does not evaluate
+  to `true`. If not supplied, then a generated message containing `value` is used.
+* Return: `undefined`
 
-If `value` is not truthy, an `AssertionError` is thrown with a `message`
-property set equal to the value of the `message` parameter. If the `message`
-parameter is `undefined`, a default error message is assigned.
+Tests if `value` evaluates to `true`. If `value` does not evaluate to `true`,
+then an `AssertionError` exception is thrown.
+
+This function is equivalent to `assert.equal(!!value, true, message)`.
 
 Examples:
 
@@ -401,7 +456,15 @@ assert.ok(false, 'it is false');
 added: v0.1.21
 -->
 
-Tests strict equality as determined by the strict equality operator ( `===` ).
+* `actual` {mixed} A value to check
+* `expected` {mixed} The expected value of `actual`
+* `message` {String} The exception message to use when `actual` and `expected`
+  are not equal. If not supplied, then a generated message containing `actual`
+  and `expected` is used.
+
+Tests equality between `actual` and `expected` as determined by the `===`
+operator. If `actual` and `expected` are not equal, then an `AssertionError`
+exception is thrown.
 
 Examples:
 
@@ -418,22 +481,21 @@ assert.strictEqual(1, 2);
 assert.strictEqual(1, '1');
 ```
 
-If the values are not strictly equal, an `AssertionError` is thrown with a
-`message` property set equal to the value of the `message` parameter. If the
-`message` parameter is undefined, a default error message is assigned.
-
 ## assert.throws(block[, error][, message])
 <!-- YAML
 added: v0.1.21
 -->
 
-Expects the function `block` to throw an error.
+* `block` {Function} A function that is expected to throw an exception
+* `error` {Function | RegExp} A constructor, regular expression, or validation
+  function to be used when matching an exception thrown by `block`
+* `message` {String} The exception message to use when `block` fails to throw an
+  exception. If not supplied, then a generic, generated message is used.
+* Return: `undefined`
 
-If specified, `error` can be a constructor, [`RegExp`][], or validation
-function.
+Calls the function `block`, expecting an exception to be thrown. If `block`
+does not throw an exception, an `AssertionError` exception is thrown.
 
-If specified, `message` will be the message provided by the `AssertionError` if
-the block fails to throw.
 Example: Match a thrown exception by constructor
 
 ```js