Repository: nodejs/node
Pull request: doc: document REPL custom eval arguments

When reading the REPL docs I noticed that the custom evaluation functions arguments are undocumented and
I figured this would be a nice addition to the docs :slightly_smiling_face: 

<!--
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: @@ -303,7 +303,19 @@ When a new [`repl.REPLServer`][] is created, a custom evaluation function may be
 provided. This can be used, for instance, to implement fully customized REPL
 applications.
 
-The following illustrates an example of a REPL that squares a given number:
+An evaluation function accepts the following four arguments:
+
+* `code` {string} The code to be executed (e.g. `1 + 1`).
+* `context` {Object} The context in which the code is executed. This can either be the JavaScript `global`
+  context or a context specific to the REPL instance, depending on the `useGlobal` option.
+* `replResourceName` {string} An identifier for the REPL resource associated with the current code
+  evaluation. This can be useful for debugging purposes.
+* `callback` {Function} A function to invoke once the code evaluation is complete. The callback takes two parameters:
+  * An error object to provide if an error occurred during evaluation, or `null`/`undefined` if no error occurred.
+  * The result of the code evaluation (this is not relevant if an error is provided).
+
+The following illustrates an example of a REPL that squares a given number, an error is instead printed
+if the provided input is not actually a number:
 
 ```mjs
 import repl from 'node:repl';
@@ -312,8 +324,12 @@ function byThePowerOfTwo(number) {
   return number * number;
 }
 
-function myEval(cmd, context, filename, callback) {
-  callback(null, byThePowerOfTwo(cmd));
+function myEval(code, context, replResourceName, callback) {
+  if (isNaN(code)) {
+    callback(new Error(`${code.trim()} is not a number`));
+  } else {
+    callback(null, byThePowerOfTwo(code));
+  }
 }
 
 repl.start({ prompt: 'Enter a number: ', eval: myEval });
@@ -326,8 +342,12 @@ function byThePowerOfTwo(number) {
   return number * number;
 }
 
-function myEval(cmd, context, filename, callback) {
-  callback(null, byThePowerOfTwo(cmd));
+function myEval(code, context, replResourceName, callback) {
+  if (isNaN(code)) {
+    callback(new Error(`${code.trim()} is not a number`));
+  } else {
+    callback(null, byThePowerOfTwo(code));
+  }
 }
 
 repl.start({ prompt: 'Enter a number: ', eval: myEval });
@@ -691,7 +711,8 @@ changes:
   * `eval` {Function} The function to be used when evaluating each given line
     of input. **Default:** an async wrapper for the JavaScript `eval()`
     function. An `eval` function can error with `repl.Recoverable` to indicate
-    the input was incomplete and prompt for additional lines.
+    the input was incomplete and prompt for additional lines. See the
+    [custom evaluation functions][] section for more details.
   * `useColors` {boolean} If `true`, specifies that the default `writer`
     function should include ANSI color styling to REPL output. If a custom
     `writer` function is provided then this has no effect. **Default:** checking
@@ -914,4 +935,5 @@ avoiding open network interfaces.
 [`repl.start()`]: #replstartoptions
 [`reverse-i-search`]: #reverse-i-search
 [`util.inspect()`]: util.md#utilinspectobject-options
+[custom evaluation functions]: #custom-evaluation-functions
 [stream]: stream.md