DOCUMENTATION: Clarify ns.scan (#1965)

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
 
 

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.