DOC: Improve ns.kill documentation (#365)

This commit is contained in:
Snarling 2023-02-13 21:50:38 -05:00 committed by GitHub
parent 571f1eb8ef
commit b0bdf0c7ad
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 53 additions and 116 deletions

@ -4,19 +4,19 @@
## NS.kill() method ## NS.kill() method
Terminate another script. Terminate the script with the provided PID.
**Signature:** **Signature:**
```typescript ```typescript
kill(script: number): boolean; kill(pid: number): boolean;
``` ```
## Parameters ## Parameters
| Parameter | Type | Description | | Parameter | Type | Description |
| --- | --- | --- | | --- | --- | --- |
| script | number | Filename or PID of the script to kill. | | pid | number | The PID of the script to kill. |
**Returns:** **Returns:**
@ -28,35 +28,13 @@ True if the script is successfully killed, and false otherwise.
RAM cost: 0.5 GB RAM cost: 0.5 GB
Kills the script on the target server specified by the scripts 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 ```js
// NS1: // kills the script with PID 20:
//The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: ns.kill(20);
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");
``` ```

@ -4,21 +4,21 @@
## NS.kill() method ## NS.kill() method
Terminate another script. Terminate the script with the provided filename, hostname, and script arguments.
**Signature:** **Signature:**
```typescript ```typescript
kill(script: string, host: string, ...args: (string | number | boolean)[]): boolean; kill(filename: string, hostname?: string, ...args: ScriptArg[]): boolean;
``` ```
## Parameters ## Parameters
| Parameter | Type | Description | | Parameter | Type | Description |
| --- | --- | --- | | --- | --- | --- |
| script | string | Filename or PID of the script to kill. | | filename | string | Filename of the script to kill. |
| host | string | Hostname of the server on which to kill the script. | | hostname | string | _(Optional)_ Hostname where the script to kill is running. Defaults to the current server. |
| args | (string \| number \| boolean)\[\] | Arguments to identify which script to kill. | | args | [ScriptArg](./bitburner.scriptarg.md)<!-- -->\[\] | Arguments of the script to kill. |
**Returns:** **Returns:**
@ -30,35 +30,19 @@ True if the script is successfully killed, and false otherwise.
RAM cost: 0.5 GB RAM cost: 0.5 GB
Kills the script on the target server specified by the scripts 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 ```js
// NS1: // kill the script "foo.js" on the same server the current script is running from, with no arguments
//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");
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 the script "foo.js" on the "n00dles" server with no arguments.
kill("foo.script", getHostname()); 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 the script foo.js on the current server that was ran with the arguments [1, “foodnstuff”, false]:
kill("foo.script", getHostname(), 1, "foodnstuff"); ns.kill("foo.js", ns.getHostname(), 1, "foodnstuff", false);
```
## 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");
``` ```

@ -132,8 +132,8 @@ export async function main(ns) {
| [httpworm(host)](./bitburner.ns.httpworm.md) | Runs HTTPWorm.exe on a server. | | [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. | | [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. | | [isRunning(script, host, args)](./bitburner.ns.isrunning.md) | Check if a script is running. |
| [kill(script)](./bitburner.ns.kill.md) | Terminate another script. | | [kill(pid)](./bitburner.ns.kill.md) | Terminate the script with the provided PID. |
| [kill(script, host, args)](./bitburner.ns.kill_1.md) | Terminate another script. | | [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. | | [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. | | [ls(host, grep)](./bitburner.ns.ls.md) | List files on a server. |
| [moveTail(x, y, pid)](./bitburner.ns.movetail.md) | Move a tail window. | | [moveTail(x, y, pid)](./bitburner.ns.movetail.md) | Move a tail window. |

@ -740,7 +740,7 @@ export const ns: InternalAPI<NSFull> = {
}, },
kill: kill:
(ctx) => (ctx) =>
(scriptID, hostname?, ...scriptArgs) => { (scriptID, hostname = ctx.workerScript.hostname, ...scriptArgs) => {
const ident = helpers.scriptIdentifier(ctx, scriptID, hostname, scriptArgs); const ident = helpers.scriptIdentifier(ctx, scriptID, hostname, scriptArgs);
let res; let res;
const killByPid = typeof ident === "number"; const killByPid = typeof ident === "number";
@ -749,7 +749,7 @@ export const ns: InternalAPI<NSFull> = {
res = killWorkerScript(ident); res = killWorkerScript(ident);
} else { } else {
// Kill by filename/hostname // Kill by filename/hostname
if (scriptID === undefined || hostname === undefined) { if (scriptID === undefined) {
throw helpers.makeRuntimeErrorMsg(ctx, "Usage: kill(scriptname, server, [arg1], [arg2]...)"); throw helpers.makeRuntimeErrorMsg(ctx, "Usage: kill(scriptname, server, [arg1], [arg2]...)");
} }

@ -5529,74 +5529,49 @@ export interface NS {
spawn(script: string, numThreads?: number, ...args: (string | number | boolean)[]): void; spawn(script: string, numThreads?: number, ...args: (string | number | boolean)[]): void;
/** /**
* Terminate another script. * Terminate the script with the provided PID.
* @remarks * @remarks
* RAM cost: 0.5 GB * RAM cost: 0.5 GB
* *
* Kills the script on the target server specified by the scripts name and arguments. * Kills the script with the provided PID.
* Remember that scripts are uniquely identified by both their names and arguments. * To instead kill a script using its filename, hostname, and args, see {@link NS.(kill:2) | the other ns.kill entry}.
* 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.
* *
* @example * @example
* ```ts * ```js
* // NS1: * // kills the script with PID 20:
* //The following example will try to kill a script named foo.script on the foodnstuff server that was ran with no arguments: * ns.kill(20);
* 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
* ```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: * @param pid - The PID of the script to kill.
* 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.
* @returns True if the script is successfully killed, and false otherwise. * @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 * @example
* ```ts * ```js
* // NS1: * // kill the script "foo.js" on the same server the current script is running from, with no arguments
* //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");
* 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 the script "foo.js" on the "n00dles" server with no arguments.
* kill("foo.script", getHostname()); * 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 the script foo.js on the current server that was ran with the arguments [1, “foodnstuff”, false]:
* kill("foo.script", getHostname(), 1, "foodnstuff"); * ns.kill("foo.js", ns.getHostname(), 1, "foodnstuff", false);
* ```
* @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 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. * Terminate all scripts on a server.