doc: update REPL documentation to instantiate the REPL

[BridgeAR]

The documentation currently states that it's not intended to directly
instantiate REPL instances. It is unknown for what reason that's
recommended as it does seem a proper way to handle new REPL instances.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[Trott]

Bottom reference needs to be corrected but other than that, looks good to me.

[BridgeAR]

Lite-CI https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/4106/

[addaleax]

@BridgeAR Using repl.start() and new REPLServer() are not equivalent, though, and the documentation seems to imply otherwise? Can you also change the code to work the same in both cases, and then add that to the YAML changelog?

[BridgeAR]

@addaleax I'll add a note about the behavior difference. The behavior of .start is somewhat special though: it just adds the very first repl instance as property on the export. I am not certain what reason there was to add this. The commit that adds this property does not indicate any reasons for it either (the description and main code change is about a different feature).
What do you think about checking the usage with Gzemnid and citgm and to deprecate that property if it's not frequently used? My guess is that this property is not used at all.

[addaleax]

@BridgeAR It adds the repl to replMap. That’s the more important bit here imo.

What do you think about checking the usage with Gzemnid and citgm and to deprecate that property if it's not frequently used? My guess is that this property is not used at all.

I think both tools would be useless in this case, and I see no reason to deprecate. repl.repl is the way to access the current REPL instance from the REPL itself, and I expect programmatic usage to be minimal.

[BridgeAR]

@addaleax I somehow did not really think about accessing the current REPL. That is indeed something we should not remove. I think we should move that into the constructor and either only make this accessible in the standalone repl or each instance instead of exporting the very first repl instance that is created with .start() in each repl instance.
I'll mark this PR as blocked and open a PR to implement the exposure when using it as standalone REPL.

It adds the repl to replMap

I removed replMap in a recent commit. So that's not an issue anymore.

[BridgeAR]

Landed in 84b15eb 🎉