doc: improve assert.markdown copy

General improvements to assert.markdown copy including
new and improved examples

Author: jasnell

doc/api/assert.markdown

@@ -2,42 +2,131 @@
 
     Stability: 3 - Locked
 
-This module is used so that Node.js can test itself. It can be accessed with
-`require('assert')`. However, it is recommended that a userland assertion
-library be used instead.
+The `assert` module provides a simple set of assertion tests that can be used
+to test invariants and implement unit tests. While the `assert` module is
+generally intended for internal use by Node.js itself, it can be used by user
+code calling `require('assert')`.
+
+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.
 
 ## assert(value[, message]), assert.ok(value[, message])
 
-Tests if value is truthy. It is equivalent to
+Tests if `value` is truthy. It is equivalent to
 `assert.equal(!!value, true, message)`.
 
+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.
+
+    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"
+
+    assert.ok(true);  // OK
+    assert.ok(1);     // OK
+    assert.ok(false);
+      // throws "AssertionError: false == true"
+    assert.ok(0);     
+      // throws "AssertionError: 0 == true"
+    assert.ok(false, 'it\'s false');
+      // throws "AssertionError: it's false"
+
 ## assert.deepEqual(actual, expected[, message])
 
-Tests for deep equality. Primitive values are compared with the equal
-comparison operator ( `==` ).
+Tests for deep equality between the `actual` and `expected` parameters.
+Primitive values are compared with the equal comparison operator ( `==` ).
 
-This only considers enumerable properties. It does not test object prototypes,
-attached symbols, or non-enumerable properties. This can lead to some
-potentially surprising results. For example, this does not throw an
-`AssertionError` because the properties on the [`Error`][] object are
-non-enumerable:
+Only enumerable "own" properties are considered. The `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:
 
     // WARNING: This does not throw an AssertionError!
     assert.deepEqual(Error('a'), Error('b'));
 
+"Deep" equality means that the enumerable "own" properties of child objects
+are evaluated also:
+
+    const assert = require('assert');
+    
+    const obj1 = {
+      a : {
+        b : 1
+      }
+    };
+    const obj2 = {
+      a : {
+        b : 2
+      }
+    };
+    const obj3 = {
+      a : {
+        b : 1
+      }
+    }
+    const obj4 = Object.create(obj1);
+    
+    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
+      
+    assert.deepEqual(obj1, obj3);
+      // OK, objects are equal
+      
+    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`
+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])
 
-Tests for deep equality. Primitive values are compared with the strict equality
-operator ( `===` ).
+Generally identical to `assert.deepEqual` with the exception that primitive
+values are compared using the strict equality operator ( `===` ).
+
+    const assert = require('assert');
+    
+    assert.deepEqual({a:1}, {a:'1'});
+      // OK, because 1 == '1'
+      
+    assert.deepStrictEqual({a:1}, {a:'1'});
+      // AssertionError: { a: 1 } deepStrictEqual { a: '1' }
+      // because 1 !== '1' using strict equality
+
+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])
 
-Expects `block` not to throw an error. See [`assert.throws()`][] for more details.
+Asserts that the function `block` does not throw an error. See
+[`assert.throws()`][] 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.
+When `assert.doesNotThrow()` is called, it will immediately call the `block`
+function.
+
+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.
+
+The following, for instance, will throw the [`TypeError`][] because there is no
+matching error type in the assertion:
 
     assert.doesNotThrow(
       function() {
@@ -46,8 +135,8 @@ assertion.
       SyntaxError
     );
 
-In case `error` matches with the error thrown by `block`, an `AssertionError`
-is thrown instead.
+However, the following will result in an `AssertionError` with the message
+'Got unwanted exception (TypeError)..':
 
     assert.doesNotThrow(
       function() {
@@ -56,47 +145,184 @@ is thrown instead.
       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:
+
+    assert.doesNotThrow(
+      function() {
+        throw new TypeError('Wrong value');
+      },
+      TypeError,
+      'Whoops'
+    );
+    // Throws: AssertionError: Got unwanted exception (TypeError). Whoops
+
 ## assert.equal(actual, expected[, message])
 
-Tests shallow, coercive equality with the equal comparison operator ( `==` ).
+Tests shallow, coercive equality between the `actual` and `expected` parameters
+using the equal comparison operator ( `==` ).
+
+    const assert = require('assert');
+    
+    assert.equal(1, 1);
+      // OK, 1 == 1
+    assert.equal(1, '1');
+      // OK, 1 == '1'
+      
+    assert.equal(1, 2);
+      // AssertionError: 1 == 2
+    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`
+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)
 
-Throws an `AssertionError`. If `message` is falsy, it displays the values for
-`actual` and `expected` separated by the provided `operator`. Otherwise, it
-displays `message` (and does not use `actual`, `expected`, and `operator`).
+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`.
+
+    const assert = require('assert');
+    
+    assert.fail(1, 2, undefined, '>');
+      // AssertionError: 1 > 2
+    
+    assert.fail(1, 2, 'whoops', '>');
+      // AssertionError: whoops
 
 ## assert.ifError(value)
 
 Throws `value` if `value` is truthy. This is useful when testing the `error`
 argument in callbacks.
 
+    const assert = require('assert');
+    
+    assert.ifError(0); // OK
+    assert.ifError(1); // Throws 1
+    assert.ifError('error') // Throws 'error'
+    assert.ifError(new Error()); // Throws Error
+
 ## assert.notDeepEqual(actual, expected[, message])
 
 Tests for any deep inequality. Opposite of [`assert.deepEqual`][].
 
+    const assert = require('assert');
+
+    const obj1 = {
+      a : {
+        b : 1
+      }
+    };
+    const obj2 = {
+      a : {
+        b : 2
+      }
+    };
+    const obj3 = {
+      a : {
+        b : 1
+      }
+    }
+    const obj4 = Object.create(obj1);
+
+    assert.deepEqual(obj1, obj1);
+      AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
+      
+    assert.deepEqual(obj1, obj2);
+      // OK, obj1 and obj2 are not deeply equal
+      
+    assert.deepEqual(obj1, obj3);
+      // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
+      
+    assert.deepEqual(obj1, obj4);
+      // OK, obj1 and obj2 are not deeply equal
+
+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])
 
-Tests for deep inequality. Opposite of [`assert.deepStrictEqual`][].
+Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual`][].
+
+    const assert = require('assert');
+
+    assert.notDeepEqual({a:1}, {a:'1'});
+      // AssertionError: { a: 1 } notDeepEqual { a: '1' }
+      
+    assert.notDeepStrictEqual({a:1}, {a:'1'});
+      // OK
+
+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])
 
 Tests shallow, coercive inequality with the not equal comparison operator
 ( `!=` ).
 
+    const assert = require('assert');
+    
+    assert.notEqual(1, 2);
+      // OK
+    
+    assert.notEqual(1, 1);
+      // AssertionError: 1 != 1
+
+    assert.notEqual(1, '1');
+      // AssertionError: 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])
 
 Tests strict inequality as determined by the strict not equal operator
 ( `!==` ).
 
+    const assert = require('assert');
+
+    assert.notStrictEqual(1, 2);
+      // OK
+
+    assert.notStrictEqual(1, 1);
+      // AssertionError: 1 != 1
+
+    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.
+
 ## assert.strictEqual(actual, expected[, message])
 
 Tests strict equality as determined by the strict equality operator ( `===` ).
 
+    const assert = require('assert');
+
+    assert.strictEqual(1, 2);
+      // AssertionError: 1 === 2
+
+    assert.strictEqual(1, 1);
+      // OK
+
+    assert.strictEqual(1, '1');
+      // AssertionError: 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])
 
-Expects `block` to throw an error. `error` can be a constructor, [`RegExp`][], or
-validation function.
+Expects the function `block` to throw an error. If specified, `error` can be a
+constructor, [`RegExp`][], or validation function.
 
 Validate instanceof using constructor:
 
@@ -130,6 +356,7 @@ Custom error validation:
       'unexpected error'
     );
 
+[Locked]: documentation.html#documentation_stability_index
 [`assert.deepEqual`]: #assert_assert_deepequal_actual_expected_message
 [`assert.deepStrictEqual`]: #assert_assert_deepstrictequal_actual_expected_message
 [`assert.throws()`]: #assert_assert_throws_block_error_message