Add assertion error docs

doc/api/assert.md

@@ -1,6 +1,6 @@
 # Assert
 
-<!--introduced_in=v0.10.0-->
+<!--introduced_in=v0.1.21-->
 
 > Stability: 2 - Stable
 
@@ -13,6 +13,71 @@ A `strict` and a `legacy` mode exist, while it is recommended to only use
 For more information about the used equality comparisons see
 [MDN's guide on equality comparisons and sameness][mdn-equality-guide].
 
+## Class: AssertionError
+
+A subclass of `Error` that indicates the failure of an assertion.
+All errors thrown by the assert module will be instance of the `AssertionError`
+class.
+
+### new AssertionError(options)
+<!-- YAML
+added: v0.1.21
+-->
+* `options` {Object}
+  * `message` {string} If provided, the error message is going to be set to this
+    value.
+  * `actual` {any} The `actual` property on the error instance is going to
+    contain this value. Internally used for the `actual` error input in case
+    e.g., [`assert.strictEqual()`] is used.
+  * `expected` {any} The `expected` property on the error instance is going to
+    contain this value. Internally used for the `expected` error input in case
+    e.g., [`assert.strictEqual()`] is used.
+  * `operator` {string} The `operator` property on the error instance is going
+    to contain this value. Internally used to indicate what operation was used
+    for comparison (or what assertion function triggered the error).
+  * `stackStartFn` {Function} If provided, the generated stack trace is going to
+    remove all frames up to the provided function.
+
+A subclass of `Error` that indicates the failure of an assertion.
+
+All instances contain the built-in Error properties (i.e., `message` and `name`)
+plus the following:
+
+* `actual` {any} Set to the actual value in case e.g.,
+  [`assert.strictEqual()`] is used.
+* `expected` {any} Set to the expected value in case e.g.,
+  [`assert.strictEqual()`] is used.
+* `generatedMessage` {boolean} Indicates if the message was auto generated
+  (`true`) or not.
+* `code` {string} This is always set to the string `ERR_ASSERTION` to indicate
+  that the error is actually a assertion error.
+* `operator` {string} Set to the passed in operator value.
+
+```js
+const assert = require('assert');
+
+// Generate a AssertionError to compare the error message later:.
+const { message } = new assert.AssertionError({
+  actual: 1,
+  expected: 2,
+  operator: '=='
+});
+
+// Verify error output:
+try {
+  assert.equal(1, 2);
+} catch (err) {
+  assert(err instanceof assert.AssertionError);
+  assert.equal(err.message, message);
+  assert.equal(err.name, 'AssertionError [ERR_ASSERTION]');
+  assert.equal(err.actual, 1);
+  assert.equal(err.expected, 2);
+  assert.equal(err.code, 'ERR_ASSERTION');
+  assert.equal(err.operator, '==');
+  assert.equal(err.generatedMessage, true);
+}
+```
+
 ## Strict mode
 <!-- YAML
 added: v9.9.0

doc/api/errors.md

@@ -364,13 +364,8 @@ detailed [here](#errors_system_errors).
 
 ## Class: AssertionError
 
-A subclass of `Error` that indicates the failure of an assertion. Such errors
-commonly indicate inequality of actual and expected value.
-
-```js
-assert.strictEqual(1, 2);
-// AssertionError [ERR_ASSERTION]: 1 === 2
-```
+A subclass of `Error` that indicates the failure of an assertion. For further
+details check asserts [`Class: AssertionError`][].
 
 ## Class: RangeError
 
@@ -1680,6 +1675,7 @@ Creation of a [`zlib`][] object failed due to incorrect configuration.
 [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`require('crypto').setEngine()`]: crypto.html#crypto_crypto_setengine_engine_flags
 [`server.listen()`]: net.html#net_server_listen
+[`Class: AssertionError`]: assert.html#class_assertionerror
 [ES6 module]: esm.html
 [Node.js Error Codes]: #nodejs-error-codes
 [V8's stack trace API]: https://github.com/v8/v8/wiki/Stack-Trace-API