MISC: Improve tutorial, documentation and discoverability of NS API documentation (#1697)

README.md

@@ -13,9 +13,10 @@ See the [frequently asked questions](./doc/FAQ.md) for more information . To dis
 
 # Documentation
 
-The game's official documentation can be found in-game.
+There are 2 types of documentation:
 
-The [in-game documentation](./markdown/bitburner.md) is generated from the [TypeScript definitions](./src/ScriptEditor/NetscriptDefinitions.d.ts).
+- In-game documentation: It can be found in the Documentation tab. This is the best place to get up-to-date information. You can also read the web version at https://github.com/bitburner-official/bitburner-src/blob/stable/src/Documentation/doc/index.md.
+- NS API documentation: It's generated from the [TypeScript definitions](./src/ScriptEditor/NetscriptDefinitions.d.ts). You can read it at https://github.com/bitburner-official/bitburner-src/blob/stable/markdown/bitburner.md.
 
 Anyone is welcome to contribute to the documentation by editing the [source
 files](/src/Documentation/doc) and then making a pull request with your contributions.

src/ScriptEditor/ui/ScriptEditorRoot.tsx

@@ -87,7 +87,7 @@ function Root(props: IProps): React.ReactElement {
       }
       const cleanCode = currentScript.code.replace(/\s/g, "");
       const ns1 = "while(true){hack('n00dles');}";
-      const ns2 = `exportasyncfunctionmain(ns){while(true){awaitns.hack('n00dles');}}`;
+      const ns2 = `/**@param{NS}ns*/exportasyncfunctionmain(ns){while(true){awaitns.hack("n00dles");}}`;
       if (!cleanCode.includes(ns1) && !cleanCode.includes(ns2)) {
         dialogBoxCreate("Please copy and paste the code from the tutorial!");
         return;

src/ScriptEditor/ui/Toolbar.tsx

@@ -3,7 +3,6 @@ import * as monaco from "monaco-editor";
 
 import Box from "@mui/material/Box";
 import Button from "@mui/material/Button";
-import Link from "@mui/material/Link";
 import Table from "@mui/material/Table";
 import TableCell from "@mui/material/TableCell";
 import TableRow from "@mui/material/TableRow";
@@ -22,7 +21,7 @@ import { useBoolean } from "../../ui/React/hooks";
 import { Settings } from "../../Settings/Settings";
 import { OptionsModal, OptionsModalProps } from "./OptionsModal";
 import { useScriptEditorContext } from "./ScriptEditorContext";
-import { getNsApiDocumentationUrl } from "../../utils/StringHelperFunctions";
+import { NsApiDocumentationLink } from "../../ui/React/NsApiDocumentationLink";
 
 type IStandaloneCodeEditor = monaco.editor.IStandaloneCodeEditor;
 
@@ -71,9 +70,7 @@ export function Toolbar({ editor, onSave }: IProps) {
           Terminal (Ctrl/Cmd + b)
         </Button>
         <Typography>
-          <Link target="_blank" href={getNsApiDocumentationUrl()} fontSize="1.2rem">
+          <NsApiDocumentationLink />
-            NS API documentation
-          </Link>
         </Typography>
       </Box>
       <OptionsModal

src/ui/InteractiveTutorial/InteractiveTutorialRoot.tsx

@@ -25,6 +25,7 @@ import {
 } from "../../InteractiveTutorial";
 import { useRerender } from "../React/hooks";
 import { Settings } from "../../Settings/Settings";
+import { NsApiDocumentationLink } from "../React/NsApiDocumentationLink";
 
 interface IContent {
   content: React.ReactElement;
@@ -339,10 +340,11 @@ export function InteractiveTutorialRoot(): React.ReactElement {
           <Typography classes={{ root: classes.code }}>
             {
               <CopyableText
-                value={`export async function main(ns) {
+                value={`/** @param {NS} ns */
-	while(true) {
+export async function main(ns) {
-		await ns.hack('n00dles');
+  while (true) {
-	}
+    await ns.hack("n00dles");
+  }
 }`}
               />
             }
@@ -352,6 +354,9 @@ export function InteractiveTutorialRoot(): React.ReactElement {
             continuously hack the n00dles server.
             <br />
             <br />
+            To access <NsApiDocumentationLink />, press the link at the bottom.
+            <br />
+            <br />
             To save and close the script editor, press the button at the bottom.
           </Typography>
         </>

src/ui/MD/a.tsx

@@ -4,6 +4,7 @@ import { useNavigator } from "../React/Documentation";
 import { CorruptableText } from "../React/CorruptableText";
 import { Player } from "@player";
 import { getNsApiDocumentationUrl } from "../../utils/StringHelperFunctions";
+import { Settings } from "../../Settings/Settings";
 
 export const isSpoiler = (title: string): boolean => title.includes("advanced/") && Player.sourceFileLvl(1) === 0;
 
@@ -22,7 +23,16 @@ export const A = (props: React.PropsWithChildren<{ href?: string }>): React.Reac
       href = getNsApiDocumentationUrl();
     }
     return (
-      <Link rel="noopener noreferrer" href={href} target="_blank">
+      <Link
+        rel="noopener noreferrer"
+        href={href}
+        target="_blank"
+        color={Settings.theme.info}
+        sx={{
+          textDecorationThickness: "3px",
+          textUnderlineOffset: "5px",
+        }}
+      >
         {props.children}
       </Link>
     );

src/ui/React/NsApiDocumentationLink.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+import { Link } from "@mui/material";
+import { getNsApiDocumentationUrl } from "../../utils/StringHelperFunctions";
+import { Settings } from "../../Settings/Settings";
+
+export function NsApiDocumentationLink(): React.ReactElement {
+  return (
+    <Link
+      target="_blank"
+      href={getNsApiDocumentationUrl()}
+      fontSize="1.2rem"
+      color={Settings.theme.info}
+      sx={{
+        textDecorationThickness: "3px",
+        textUnderlineOffset: "5px",
+      }}
+    >
+      NS API documentation
+    </Link>
+  );
+}