From e849e7444477a0900f7f1d394a968e1e59d3cc76 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Wed, 5 Feb 2025 14:59:37 +0100 Subject: [PATCH] doc: make MDN links to global classes more consistent in `assert.md` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/56920 Reviewed-By: Michaël Zasso Reviewed-By: Luigi Pinca --- doc/api/assert.md | 70 +++++++++++++++++++++-------------------------- 1 file changed, 31 insertions(+), 39 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 7b5ff9ee4fe804..89e255771408d0 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -150,7 +150,7 @@ added: v0.1.21 * `stackStartFn` {Function} If provided, the generated stack trace omits frames before this function. -A subclass of `Error` that indicates the failure of an assertion. +A subclass of {Error} that indicates the failure of an assertion. All instances contain the built-in `Error` properties (`message` and `name`) and: @@ -623,23 +623,23 @@ are also recursively evaluated by the following rules. ### Comparison details * Primitive values are compared with the [`==` operator][], - with the exception of `NaN`. It is treated as being identical in case - both sides are `NaN`. + with the exception of {NaN}. It is treated as being identical in case + both sides are {NaN}. * [Type tags][Object.prototype.toString()] of objects should be the same. * Only [enumerable "own" properties][] are considered. -* [`Error`][] names, messages, causes, and errors are always compared, +* {Error} names, messages, causes, and errors are always compared, even if these are not enumerable properties. * [Object wrappers][] are compared both as objects and unwrapped values. * `Object` properties are compared unordered. -* [`Map`][] keys and [`Set`][] items are compared unordered. +* {Map} keys and {Set} items are compared unordered. * Recursion stops when both sides differ or both sides encounter a circular reference. * Implementation does not test the [`[[Prototype]]`][prototype-spec] of objects. -* [`Symbol`][] properties are not compared. -* [`WeakMap`][] and [`WeakSet`][] comparison does not rely on their values +* {Symbol} properties are not compared. +* {WeakMap} and {WeakSet} comparison does not rely on their values but only on their instances. -* [`RegExp`][] lastIndex, flags, and source are always compared, even if these +* {RegExp} lastIndex, flags, and source are always compared, even if these are not enumerable properties. The following example does not throw an [`AssertionError`][] because the @@ -735,7 +735,7 @@ 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. If the `message` -parameter is an instance of an [`Error`][] then it will be thrown instead of the +parameter is an instance of {Error} then it will be thrown instead of the [`AssertionError`][]. ## `assert.deepStrictEqual(actual, expected[, message])` @@ -795,20 +795,20 @@ are recursively evaluated also by the following rules. * [`[[Prototype]]`][prototype-spec] of objects are compared using the [`===` operator][]. * Only [enumerable "own" properties][] are considered. -* [`Error`][] names, messages, causes, and errors are always compared, +* {Error} names, messages, causes, and errors are always compared, even if these are not enumerable properties. `errors` is also compared. -* Enumerable own [`Symbol`][] properties are compared as well. +* Enumerable own {Symbol} properties are compared as well. * [Object wrappers][] are compared both as objects and unwrapped values. * `Object` properties are compared unordered. -* [`Map`][] keys and [`Set`][] items are compared unordered. +* {Map} keys and {Set} items are compared unordered. * Recursion stops when both sides differ or both sides encounter a circular reference. -* [`WeakMap`][] and [`WeakSet`][] instances are **not** compared structurally. +* {WeakMap} and {WeakSet} instances are **not** compared structurally. They are only equal if they reference the same object. Any comparison between different `WeakMap` or `WeakSet` instances will result in inequality, even if they contain the same entries. -* [`RegExp`][] lastIndex, flags, and source are always compared, even if these +* {RegExp} lastIndex, flags, and source are always compared, even if these are not enumerable properties. ```mjs @@ -1034,7 +1034,7 @@ assert.deepStrictEqual(weakSet1, weakSet1); 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. If the `message` -parameter is an instance of an [`Error`][] then it will be thrown instead of the +parameter is an instance of {Error} then it will be thrown instead of the `AssertionError`. ## `assert.doesNotMatch(string, regexp[, message])` @@ -1085,7 +1085,7 @@ If the values do match, or if the `string` argument is of another type than `string`, 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. If the `message` parameter is an -instance of an [`Error`][] then it will be thrown instead of the +instance of {Error} then it will be thrown instead of the [`AssertionError`][]. ## `assert.doesNotReject(asyncFn[, error][, message])` @@ -1113,7 +1113,7 @@ benefit in catching a rejection and then rejecting it again. Instead, consider adding a comment next to the specific code path that should not reject and keep error messages as expressive as possible. -If specified, `error` can be a [`Class`][], [`RegExp`][], or a validation +If specified, `error` can be a [`Class`][], {RegExp} or a validation function. See [`assert.throws()`][] for more details. Besides the async nature to await the completion behaves identically to @@ -1195,10 +1195,10 @@ 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. -If specified, `error` can be a [`Class`][], [`RegExp`][], or a validation +If specified, `error` can be a [`Class`][], {RegExp}, or a validation function. See [`assert.throws()`][] for more details. -The following, for instance, will throw the [`TypeError`][] because there is no +The following, for instance, will throw the {TypeError} because there is no matching error type in the assertion: ```mjs @@ -1346,7 +1346,7 @@ 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. If the `message` -parameter is an instance of an [`Error`][] then it will be thrown instead of the +parameter is an instance of {Error} then it will be thrown instead of the `AssertionError`. ## `assert.fail([message])` @@ -1358,7 +1358,7 @@ added: v0.1.21 * `message` {string|Error} **Default:** `'Failed'` Throws an [`AssertionError`][] with the provided error message or a default -error message. If the `message` parameter is an instance of an [`Error`][] then +error message. If the `message` parameter is an instance of {Error} then it will be thrown instead of the [`AssertionError`][]. ```mjs @@ -1610,7 +1610,7 @@ If the values do not match, or if the `string` argument is of another type than `string`, 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. If the `message` parameter is an -instance of an [`Error`][] then it will be thrown instead of the +instance of {Error} then it will be thrown instead of the [`AssertionError`][]. ## `assert.notDeepEqual(actual, expected[, message])` @@ -1734,7 +1734,7 @@ assert.notDeepEqual(obj1, obj4); 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. If the -`message` parameter is an instance of an [`Error`][] then it will be thrown +`message` parameter is an instance of {Error} then it will be thrown instead of the `AssertionError`. ## `assert.notDeepStrictEqual(actual, expected[, message])` @@ -1794,7 +1794,7 @@ assert.notDeepStrictEqual({ a: 1 }, { a: '1' }); 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. If -the `message` parameter is an instance of an [`Error`][] then it will be thrown +the `message` parameter is an instance of {Error} then it will be thrown instead of the [`AssertionError`][]. ## `assert.notEqual(actual, expected[, message])` @@ -1858,7 +1858,7 @@ 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. If the `message` -parameter is an instance of an [`Error`][] then it will be thrown instead of the +parameter is an instance of {Error} then it will be thrown instead of the `AssertionError`. ## `assert.notStrictEqual(actual, expected[, message])` @@ -1911,7 +1911,7 @@ assert.notStrictEqual(1, '1'); 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. If the -`message` parameter is an instance of an [`Error`][] then it will be thrown +`message` parameter is an instance of {Error} then it will be thrown instead of the `AssertionError`. ## `assert.ok(value[, message])` @@ -1934,7 +1934,7 @@ Tests if `value` is truthy. It is equivalent to 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. If the `message` -parameter is an instance of an [`Error`][] then it will be thrown instead of the +parameter is an instance of {Error} then it will be thrown instead of the `AssertionError`. If no arguments are passed in at all `message` will be set to the string: ``'No value argument passed to `assert.ok()`'``. @@ -2055,7 +2055,7 @@ handler is skipped. Besides the async nature to await the completion behaves identically to [`assert.throws()`][]. -If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function, +If specified, `error` can be a [`Class`][], {RegExp}, a validation function, an object where each property will be tested for, or an instance of error where each property will be tested for including the non-enumerable `message` and `name` properties. @@ -2229,7 +2229,7 @@ assert.strictEqual(1, '1', new TypeError('Inputs are not identical')); 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. If the -`message` parameter is an instance of an [`Error`][] then it will be thrown +`message` parameter is an instance of {Error} then it will be thrown instead of the [`AssertionError`][]. ## `assert.throws(fn[, error][, message])` @@ -2255,7 +2255,7 @@ changes: Expects the function `fn` to throw an error. -If specified, `error` can be a [`Class`][], [`RegExp`][], a validation function, +If specified, `error` can be a [`Class`][], {RegExp}, a validation function, a validation object where each property will be tested for strict deep equality, or an instance of error where each property will be tested for strict deep equality including the non-enumerable `message` and `name` properties. When @@ -2430,7 +2430,7 @@ assert.throws( ); ``` -Validate error message using [`RegExp`][]: +Validate error message using {RegExp}: Using a regular expression runs `.toString` on the error object, and will therefore also include the error name. @@ -2688,15 +2688,7 @@ assert.partialDeepStrictEqual({ a: { b: 2 } }, { a: { b: '2' } }); [`Class`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes [`ERR_INVALID_RETURN_VALUE`]: errors.md#err_invalid_return_value [`Error.captureStackTrace`]: errors.md#errorcapturestacktracetargetobject-constructoropt -[`Error`]: errors.md#class-error -[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map [`Object.is()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is -[`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions -[`Set`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set -[`Symbol`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol -[`TypeError`]: errors.md#class-typeerror -[`WeakMap`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap -[`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet [`assert.deepEqual()`]: #assertdeepequalactual-expected-message [`assert.deepStrictEqual()`]: #assertdeepstrictequalactual-expected-message [`assert.doesNotThrow()`]: #assertdoesnotthrowfn-error-message