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

[quacksouls]

This PR is inspired by the confusion raised by the OP of this Steam post:

https://steamcommunity.com/app/1812820/discussions/0/6077070109425748796/

The PR proposes the following changes to the documentation of ns.prompt():

1. Commit a368c6904e2378d6afa21ed06e53f5b6f2047e93. A typographical fix.
2. Commit ~3db6e051db26ba37ceff083652fa4ee99a34bead~ 473e6a26749bce6abee18142fcb4c4bb0af4a6c6. Explain the various values for the parameters of the function. The explanation is broken into bullet points for clear presentation and easy reading. This commit also documents the default behaviour when only a string is passed to the function ns.prompt().
3. Commit ~f7a523d5a9da30070aed1356a84017bd028e8b1a~ 93090691b53a71cf262103200c0d8dacf532451d. Some examples on how to create all the prompt dialog boxes. These examples illustrate the various explicit options, including the default case.

[Snarling]

For boolean prompts, I would recommend not including {type: "boolean"}, or {type: undefined} because that's not the simplest way to create a boolean prompt and should not be the example provided. The expected and simplest way is just by not including options at all.

The multiline formatting on the simple text query or on the array also don't really make sense IMO (prettier is also fine with them not being multiline), and they definitely would have been more confusing for me when I was first starting out in js.

It's also not necessary and doesn't really make sense to store the query text in variables.

An extra line between each of the 3 examples also helps readability.

e.g. here's how I would change the examples for NS2, with similar changes for NS1

// A Yes/No question
const resultA = await ns.prompt("Do you enjoy Bitburner?");
ns.tprint(`You answered ${resultA}.`);

// Free-form text box.
const resultB = await ns.prompt("What is your name?", { "type": "text" });
ns.tprint(`Hello, ${resultB}.`);

// A drop-down list.
const resultC = await ns.prompt("Please select your favorite fruit.", {
  "type": "select",
  "choices": ["Apple", "Banana", "Orange", "Pear", "Strawberry"]
});
ns.tprint(`Your favorite fruit is ${resultC.toLowerCase()}.`);

[quacksouls]

For boolean prompts, I would recommend not including {type: "boolean"}, or {type: undefined} because that's not the simplest way to create a boolean prompt and should not be the example provided. The expected and simplest way is just by not including options at all.

See commit 93090691b53a71cf262103200c0d8dacf532451d. The first example is rewritten to make use of the default behaviour, i.e. create a boolean dialog box. The example following that has been rewritten to show that a boolean dialog box can also be created by explicitly passing the option {"type": "boolean"}. I think it's important to document the default behaviour and how to get the default behaviour by an explicit option. Commit 473e6a26749bce6abee18142fcb4c4bb0af4a6c6 now also documents the default behaviour.

The multiline formatting on the simple text query or on the array also don't really make sense IMO (prettier is also fine with them not being multiline), and they definitely would have been more confusing for me when I was first starting out in js.

Fixed in commit 93090691b53a71cf262103200c0d8dacf532451d.

It's also not necessary and doesn't really make sense to store the query text in variables.

This makes sense for the last 2 examples, but not the first 2 examples. Consider this script:

/** @param {NS} ns */
export async function main(ns) {
    // A Yes/No question.
    const resultA = await ns.prompt("Do you enjoy Bitburner?");
    ns.tprint(`You answered: ${resultA}`);

    // Another Yes/No question.
    const resultB = await ns.prompt("Is programming fun?");
    ns.tprint(`You answered: ${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()}.`);
}

The image below gives a sample output at the Terminal. I have to check the script code to know the questions to which I give a true or false answer. Now save the boolean questions and print the questions together with their corresponding boolean responses. As shown in the image below, at the Terminal I can see the questions to which I give a true or false response.

/** @param {NS} ns */
export async function main(ns) {
    // A Yes/No question.
    const queryA = "Do you enjoy Bitburner?";
    const resultA = await ns.prompt(queryA);
    ns.tprint(`${queryA} ${resultA}`);

    // Another Yes/No question.
    const queryB = "Is programming fun?";
    const resultB = await ns.prompt(queryB);
    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()}.`);
}

An extra line between each of the 3 examples also helps readability.

Fixed in commit 93090691b53a71cf262103200c0d8dacf532451d.