doc: clarify examples section in REPL doc #57762

dario-piotrowicz · 2025-04-05T18:27:14Z

This is pretty minor, but I just figured a little bit of polishing wouldn't hurt 🙂

The current examples presented at the bottom of the REPL doc have three issues which I am trying to address here:

they look like they're part of the section above (on how to run multiple REPL instances in the same process) but they are not

see the table of contents at the top of the REPL page:

before after

(the examples are under the multiple REPL section) (the examples are listed on their own)
they link to old gists with code that uses outdates JS syntax (e.g var) and deprecated utilities (e.g. new Buffer)
(so not something really ideal to present as an official example)
the alert informing readers not to use the second example in production environments can be wrongly interpreted as to refer to both examples

(this might be just me, but when I read the text there it really looked to me like the warning was referring to both examples and that This example was likely a typo and that These examples was supposed to be used)

before after

the warning is ananbiguously in the section specific for the example

doc/api/repl.md

aduh95 · 2025-04-06T07:56:44Z

doc/api/repl.md

+
+* running a "full-featured" (`terminal`) REPL over
+  a `net.Server` and `net.Socket` instance:
+  <https://gist.github.com/TooTallNate/2209310>.


I wonder if it still makes sense to link to an external gist, maybe we should copy the code over (not sure how it's licensed though it seems short enough to not fall under copyrightable code).

I totally agree, an external gist to a personal github user feels off to me 😕

IMO, We should create our own example derived from the sample and still link over to the gist for credit.

I can definitely do that 🙂👍

done 🙂 0c1abbe

Ah yeah, one last question! 🙂

Do you think that the multi REPL section should also be moved under the new examples section? 🙂

The current examples presented at the bottom of the REPL doc have two issues: - they look like they're part of the section above (on how to run multiple REPL instances in the same process) but they are not - the alert informing readers not to use the second example in production environments can be wrongly interpreted as to refer to both examples The changes here address both these issues

Capitalize list items Co-authored-by: Antoine du Hamel <[email protected]>

doc/api/repl.md

aduh95 · 2025-04-06T23:16:00Z

doc/api/repl.md

+  // Hack to thread stdin and stdout
+  // simultaneously in curl's single thread
+  const iv = setInterval(() => {
+    res.write(buf0);
+  }, 100);
+


Is this still needed? I can't see what difference it makes

No I just tried the example without it (I'm on Ubuntu) and it does not seem necessary

I wasn't actually fully sure why this was needed and feared that removing might break the example under some conditions / on some platform? 🤷

However do think that quite likely this is not needed, so I'm totally happy removing it, we can always re-add it if in some cases it is right? 🙂

Removed 🙂 a977fbe

(PS: thanks so much for the suggestion 🫶)

Co-authored-by: Antoine du Hamel <[email protected]>

nodejs-github-bot · 2025-04-08T18:25:42Z

Landed in b396991

The current examples presented at the bottom of the REPL doc have two issues: - they look like they're part of the section above (on how to run multiple REPL instances in the same process) but they are not - the alert informing readers not to use the second example in production environments can be wrongly interpreted as to refer to both examples The changes here address both these issues PR-URL: nodejs#57762 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>

The current examples presented at the bottom of the REPL doc have two issues: - they look like they're part of the section above (on how to run multiple REPL instances in the same process) but they are not - the alert informing readers not to use the second example in production environments can be wrongly interpreted as to refer to both examples The changes here address both these issues PR-URL: #57762 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>

nodejs-github-bot added doc Issues and PRs related to the documentations. repl Issues and PRs related to the REPL subsystem. labels Apr 5, 2025

dario-piotrowicz force-pushed the dario/doc/repl-examples-format branch from bb2fea9 to 1edd98a Compare April 5, 2025 18:33