doc: improve assert.snapshot() docs

PR-URL: https://github.com/nodejs/node/pull/44429
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>

2 files changed, 29 insertions, 13 deletions

diff --git a/doc/api/assert.md b/doc/api/assert.md
index 2b8eede2b87..4864023f65d 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -2097,23 +2097,39 @@ added: v18.8.0
 
 > Stability: 1 - Experimental
 
-* `value` {any} the value to snapshot
-* `name` {string} the name of snapshot.
+* `value` {any} the value to snapshot.
+* `name` {string} the name of the snapshot.
 * Returns: {Promise}
 
-reads a snapshot from a file, and compares `value` to the snapshot.
-`value` is serialized with [`util.inspect()`][]
-If the value is not strictly equal to the snapshot,
-`assert.snapshot()` will return a rejected `Promise`
-with an [`AssertionError`][].
+Reads the `name` snapshot from a file and compares `value` to the snapshot.
+`value` is serialized with [`util.inspect()`][]. If the value is not strictly
+equal to the snapshot, `assert.snapshot()` returns a rejected `Promise` with an
+[`AssertionError`][].
+
+The snapshot filename uses the same basename as the application's main
+entrypoint with a `.snapshot` extension. If the snapshot file does not exist,
+it is created. The [`--update-assert-snapshot`][] command line flag can be used
+to force the update of an existing snapshot.
 
-If the snapshot file does not exist, the snapshot is written.
+```mjs
+import assert from 'node:assert/strict';
 
-In case it is needed to force a snapshot update,
-use [`--update-assert-snapshot`][];
+// Assuming that the application's main entrypoint is app.mjs, this reads the
+// 'snapshotName' snapshot from app.snapshot and strictly compares its value
+// to `util.inspect('value')`.
+await assert.snapshot('value', 'snapshotName');
+```
 
-By default, a snapshot is read and written to a file,
-using the same name as the main entrypoint with `.snapshot` as the extension.
+```cjs
+const assert = require('node:assert/strict');
+
+(async () => {
+  // Assuming that the application's main entrypoint is app.js, this reads the
+  // 'snapshotName' snapshot from app.snapshot and strictly compares its value
+  // to `util.inspect('value')`.
+  await assert.snapshot('value', 'snapshotName');
+})();
+```
 
 ## `assert.strictEqual(actual, expected[, message])`
 
diff --git a/doc/api/cli.md b/doc/api/cli.md
index 4f9d98a2344..d252aba1612 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1464,7 +1464,7 @@ loading phase, it will always raise it as an uncaught exception.
 added: v18.8.0
 -->
 
-Force updating snapshot files for [`assert.snapshot()`][]
+Updates snapshot files used by [`assert.snapshot()`][].
 
 ### `--use-bundled-ca`, `--use-openssl-ca`