doc: document asserts Weak(Map|Set) behavior

Right now it is not documentated that WeakMap entries are not
compared. This might result in some confusion. This adds a note
about the behavior in `assert.deepStrictEqual`. This documentation
is also references in `util.isDeepStrictEqual`, so we do not have
to document it again for that function as the underlying algorithm
is the same.

Backport-PR-URL: #19230
PR-URL: #18248
Fixes: #18228
Refs: #18228
Reviewed-By: Joyee Cheung <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>

doc/api/assert.md

@@ -251,6 +251,8 @@ are recursively evaluated also by the following rules.
 * Map keys and Set items are compared unordered.
 * Recursion stops when both sides differ or both sides encounter a circular
   reference.
+* [`WeakMap`][] and [`WeakSet`][] comparison does not rely on their values. See
+  below for further details.
 
 ```js
 const assert = require('assert').strict;
@@ -292,6 +294,16 @@ assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol1]: 1 });
 // OK, because it is the same symbol on both objects.
 assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });
 // Fails because symbol1 !== symbol2!
+
+const weakMap1 = new WeakMap();
+const weakMap2 = new WeakMap([[{}, {}]]);
+const weakMap3 = new WeakMap();
+weakMap3.unequal = true;
+
+assert.deepStrictEqual(weakMap1, weakMap2);
+// OK, because it is impossible to compare the entries
+assert.deepStrictEqual(weakMap1, weakMap3);
+// Fails because weakMap3 has a property that weakMap1 does not contain!
 ```
 
 If the values are not equal, an `AssertionError` is thrown with a `message`
@@ -893,6 +905,8 @@ For more information, see
 [`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.html#errors_class_typeerror
+[`WeakMap`]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
+[`WeakSet`]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/WeakSet
 [`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message
 [`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message
 [`assert.notDeepStrictEqual()`]: #assert_assert_notdeepstrictequal_actual_expected_message