From 6616f7ba15a16f32fef820ad4260c54c3c2f40c2 Mon Sep 17 00:00:00 2001
From: Snarling <84951833+Snarling@users.noreply.github.com>
Date: Mon, 21 Nov 2022 12:19:16 -0500
Subject: [PATCH] DOCS: Update documentation for ns.args (#220)

---
 .../netscript/netscriptscriptarguments.rst    | 31 ++++++++---------
 src/ScriptEditor/NetscriptDefinitions.d.ts    | 33 ++++++++++++++++---
 2 files changed, 42 insertions(+), 22 deletions(-)

diff --git a/doc/source/netscript/netscriptscriptarguments.rst b/doc/source/netscript/netscriptscriptarguments.rst
index 945941557..c3805b83f 100644
--- a/doc/source/netscript/netscriptscriptarguments.rst
+++ b/doc/source/netscript/netscriptscriptarguments.rst
@@ -4,33 +4,28 @@ Netscript Script Arguments
 ==========================
 
 Arguments passed into a script can be accessed in Netscript using a
-special array called *args*. The arguments can be
-accessed using a normal array using the [] operator
-(args[0], args[1], etc...).
+special array called ``args``. The arguments can be accessed using a
+normal array using the ``[]`` operator (``args[0]``, ``args[1]``, etc...).
+These arguments can be string, number, or boolean.
 
 For example, let's say we want to make a generic script
-'generic-run.script' and we plan to pass two arguments into that script.
+``generic-run.script`` and we plan to pass two arguments into that script.
 The first argument will be the name of another script, and the second
 argument will be a number. This generic script will run the
 script specified in the first argument with the amount of threads
-specified in the second element. The code would look like::
+specified in the second argument. The code would look like::
 
     run(args[0], args[1]);
 
-It is also possible to get the number of arguments that was passed
-into a script using::
+And it could be ran from the terminal like:
 
-    args.length
+``run generic-run.script myscript.script 7``
 
-**WARNING: Do not try to modify the args array. This will break the game.**
+In .js / ns2, the above script would look like::
 
+    export async function main(ns) {
+      ns.run(ns.args[0], ns.args[1]);
+    }
 
-example for accessing arguments in ns2 from terminal execution:
-terminal command:
-run name_of_script.js -t 10 --tail argument1 argument2
-
-ns2 script:
-
-const args_obj = arguments[0]
-const argument1 = (args_obj.server.args[0])
-const argument2 = (args_obj.server.args[1])
+It is also possible to get the number of arguments that were passed
+into a script using ``args.length``.
diff --git a/src/ScriptEditor/NetscriptDefinitions.d.ts b/src/ScriptEditor/NetscriptDefinitions.d.ts
index 611d41fc8..359ffa431 100644
--- a/src/ScriptEditor/NetscriptDefinitions.d.ts
+++ b/src/ScriptEditor/NetscriptDefinitions.d.ts
@@ -4535,11 +4535,36 @@ export interface NS {
    * @remarks
    * RAM cost: 0 GB
    *
-   * Arguments passed into a script can be accessed using a normal
-   * array using the [] operator (args[0], args[1], etc…).
+   * Arguments passed into a script can be accessed as a normal array by using the `[]` operator
+   * (`args[0]`, `args[1]`, etc...).
+   * Arguments can be string, number, or boolean.
+   * Use `args.length` to get the number of arguments that were passed into a script.
    *
-   * It is also possible to get the number of arguments that was passed into a script using: 'args.length'
-   * WARNING: Do not try to modify the args array. This will break the game.
+   * @example
+   * `run example.script 7 text true`
+   *
+   * ```js
+   * // NS1 - example.script
+   * tprint(args.length) // 3
+   * tprint(args[0]); // 7 (number)
+   * tprint(args[1]); // "text" (string)
+   * tprint(args[2]); // true (boolean)
+   * tprint(args[3]); // undefined, because only 3 arguments were provided
+   * ```
+   *
+   * @example
+   * `run example.js 7 text true`
+   *
+   * ```js
+   * // NS2 - example.js
+   * export async function main(ns) {
+   *   ns.tprint(ns.args.length) // 3
+   *   ns.tprint(ns.args[0]); // 7 (number)
+   *   ns.tprint(ns.args[1]); // "text" (string)
+   *   ns.tprint(ns.args[2]); // true (boolean)
+   *   ns.tprint(ns.args[3]); // undefined, because only 3 arguments were provided
+   * }
+   * ```
    */
   readonly args: (string | number | boolean)[];