Merge pull request #4247 from quacksouls/doc-prompt

DOC: `ns.prompt()`: some cleanup and examples

src/ScriptEditor/NetscriptDefinitions.d.ts

@@ -6608,16 +6608,84 @@ export interface NS {
    * @remarks
    * RAM cost: 0 GB
    *
-   * Prompts the player with a dialog box. If `options.type` is undefined or "boolean",
+   * Prompts the player with a dialog box. Here is an explanation of the various options.
-   * the player is shown "Yes" and "No" prompts, which return true and false respectively.
+   *
-   * Passing a type of "text" will give the player a text field and a value of "select"
+   * - `options.type` is not provided to the function. If `options.type` is left out and
-   * will show a drop-down field. Choosing type "select" will require an array or object
+   *   only a string is passed to the function, then the default behavior is to create a
-   * to be passed via the `options.choices` property.
+   *   boolean dialog box.
-   * The script’s execution is halted until the player selects one of the options.
+   *
+   * - `options.type` has value `undefined` or `"boolean"`. A boolean dialog box is
+   *   created. The player is shown "Yes" and "No" prompts, which return true and false
+   *   respectively. The script's execution is halted until the player presses either the
+   *   "Yes" or "No" button.
+   *
+   * - `options.type` has value `"text"`. The player is given a text field to enter
+   *   free-form text. The script's execution is halted until the player enters some text
+   *   and/or presses the "Confirm" button.
+   *
+   * - `options.type` has value `"select"`. The player is shown a drop-down field.
+   *   Choosing type `"select"` will require an array to be passed via the
+   *   `options.choices` property. The array can be an array of strings, an array of
+   *   numbers (not BigInt numbers), or a mixture of both numbers and strings. Any other
+   *   types of array elements will result in an error or an undefined/unexpected
+   *   behavior. The `options.choices` property will be ignored if `options.type` has a
+   *   value other than `"select"`. The script's execution is halted until the player
+   *   chooses one of the provided options and presses the "Confirm" button.
+   *
+   * @example
+   * ```ts
+   * // NS1
+   * // A Yes/No question. The default is to create a boolean dialog box.
+   * var queryA = "Do you enjoy Bitburner?";
+   * var resultA = prompt(queryA);
+   * tprint(queryA + " " + resultA);
+   *
+   * // Another Yes/No question. Can also create a boolean dialog box by explicitly
+   * // passing the option {"type": "boolean"}.
+   * var queryB = "Is programming fun?";
+   * var resultB = prompt(queryB, { type: "boolean" });
+   * tprint(queryB + " " + resultB);
+   *
+   * // Free-form text box.
+   * var resultC = prompt("Please enter your name.", { type: "text" });
+   * tprint("Hello, " + resultC + ".");
+   *
+   * // A drop-down list.
+   * var resultD = prompt("Please select your favorite fruit.", {
+   *     type: "select",
+   *     choices: ["Apple", "Banana", "Orange", "Pear", "Strawberry"]
+   * });
+   * tprint("Your favorite fruit is " + resultD.toLowerCase() + ".");
+   * ```
+   * @example
+   * ```ts
+   * // NS2
+   * // A Yes/No question. The default is to create a boolean dialog box.
+   * const queryA = "Do you enjoy Bitburner?";
+   * const resultA = await ns.prompt(queryA);
+   * ns.tprint(`${queryA} ${resultA}`);
+   *
+   * // Another Yes/No question. Can also create a boolean dialog box by explicitly
+   * // passing the option {"type": "boolean"}.
+   * const queryB = "Is programming fun?";
+   * const resultB = await ns.prompt(queryB, { type: "boolean" });
+   * ns.tprint(`${queryB} ${resultB}`);
+   *
+   * // Free-form text box.
+   * const resultC = await ns.prompt("Please enter your name.", { type: "text" });
+   * ns.tprint(`Hello, ${resultC}.`);
+   *
+   * // A drop-down list.
+   * const resultD = await ns.prompt("Please select your favorite fruit.", {
+   *     type: "select",
+   *     choices: ["Apple", "Banana", "Orange", "Pear", "Strawberry"]
+   * });
+   * ns.tprint(`Your favorite fruit is ${resultD.toLowerCase()}.`);
+   * ```
    *
    * @param txt - Text to appear in the prompt dialog box.
    * @param options - Options to modify the prompt the player is shown.
-   * @returns True if the player click “Yes”; false if the player clicks “No”; or the value entered by the player.
+   * @returns True if the player clicks “Yes”; false if the player clicks “No”; or the value entered by the player.
    */
   prompt(
     txt: string,