doc,assert: consolidate introductory text

doc/api/assert.md

@@ -5,68 +5,7 @@
 > Stability: 2 - Stable
 
 The `assert` module provides a set of assertion functions for verifying
-invariants. The module provides a recommended [strict assertion mode][]
-and a more lenient legacy assertion mode.
-
-## Class: assert.AssertionError
-
-* Extends: {errors.Error}
-
-Indicates the failure of an assertion. All errors thrown by the `assert` module
-will be instances of the `AssertionError` class.
-
-### `new assert.AssertionError(options)`
-<!-- YAML
-added: v0.1.21
--->
-
-* `options` {Object}
-  * `message` {string} If provided, the error message is set to this value.
-  * `actual` {any} The `actual` property on the error instance.
-  * `expected` {any} The `expected` property on the error instance.
-  * `operator` {string} The `operator` property on the error instance.
-  * `stackStartFn` {Function} If provided, the generated stack trace omits
-    frames before this function.
-
-A subclass of `Error` that indicates the failure of an assertion.
-
-All instances contain the built-in `Error` properties (`message` and `name`)
-and:
-
-* `actual` {any} Set to the `actual` argument for methods such as
-  [`assert.strictEqual()`][].
-* `expected` {any} Set to the `expected` value for methods such as
-  [`assert.strictEqual()`][].
-* `generatedMessage` {boolean} Indicates if the message was auto-generated
-  (`true`) or not.
-* `code` {string} Value is always `ERR_ASSERTION` to show that the error is an
-  assertion error.
-* `operator` {string} Set to the passed in operator value.
-
-```js
-const assert = require('assert');
-
-// Generate an AssertionError to compare the error message later:
-const { message } = new assert.AssertionError({
-  actual: 1,
-  expected: 2,
-  operator: 'strictEqual'
-});
-
-// Verify error output:
-try {
-  assert.strictEqual(1, 2);
-} catch (err) {
-  assert(err instanceof assert.AssertionError);
-  assert.strictEqual(err.message, message);
-  assert.strictEqual(err.name, 'AssertionError');
-  assert.strictEqual(err.actual, 1);
-  assert.strictEqual(err.expected, 2);
-  assert.strictEqual(err.code, 'ERR_ASSERTION');
-  assert.strictEqual(err.operator, 'strictEqual');
-  assert.strictEqual(err.generatedMessage, true);
-}
-```
+invariants.
 
 ## Strict assertion mode
 <!-- YAML
@@ -84,9 +23,9 @@ changes:
     description: Added strict assertion mode to the assert module.
 -->
 
-In strict assertion mode, `assert` functions use the comparison in the
-corresponding strict functions. For example, [`assert.deepEqual()`][] will
-behave like [`assert.deepStrictEqual()`][].
+In strict assertion mode, non-strict methods behave like their corresponding
+strict methods. For example, [`assert.deepEqual()`][] will behave like
+[`assert.deepStrictEqual()`][].
 
 In strict assertion mode, error messages for objects display a diff. In legacy
 assertion mode, error messages for objects display the objects, often truncated.
@@ -150,6 +89,66 @@ lax:
 assert.deepEqual(/a/gi, new Date());
 ```
 
+## Class: assert.AssertionError
+
+* Extends: {errors.Error}
+
+Indicates the failure of an assertion. All errors thrown by the `assert` module
+will be instances of the `AssertionError` class.
+
+### `new assert.AssertionError(options)`
+<!-- YAML
+added: v0.1.21
+-->
+
+* `options` {Object}
+  * `message` {string} If provided, the error message is set to this value.
+  * `actual` {any} The `actual` property on the error instance.
+  * `expected` {any} The `expected` property on the error instance.
+  * `operator` {string} The `operator` property on the error instance.
+  * `stackStartFn` {Function} If provided, the generated stack trace omits
+    frames before this function.
+
+A subclass of `Error` that indicates the failure of an assertion.
+
+All instances contain the built-in `Error` properties (`message` and `name`)
+and:
+
+* `actual` {any} Set to the `actual` argument for methods such as
+  [`assert.strictEqual()`][].
+* `expected` {any} Set to the `expected` value for methods such as
+  [`assert.strictEqual()`][].
+* `generatedMessage` {boolean} Indicates if the message was auto-generated
+  (`true`) or not.
+* `code` {string} Value is always `ERR_ASSERTION` to show that the error is an
+  assertion error.
+* `operator` {string} Set to the passed in operator value.
+
+```js
+const assert = require('assert');
+
+// Generate an AssertionError to compare the error message later:
+const { message } = new assert.AssertionError({
+  actual: 1,
+  expected: 2,
+  operator: 'strictEqual'
+});
+
+// Verify error output:
+try {
+  assert.strictEqual(1, 2);
+} catch (err) {
+  assert(err instanceof assert.AssertionError);
+  assert.strictEqual(err.message, message);
+  assert.strictEqual(err.name, 'AssertionError');
+  assert.strictEqual(err.actual, 1);
+  assert.strictEqual(err.expected, 2);
+  assert.strictEqual(err.code, 'ERR_ASSERTION');
+  assert.strictEqual(err.operator, 'strictEqual');
+  assert.strictEqual(err.generatedMessage, true);
+}
+```
+
 ## `assert(value[, message])`
 <!-- YAML
 added: v0.5.9