Repository: nodejs/node
Pull request: doc: clarify the multi REPL example

clarify the example presented where multiple REPL
instances are run in the same process by:
 - clarifying that they share the same `global` object (which currently is a bit ambiguous/half implied)
 - making sure that they do share the same `global` object (via `useGlobal` set to `true`)
 - they delete the unix socket if present (so that people running the code twice don't get confused/annoyed that the second time it doesn't properly work)

Fixes https://github.com/nodejs/node/issues/43118

<!--
Before submitting a pull request, please read:

- the CONTRIBUTING guide at https://github.com/nodejs/node/blob/HEAD/CONTRIBUTING.md
- the commit message formatting guidelines at
  https://github.com/nodejs/node/blob/HEAD/doc/contributing/pull-requests.md#commit-message-guidelines

For code changes:
1. Include tests for any bug fixes or new features.
2. Update documentation if relevant.
3. Ensure that `make -j4 test` (UNIX), or `vcbuild test` (Windows) passes.

If you believe this PR should be highlighted in the Node.js CHANGELOG
please add the `notable-change` label.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
-->


Changed files:
filename: doc/api/repl.md
patch: @@ -822,43 +822,52 @@ For example, the following can be added to a `.bashrc` file:
 alias node="env NODE_NO_READLINE=1 rlwrap node"
 ```
 
-### Starting multiple REPL instances against a single running instance
+### Starting multiple REPL instances in the same process
 
 It is possible to create and run multiple REPL instances against a single
-running instance of Node.js that share a single `global` object but have
-separate I/O interfaces.
+running instance of Node.js that share a single `global` object (by setting
+the `useGlobal` option to `true`) but have separate I/O interfaces.
 
 The following example, for instance, provides separate REPLs on `stdin`, a Unix
-socket, and a TCP socket:
+socket, and a TCP socket, all sharing the same `global` object:
 
 ```mjs
 import net from 'node:net';
 import repl from 'node:repl';
 import process from 'node:process';
+import fs from 'node:fs';
 
 let connections = 0;
 
 repl.start({
   prompt: 'Node.js via stdin> ',
+  useGlobal: true,
   input: process.stdin,
   output: process.stdout,
 });
 
+const unixSocketPath = '/tmp/node-repl-sock';
+
+// If the socket file already exists let's remove it
+fs.rmSync(unixSocketPath, { force: true });
+
 net.createServer((socket) => {
   connections += 1;
   repl.start({
     prompt: 'Node.js via Unix socket> ',
+    useGlobal: true,
     input: socket,
     output: socket,
   }).on('exit', () => {
     socket.end();
   });
-}).listen('/tmp/node-repl-sock');
+}).listen(unixSocketPath);
 
 net.createServer((socket) => {
   connections += 1;
   repl.start({
     prompt: 'Node.js via TCP socket> ',
+    useGlobal: true,
     input: socket,
     output: socket,
   }).on('exit', () => {
@@ -870,29 +879,39 @@ net.createServer((socket) => {
 ```cjs
 const net = require('node:net');
 const repl = require('node:repl');
+const fs = require('node:fs');
+
 let connections = 0;
 
 repl.start({
   prompt: 'Node.js via stdin> ',
+  useGlobal: true,
   input: process.stdin,
   output: process.stdout,
 });
 
+const unixSocketPath = '/tmp/node-repl-sock';
+
+// If the socket file already exists let's remove it
+fs.rmSync(unixSocketPath, { force: true });
+
 net.createServer((socket) => {
   connections += 1;
   repl.start({
     prompt: 'Node.js via Unix socket> ',
+    useGlobal: true,
     input: socket,
     output: socket,
   }).on('exit', () => {
     socket.end();
   });
-}).listen('/tmp/node-repl-sock');
+}).listen(unixSocketPath);
 
 net.createServer((socket) => {
   connections += 1;
   repl.start({
     prompt: 'Node.js via TCP socket> ',
+    useGlobal: true,
     input: socket,
     output: socket,
   }).on('exit', () => {