Add API documentation and revert module aliases. (#13)

* Add doc generation and GitHub action to create docs page on release * Added documentation for all currently written classes * Removed all relative paths, as it was still causing an issue * Update README with API changes
ThePhar · Jun 16, 2022 · 194d124 · 194d124
1 parent 1601798
commit 194d124
Show file tree

Hide file tree

Showing 62 changed files with 3,339 additions and 6,233 deletions.
diff --git a/.babelrc b/.babelrc
@@ -1,8 +1,7 @@
 {
   "presets": [
     "@babel/preset-env",
-    "@babel/preset-typescript",
-    "minify"
+    "@babel/preset-typescript"
   ],
   "plugins": [
     ["babel-plugin-module-resolver", {

diff --git a/.github/workflows/update-docs.yaml b/.github/workflows/update-docs.yaml
@@ -0,0 +1,28 @@
+name: Update Documentation
+
+on:
+  release:
+    types: [ "created" ]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+      - name: Installing dependancies...
+        run: npm install
+      - name: Building documentation...
+        run: npm run docs
+      - name: Deploy to GitHub Pages
+        if: success()
+        uses: crazy-max/ghaction-github-pages@v3
+        with:
+          target_branch: docs
+          build_dir: docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -302,4 +302,8 @@ $RECYCLE.BIN/
 # Windows shortcuts
 *.lnk
 
+### Documentation ###
+# typedoc output
+docs
+
 # End of https://www.toptal.com/developers/gitignore/api/windows,macos,linux,intellij+all,node
diff --git a/README.md b/README.md
@@ -7,25 +7,46 @@
 
 A general purpose library for communicating with Archipelago servers via Node.js.
 
+**Note: This library is currently in active development and some key APIs may change between 0.x releases. __Use this
+library at your own risk.__**
+
 ## Getting Started
 
-```javascript
-import { ArchipelagoClient, NetworkVersion } from "archipelago.js";
+Install `archipelago.js` into your npm project with the following command:
+
+```bash
+npm install archipelago.js
+```
 
-// Set up our client.
-const version = new NetworkVersion(0, 3, 2);
-const client = new ArchipelagoClient("localhost:38281", version);
+Here is an example client that connects and sends a hello message on connection. It also updates the console when a new
+message comes in.
 
-// Connect to the Archipelago server!
+```javascript
+// CommonJS Modules
+const { ArchipelagoClient, CommandPacketType, ItemsHandlingFlags } = require("archipelago.js");
+
+// Set up the AP client.
+const client = new ArchipelagoClient("localhost:38281");
+const credentials = {
+    game: "Rogue Legacy",
+    name: "Phar",
+    uuid: "8da62081-7213-4543-97f6-b54d40e2fe52",
+    version: { major: 0, minor: 3, build: 2 },
+    items_handling: ItemsHandlingFlags.REMOTE_ALL,
+};
+
+// Connect to the Archipelago server.
 client
-    .connect("Archipelago", "YourName1")
+    .connect(credentials)
     .then(() => {
-        // Send a client packet!
-        client.send({ cmd: "Say", text: "Hello world!" });
+        console.log(`Connected to room with ${client.data.players.size} players.`);
+
+        // Send a raw packet to the server!
+        client.send({ cmd: CommandPacketType.SAY, text: "Hello, everybody!" });
     })
     .catch(console.error);
 
-// Listen for events!
+// Listen for events, like `print` packets.
 client.addListener("print", (packet) => {
     console.log(packet.text);
 });
@@ -34,59 +55,39 @@ client.addListener("print", (packet) => {
 The `ArchipelagoClient` handles all the main interactions with the Archipelago server, including sending and receiving 
 packets and maintaining the websocket connection.
 
-This library is still in development so more features will be coming to make developing with this library easier.
-
 ### LocationsManager
 
 The `locations` property on a `ArchipelagoClient` can be used to look up the name of a location from the data package,
 check or scout locations, or view a list of all locations checked or missing.
 
 ```javascript
-import { ArchipelagoClient, NetworkVersion } from "archipelago.js";
+// See a list of all locations checked or not checked.
+console.log(client.locations.checked);
+console.log(client.locations.missing);
 
-const version = new NetworkVersion(0, 3, 2);
-const client = new ArchipelagoClient("localhost:38281", version);
-
-client
-    .connect("Rogue Legacy", "Phar", "", ["DeathLink"], 0b111)
-    .then(() => {
-        // See a list of all locations checked or not checked.
-        console.log(client.locations.checked);
-        console.log(client.locations.missing);
-
-        // Await location info.
-        client.addListener("locationInfo", (packet) => {
-            console.log(packet.locations);
-        });
+// Await location info.
+client.addListener("locationInfo", (packet) => {
+    console.log(packet.locations);
+});
 
-        // Check locations. Data will return on "locationInfo" event if ItemHandlingFlags are set.
-        client.locations.check(90000, 90001, 90002); // As many ids as you want.
+// Check locations. Data will return on "locationInfo" event if ItemHandlingFlags are set.
+client.locations.check(90000, 90001, 90002); // As many ids as you want.
 
-        // Scout locations without checking them. Data will return on "locationInfo" event.
-        client.locations.scout(false, 90003, 90004); // Do not hint.
-        client.locations.scout(true, 90005) // Hint this location.
+// Scout locations without checking them. Data will return on "locationInfo" event.
+client.locations.scout(false, 90003, 90004); // Do not hint.
+client.locations.scout(true, 90005) // Hint this location.
 
-        // Get the name of a location by its id.
-        console.log(client.locations.name(90010));
-    });
+// Get the name of a location by its id.
+console.log(client.locations.name(90010));
 ```
 
 ### ItemsManager
 
 The `items` property on a `ArchipelagoClient` can be used to look up the name of an item from the data package.
 
 ```javascript
-import { ArchipelagoClient, NetworkVersion } from "archipelago.js";
-
-const version = new NetworkVersion(0, 3, 2);
-const client = new ArchipelagoClient("localhost:38281", version);
-
-client
-    .connect("Rogue Legacy", "Phar", "", ["DeathLink"], 0b111)
-    .then(() => {
-        // Get the name of a item by its id.
-        console.log(client.items.name(90001));
-    });
+// Get the name of a item by its id.
+console.log(client.items.name(90001));
 ```
 
 ### PlayersManager
@@ -95,46 +96,15 @@ The `players` property on a `ArchipelagoClient` can be used to look up the name
 package.
 
 ```javascript
-import { ArchipelagoClient, NetworkVersion } from "archipelago.js";
-
-const version = new NetworkVersion(0, 3, 2);
-const client = new ArchipelagoClient("localhost:38281", version);
-
-client
-    .connect("Rogue Legacy", "Phar", "", ["DeathLink"], 0b111)
-    .then(() => {
-        // Get the name of a player by their id.
-        console.log(client.players.name(1)); // Always their slot name.
-        console.log(client.players.alias(2)); // Their current alias.
-    });
+// Get the name of a player by their id.
+console.log(client.players.name(1)); // Always their slot name.
+console.log(client.players.alias(2)); // Their current alias.
 ```
 
-### DataManager
-
-The `data` property on a `ArchipelagoClient` can be used to look at the raw data in the data package or in the room 
-itself.
-
-```javascript
-import { ArchipelagoClient, NetworkVersion } from "archipelago.js";
-
-const version = new NetworkVersion(0, 3, 2);
-const client = new ArchipelagoClient("localhost:38281", version);
-
-client
-    .connect("Rogue Legacy", "Phar", "", ["DeathLink"], 0b111)
-    .then(() => {
-        // Get the raw datapackage map.
-        console.log(client.data.package);   // Map<string, GameData>
-
-        // Get the look up map for locations/items/players.
-        console.log(client.data.locations); // Map<number, string>
-        console.log(client.data.items);     // Map<number, string>
-        console.log(client.data.players);   // Map<number, NetworkPlayer>
-    });
-```
+## API Documentation & Other Links
 
-## Written in TypeScript
+There is documentation in the GitHub pages section of this repository that includes all the available API. Please take
+a look for more information.
 
-This application was written in TypeScript and thus has access to all the type information of each packet and its parts.
-You can still load this application in vanilla JavaScript if you prefer, though and still have access to type 
-information.
+This library supports 100% of the Archipelago network protocol referenced [here](https://github.com/ArchipelagoMW/Archipelago/blob/main/docs/network%20protocol.md). See more information about 
+[Archipelago](https://archipelago.gg) at their website.