From 3bb56efb3468690818b19f8dc1fe85ba129de45c Mon Sep 17 00:00:00 2001
From: catloversg <152669316+catloversg@users.noreply.github.com>
Date: Mon, 17 Feb 2025 09:27:10 +0700
Subject: [PATCH] DOCUMENTATION: Clarify ns.scan (#1965)

---
 markdown/bitburner.ns.scan.md              | 23 ++++++++++++++++++
 src/ScriptEditor/NetscriptDefinitions.d.ts | 27 ++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/markdown/bitburner.ns.scan.md b/markdown/bitburner.ns.scan.md
index d281f4b5e..ff2d154bc 100644
--- a/markdown/bitburner.ns.scan.md
+++ b/markdown/bitburner.ns.scan.md
@@ -30,6 +30,29 @@ RAM cost: 0.2 GB
 
 Returns an array containing the hostnames of all servers that are one node way from the specified target server. The hostnames in the returned array are strings.
 
+The server network is a tree graph with the home server at the root. The parent node is always the first item of the returned array.
+
+For example, let's say the network looks like this:
+
+```
+home
+--n00dles
+--joesguns
+----CSEC
+------omega-net
+```
+ns.scan("home"): \["n00dles", "joesguns"\]: "home" is the root, so it does not have a parent node.
+
+ns.scan("n00dles"): \["home"\]: "home" is the parent node of "n00dles".
+
+ns.scan("joesguns"): \["home", "CSEC"\]: "home" is the parent node of "joesguns".
+
+ns.scan("CSEC"): \["joesguns", "omega-net"\]: "joesguns" is the parent node of "CSEC".
+
+ns.scan("omega-net"): \["CSEC"\]: "CSEC" is the parent node of "omega-net".
+
+If you run the "scan-analyze" command at home, it won't show all servers due to its limited maximum depth. You can use this function with BFS (Breadth-first search) or DFS (Depth-first search) to traverse the network and discover all servers.
+
 ## Example
 
 
diff --git a/src/ScriptEditor/NetscriptDefinitions.d.ts b/src/ScriptEditor/NetscriptDefinitions.d.ts
index bb0e70cde..7172e2a66 100644
--- a/src/ScriptEditor/NetscriptDefinitions.d.ts
+++ b/src/ScriptEditor/NetscriptDefinitions.d.ts
@@ -6705,6 +6705,33 @@ export interface NS {
    * node way from the specified target server. The hostnames in the returned
    * array are strings.
    *
+   * The server network is a tree graph with the home server at the root. The parent node is always the first item of
+   * the returned array.
+   *
+   * For example, let's say the network looks like this:
+   *
+   * ```
+   * home
+   * --n00dles
+   * --joesguns
+   * ----CSEC
+   * ------omega-net
+   * ```
+   *
+   * ns.scan("home"): ["n00dles", "joesguns"]: "home" is the root, so it does not have a parent node.
+   *
+   * ns.scan("n00dles"): ["home"]: "home" is the parent node of "n00dles".
+   *
+   * ns.scan("joesguns"): ["home", "CSEC"]: "home" is the parent node of "joesguns".
+   *
+   * ns.scan("CSEC"): ["joesguns", "omega-net"]: "joesguns" is the parent node of "CSEC".
+   *
+   * ns.scan("omega-net"): ["CSEC"]: "CSEC" is the parent node of "omega-net".
+   *
+   * If you run the "scan-analyze" command at home, it won't show all servers due to its limited maximum depth. You can
+   * use this function with BFS (Breadth-first search) or DFS (Depth-first search) to traverse the network and discover
+   * all servers.
+   *
    * @example
    * ```js
    * // All servers that are one hop from the current server.