doc: properly document AssertionError

The AssertionError was always exposed but never properly documented.
This explains how it is used and what options it accepts.

PR-URL: https://github.com/nodejs/node/pull/19724
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

doc/api/assert.md

@@ -13,6 +13,70 @@ 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: assert.AssertionError
+
+A subclass of `Error` that 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 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 (`message` and `name`)
+and:
+
+* `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 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 [ERR_ASSERTION]');
+  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);
+}
+```
+
 ## 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 details,
+see [`Class: assert.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: assert.AssertionError`]: assert.html#assert_class_assert_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