From b0bdf0c7ad3354a2abb5dce1d1a470e9e67225e7 Mon Sep 17 00:00:00 2001 From: Snarling <84951833+Snarling@users.noreply.github.com> Date: Mon, 13 Feb 2023 21:50:38 -0500 Subject: [PATCH] DOC: Improve ns.kill documentation (#365) --- markdown/bitburner.ns.kill.md | 38 +++-------- markdown/bitburner.ns.kill_1.md | 44 ++++-------- markdown/bitburner.ns.md | 4 +- src/NetscriptFunctions.ts | 4 +- src/ScriptEditor/NetscriptDefinitions.d.ts | 79 ++++++++-------------- 5 files changed, 53 insertions(+), 116 deletions(-) diff --git a/markdown/bitburner.ns.kill.md b/markdown/bitburner.ns.kill.md index 67e3a39e5..1d1329d2f 100644 --- a/markdown/bitburner.ns.kill.md +++ b/markdown/bitburner.ns.kill.md @@ -4,19 +4,19 @@ ## NS.kill() method -Terminate another script. +Terminate the script with the provided PID. **Signature:** ```typescript -kill(script: number): boolean; +kill(pid: number): boolean; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| script | number | Filename or PID of the script to kill. | +| pid | number | The PID of the script to kill. | **Returns:** @@ -28,35 +28,13 @@ True if the script is successfully killed, and false otherwise. RAM cost: 0.5 GB -Kills the script on the target server specified by the script’s name and arguments. Remember that scripts are uniquely identified by both their names and arguments. For example, if `foo.script` is run with the argument 1, then this is not the same as `foo.script` run with the argument 2, even though they have the same name. +Kills the script with the provided PID. To instead kill a script using its filename, hostname, and args, see [the other ns.kill entry](./bitburner.ns.kill_1.md). -## Example 1 +## Example -```ts -// NS1: -//The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: -kill("foo.script", "foodnstuff"); - -//The following will try to kill a script named foo.script on the current server that was ran with no arguments: -kill("foo.script", getHostname()); - -//The following will try to kill a script named foo.script on the current server that was ran with the arguments 1 and “foodnstuff”: -kill("foo.script", getHostname(), 1, "foodnstuff"); -``` - -## Example 2 - - -```ts -// NS2: -//The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: -ns.kill("foo.script", "foodnstuff"); - -//The following will try to kill a script named foo.script on the current server that was ran with no arguments: -ns.kill("foo.script", getHostname()); - -//The following will try to kill a script named foo.script on the current server that was ran with the arguments 1 and “foodnstuff”: -ns.kill("foo.script", getHostname(), 1, "foodnstuff"); +```js +// kills the script with PID 20: +ns.kill(20); ``` diff --git a/markdown/bitburner.ns.kill_1.md b/markdown/bitburner.ns.kill_1.md index c8d25bba5..680cfc722 100644 --- a/markdown/bitburner.ns.kill_1.md +++ b/markdown/bitburner.ns.kill_1.md @@ -4,21 +4,21 @@ ## NS.kill() method -Terminate another script. +Terminate the script with the provided filename, hostname, and script arguments. **Signature:** ```typescript -kill(script: string, host: string, ...args: (string | number | boolean)[]): boolean; +kill(filename: string, hostname?: string, ...args: ScriptArg[]): boolean; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| script | string | Filename or PID of the script to kill. | -| host | string | Hostname of the server on which to kill the script. | -| args | (string \| number \| boolean)\[\] | Arguments to identify which script to kill. | +| filename | string | Filename of the script to kill. | +| hostname | string | _(Optional)_ Hostname where the script to kill is running. Defaults to the current server. | +| args | [ScriptArg](./bitburner.scriptarg.md)\[\] | Arguments of the script to kill. | **Returns:** @@ -30,35 +30,19 @@ True if the script is successfully killed, and false otherwise. RAM cost: 0.5 GB -Kills the script on the target server specified by the script’s name and arguments. Remember that scripts are uniquely identified by both their names and arguments. For example, if `foo.script` is run with the argument 1, then this is not the same as `foo.script` run with the argument 2, even though they have the same name. +Kills the script with the provided filename, running on the specified host with the specified args. To instead kill a script using its PID, see [the other ns.kill entry](./bitburner.ns.kill.md). -## Example 1 +## Example -```ts -// NS1: -//The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: -kill("foo.script", "foodnstuff"); +```js +// kill the script "foo.js" on the same server the current script is running from, with no arguments +ns.kill("foo.script"); -//The following will try to kill a script named foo.script on the current server that was ran with no arguments: -kill("foo.script", getHostname()); +// kill the script "foo.js" on the "n00dles" server with no arguments. +ns.kill("foo.script", "n00dles"); -//The following will try to kill a script named foo.script on the current server that was ran with the arguments 1 and “foodnstuff”: -kill("foo.script", getHostname(), 1, "foodnstuff"); -``` - -## Example 2 - - -```ts -// NS2: -//The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: -ns.kill("foo.script", "foodnstuff"); - -//The following will try to kill a script named foo.script on the current server that was ran with no arguments: -ns.kill("foo.script", getHostname()); - -//The following will try to kill a script named foo.script on the current server that was ran with the arguments 1 and “foodnstuff”: -ns.kill("foo.script", getHostname(), 1, "foodnstuff"); +// kill the script foo.js on the current server that was ran with the arguments [1, “foodnstuff”, false]: +ns.kill("foo.js", ns.getHostname(), 1, "foodnstuff", false); ``` diff --git a/markdown/bitburner.ns.md b/markdown/bitburner.ns.md index 035d2b135..de4a21017 100644 --- a/markdown/bitburner.ns.md +++ b/markdown/bitburner.ns.md @@ -132,8 +132,8 @@ export async function main(ns) { | [httpworm(host)](./bitburner.ns.httpworm.md) | Runs HTTPWorm.exe on a server. | | [isLogEnabled(fn)](./bitburner.ns.islogenabled.md) | Checks the status of the logging for the given function. | | [isRunning(script, host, args)](./bitburner.ns.isrunning.md) | Check if a script is running. | -| [kill(script)](./bitburner.ns.kill.md) | Terminate another script. | -| [kill(script, host, args)](./bitburner.ns.kill_1.md) | Terminate another script. | +| [kill(pid)](./bitburner.ns.kill.md) | Terminate the script with the provided PID. | +| [kill(filename, hostname, args)](./bitburner.ns.kill_1.md) | Terminate the script with the provided filename, hostname, and script arguments. | | [killall(host, safetyguard)](./bitburner.ns.killall.md) | Terminate all scripts on a server. | | [ls(host, grep)](./bitburner.ns.ls.md) | List files on a server. | | [moveTail(x, y, pid)](./bitburner.ns.movetail.md) | Move a tail window. | diff --git a/src/NetscriptFunctions.ts b/src/NetscriptFunctions.ts index 3aa6f90a6..cd4d4fdf9 100644 --- a/src/NetscriptFunctions.ts +++ b/src/NetscriptFunctions.ts @@ -740,7 +740,7 @@ export const ns: InternalAPI = { }, kill: (ctx) => - (scriptID, hostname?, ...scriptArgs) => { + (scriptID, hostname = ctx.workerScript.hostname, ...scriptArgs) => { const ident = helpers.scriptIdentifier(ctx, scriptID, hostname, scriptArgs); let res; const killByPid = typeof ident === "number"; @@ -749,7 +749,7 @@ export const ns: InternalAPI = { res = killWorkerScript(ident); } else { // Kill by filename/hostname - if (scriptID === undefined || hostname === undefined) { + if (scriptID === undefined) { throw helpers.makeRuntimeErrorMsg(ctx, "Usage: kill(scriptname, server, [arg1], [arg2]...)"); } diff --git a/src/ScriptEditor/NetscriptDefinitions.d.ts b/src/ScriptEditor/NetscriptDefinitions.d.ts index 9daad20ce..529a4a2b4 100644 --- a/src/ScriptEditor/NetscriptDefinitions.d.ts +++ b/src/ScriptEditor/NetscriptDefinitions.d.ts @@ -5529,74 +5529,49 @@ export interface NS { spawn(script: string, numThreads?: number, ...args: (string | number | boolean)[]): void; /** - * Terminate another script. + * Terminate the script with the provided PID. * @remarks * RAM cost: 0.5 GB * - * Kills the script on the target server specified by the script’s name and arguments. - * Remember that scripts are uniquely identified by both their names and arguments. - * For example, if `foo.script` is run with the argument 1, then this is not the same as - * `foo.script` run with the argument 2, even though they have the same name. + * Kills the script with the provided PID. + * To instead kill a script using its filename, hostname, and args, see {@link NS.(kill:2) | the other ns.kill entry}. * * @example - * ```ts - * // NS1: - * //The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: - * kill("foo.script", "foodnstuff"); - * - * //The following will try to kill a script named foo.script on the current server that was ran with no arguments: - * kill("foo.script", getHostname()); - * - * //The following will try to kill a script named foo.script on the current server that was ran with the arguments 1 and “foodnstuff”: - * kill("foo.script", getHostname(), 1, "foodnstuff"); + * ```js + * // kills the script with PID 20: + * ns.kill(20); * ``` - * @example - * ```ts - * // NS2: - * //The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: - * ns.kill("foo.script", "foodnstuff"); * - * //The following will try to kill a script named foo.script on the current server that was ran with no arguments: - * ns.kill("foo.script", getHostname()); - * - * //The following will try to kill a script named foo.script on the current server that was ran with the arguments 1 and “foodnstuff”: - * ns.kill("foo.script", getHostname(), 1, "foodnstuff"); - * ``` - * @param script - Filename or PID of the script to kill. - * @param host - Hostname of the server on which to kill the script. - * @param args - Arguments to identify which script to kill. + * @param pid - The PID of the script to kill. * @returns True if the script is successfully killed, and false otherwise. */ - kill(script: number): boolean; + kill(pid: number): boolean; /** - * {@inheritDoc NS.(kill:1)} + * Terminate the script with the provided filename, hostname, and script arguments. + * @remarks + * RAM cost: 0.5 GB + * + * Kills the script with the provided filename, running on the specified host with the specified args. + * To instead kill a script using its PID, see {@link NS.(kill:1) | the other ns.kill entry}. + * * @example - * ```ts - * // NS1: - * //The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: - * kill("foo.script", "foodnstuff"); + * ```js + * // kill the script "foo.js" on the same server the current script is running from, with no arguments + * ns.kill("foo.script"); * - * //The following will try to kill a script named foo.script on the current server that was ran with no arguments: - * kill("foo.script", getHostname()); + * // kill the script "foo.js" on the "n00dles" server with no arguments. + * ns.kill("foo.script", "n00dles"); * - * //The following will try to kill a script named foo.script on the current server that was ran with the arguments 1 and “foodnstuff”: - * kill("foo.script", getHostname(), 1, "foodnstuff"); - * ``` - * @example - * ```ts - * // NS2: - * //The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: - * ns.kill("foo.script", "foodnstuff"); - * - * //The following will try to kill a script named foo.script on the current server that was ran with no arguments: - * ns.kill("foo.script", getHostname()); - * - * //The following will try to kill a script named foo.script on the current server that was ran with the arguments 1 and “foodnstuff”: - * ns.kill("foo.script", getHostname(), 1, "foodnstuff"); + * // kill the script foo.js on the current server that was ran with the arguments [1, “foodnstuff”, false]: + * ns.kill("foo.js", ns.getHostname(), 1, "foodnstuff", false); * ``` + * @param filename - Filename of the script to kill. + * @param hostname - Hostname where the script to kill is running. Defaults to the current server. + * @param args - Arguments of the script to kill. + * @returns True if the script is successfully killed, and false otherwise. */ - kill(script: string, host: string, ...args: (string | number | boolean)[]): boolean; + kill(filename: string, hostname?: string, ...args: ScriptArg[]): boolean; /** * Terminate all scripts on a server.