Documentation.

Lots and Lots of Documentation.
and it's still not enough...

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>dev.koifysh</groupId>
     <artifactId>archipelago-client</artifactId>
-    <version>0.1.0</version>
+    <version>0.1.13</version>
 
     <name>Archipelago Java Library</name>
     <description>Library to connect to an Archipelago Server</description>
@@ -21,7 +21,7 @@
     </licenses>
 
     <scm>
-        <connection>scm:git:git://github.com/KonoTyran/archipelago-client.git</connection>
+        <connection>scm:git:git://github.com/KonoTyran/archipelago-client</connection>
         <developerConnection>scm:git:https://github.com/KonoTyran/archipelago-client.git</developerConnection>
         <url>https://github.com/KonoTyran/archipelago-client</url>
     </scm>

src/main/java/dev/koifysh/archipelago/Client.java

@@ -242,6 +242,11 @@ public RoomInfoPacket getRoomInfo() {
 
     public HashMap<Integer, NetworkSlot> getSlotInfo() {return slotInfo;}
 
+    /**
+     * Works exactly like {@link #connect(URI, boolean)} with allowDowngrade set to true;
+     * @param address
+     * @throws URISyntaxException on malformed address
+     */
     public void connect(String address) throws URISyntaxException {
         URIBuilder builder = new URIBuilder((!address.contains("//")) ? "//" + address : address);
         if (builder.getPort() == -1) { //set default port if not included
@@ -262,6 +267,10 @@ public void connect(String address) throws URISyntaxException {
         connect(builder.build());
     }
 
+    /**
+     * Works exactly like {@link #connect(URI, boolean)} but allowDowngrade is False
+     * @param address Address to connect to
+     */
     public void connect(URI address) {
         connect(address, false);
     }
@@ -290,6 +299,10 @@ public void connect(URI address, boolean allowDowngrade) {
         webSocket.connect(allowDowngrade);
     }
 
+    /**
+     * Sends a Chat message to all other connected Clients.
+     * @param message Message to send.
+     */
     public void sendChat(String message) {
         if (webSocket == null)
             return;
@@ -298,23 +311,46 @@ public void sendChat(String message) {
         }
     }
 
+    /**
+     * inform the Archipelago server that a location ID has been checked.
+     * @param locationID id of a location.
+     * @return true if packet was successfully sent. False if not connected or otherwise failed to send.
+     */
     public boolean checkLocation(long locationID) {
         return locationManager.checkLocation(locationID);
     }
 
+    /**
+     * inform the Archipelago server that a collection of location ID has been checked.
+     * @param locationIDs a collection of a locations.
+     * @return true if packet was successfully sent. False if not connected or otherwise failed to send.
+     */
     public boolean checkLocations(Collection<Long> locationIDs) {
         return locationManager.checkLocations(locationIDs);
     }
 
+    /**
+     * Ask the server for information about what is in locations. you will get a response in the {@link dev.koifysh.archipelago.events.LocationInfoEvent} event.
+     * @param locationIDs List of location ID's to request info on.
+     */
     public void scoutLocations(ArrayList<Long> locationIDs) {
         HashMap<Long, String> locations = dataPackage.getLocationsForGame(game);
         locationIDs.removeIf( location -> !locations.containsKey(location));
         webSocket.scoutLocation(locationIDs);
     }
 
-    public abstract void onPrint(String print);
-
-    public abstract void onPrintJson(APPrint apPrint, String type, int sending, NetworkItem receiving);
+    /**
+     * Called when the server wishes to display a message to the user.
+     * <br>
+     * Deprecated use {@link dev.koifysh.archipelago.events.PrintJSONEvent} instead
+     * @see dev.koifysh.archipelago.events.PrintJSONEvent
+     * @param apPrint list of message segments.
+     * @param type the type of the received message.
+     * @param player int id of the sending player.
+     * @param item the network item that is involved with the message.
+     */
+    @Deprecated
+    public abstract void onPrintJson(APPrint apPrint, String type, int player, NetworkItem item);
 
     public abstract void onError(Exception ex);
 
@@ -354,14 +390,26 @@ public void reconnect() {
         webSocket.reconnect();
     }
 
+    /**
+     * Gets the UUID of this client.
+     * @return UUID of the client, this should theoretically never change.
+     */
     public String getUUID() {
         return UUID;
     }
 
+    /**
+     * gets the alias of this slot.
+     * @return Alias of the slot connected to.
+     */
     public String getAlias() {
         return alias;
     }
 
+    /**
+     * sets an Alias for this slot on the Archipelago server.
+     * @param alias Name to set the alias to.
+     */
     void setAlias(String alias) {
         this.alias = alias;
     }
@@ -374,13 +422,22 @@ public ItemManager getItemManager() {
         return itemManager;
     }
 
+    /**
+     * Update the current game status.
+     * @see ClientStatus
+     *
+     * @param status a {@link ClientStatus} to send to the server.
+     */
     public void setGameState(ClientStatus status) {
         if (webSocket == null)
             return;
         if (webSocket.isAuthenticated())
             webSocket.sendPacket(new StatusUpdatePacket(status));
     }
 
+    /**
+     * manually trigger a resync to the Archipelago server. this should be done automatically if the library detects a desync.
+     */
     public void sync() {
         webSocket.sendPacket(new SyncPacket());
     }
@@ -392,30 +449,45 @@ public void sendBounce(BouncePacket bouncePacket) {
             webSocket.sendPacket(bouncePacket);
     }
 
+    /**
+     * disconnects from a connected Archipelago server.
+     */
     public void disconnect() {
         webSocket.close();
     }
 
+    /**
+     * @return set of tags currently in use.
+     */
     public Set<String> getTags() {
         return tags;
     }
 
+    /**
+     * fetch the itemflags that have been set, bitwise Or against {@link ItemFlags} to read.
+     * @return items handling int.
+     */
     public int getItemsHandlingFlags() {
         return itemsHandlingFlags;
     }
 
+    /**
+     * fetch the itemflags that have been set, bitwise Or against {@link ItemFlags} to read.
+     */
     public void setItemsHandlingFlags(int itemsHandlingFlags) {
         this.itemsHandlingFlags = itemsHandlingFlags;
     }
 
+    /**
+     * @return the event manager.
+     */
     public EventManager getEventManager() {
         return eventManager;
     }
 
     /**
      * Uses DataStorage to save a value on the AP server.
      *
-     * @param setPacket
      */
     public int dataStorageSet(SetPacket setPacket) {
         if (webSocket == null || !webSocket.isAuthenticated())

src/main/java/dev/koifysh/archipelago/ClientStatus.java

@@ -2,6 +2,13 @@
 
 import com.google.gson.annotations.SerializedName;
 
+/**
+ * A Status to send to the server. <br>
+ * {@link #CLIENT_UNKNOWN} - default, no status. <br>
+ * {@link #CLIENT_READY} - Ready to start. <br>
+ * {@link #CLIENT_PLAYING} - Player has started playing. <br>
+ * {@link #CLIENT_GOAL} - Player has finished their game. This will trigger an auto-release depending on server settings.
+ */
 public enum ClientStatus {
 
     @SerializedName("0")

src/main/java/dev/koifysh/archipelago/EventManager.java

@@ -8,10 +8,20 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Manages registering and calling events
+ * @see #registerListener(Object)
+ */
 public class EventManager {
 
     private final Map<Method, Object> registeredListeners = new HashMap<>();
 
+    /**
+     * Use to register for Events that come from the Archipelago server.
+     * supplied Object must have at least 1 method annotated with {@link ArchipelagoEventListener}
+     * and have 1 parameter that extends {@link Event}
+     * @param listener the object containing a listener method.
+     */
     public void registerListener(Object listener) {
         for (Method method : listener.getClass().getMethods()) {
             if (!method.isAnnotationPresent(ArchipelagoEventListener.class))

src/main/java/dev/koifysh/archipelago/ItemFlags.java

@@ -1,14 +1,26 @@
 package dev.koifysh.archipelago;
 
+/**
+ * Item Flag variables to read {@link Client#getItemsHandlingFlags()} and set {@link Client#setItemsHandlingFlags(int)}
+ * <br>
+ * Current item flags: {@link #SEND_ITEMS} {@link #SEND_OWN_ITEMS} {@link #SEND_STARTING_INVENTORY}
+ */
 public class ItemFlags {
 
-    //Indicates you get items sent from other worlds.
+    /**
+     * Tells the server to send you items from other worlds.
+     */
     public static final int SEND_ITEMS = 0b001;
 
-    //send your own items to you (remote items game)
+    /**
+     * Tells the server to send your own items to you (remote items game)
+     */
     public static final int SEND_OWN_ITEMS = 0b010;
 
-    //send starting inventory upon connect
+    /**
+     * Tells the server to send you any items that You should start with.
+     * don't set this if you handle starting items by some kind of data file.
+     */
     public static final int SEND_STARTING_INVENTORY = 0b100;
 
 }

src/main/java/dev/koifysh/archipelago/WebSocket.java

@@ -132,9 +132,6 @@ public void onMessage(String message) {
                         ConnectionRefusedPacket error = gson.fromJson(cmdList.get(i), ConnectionRefusedPacket.class);
                         client.getEventManager().callEvent(new ConnectionResultEvent(error.errors[0]));
                         break;
-                    case Print:
-                        client.onPrint(gson.fromJson(packet, PrintPacket.class).getText());
-                        break;
                     case DataPackage:
                         JsonElement data = packet.getAsJsonObject().get("data");
                         DataPackage dataPackage = gson.fromJson(data, DataPackage.class);
@@ -160,7 +157,12 @@ public void onMessage(String message) {
                                 print.parts[p].text = client.getDataPackage().getLocation(locationID, client.getSlotInfo().get(print.parts[i].player).game);
                             }
                         }
+
+                        client.getEventManager().callEvent(new PrintJSONEvent(print, print.type, print.receiving, print.item));
+
+                        //todo: remove next version
                         client.onPrintJson(print, print.type, print.receiving, print.item);
+
                         break;
                     case RoomUpdate:
                         RoomUpdatePacket updatePacket = gson.fromJson(packet, RoomUpdatePacket.class);
@@ -173,7 +175,7 @@ public void onMessage(String message) {
                         break;
                     case Bounced:
                         BouncedPacket bounced = gson.fromJson(packet, BouncedPacket.class);
-                        if (DeathLink.isDeathLink(bounced))
+                        if (bounced.tags.contains("DeathLink"))
                             DeathLink.receiveDeathLink(bounced);
                         else
                             client.getEventManager().callEvent(new BouncedEvent(bounced.games, bounced.tags, bounced.slots, bounced.data));

src/main/java/dev/koifysh/archipelago/events/ArchipelagoEventListener.java

@@ -3,6 +3,9 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * tag a method with this who's only parameter is a class that extends {@link Event}
+ */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ArchipelagoEventListener {
 }

src/main/java/dev/koifysh/archipelago/events/DeathLinkEvent.java

@@ -1,5 +1,8 @@
 package dev.koifysh.archipelago.events;
 
+/**
+ * event that is fired whenever you receive a death link from another player. must first enable death links via {@link dev.koifysh.archipelago.helper.DeathLink}
+ */
 public class DeathLinkEvent implements Event {
 
     public double time;

src/main/java/dev/koifysh/archipelago/events/PrintJSONEvent.java

@@ -0,0 +1,28 @@
+package dev.koifysh.archipelago.events;
+
+import dev.koifysh.archipelago.Print.APPrint;
+import dev.koifysh.archipelago.parts.NetworkItem;
+
+/**
+ * event that is fired when the server wishes to send a message to the user.
+ */
+public class PrintJSONEvent implements Event {
+
+    public APPrint apPrint;
+    public String type;
+    public int player;
+    public NetworkItem item;
+
+    /**
+     * @param apPrint list of message segments.
+     * @param type the type of the received message.
+     * @param player int id of the sending player.
+     * @param item the network item that is involved with the message.
+     */
+    public PrintJSONEvent(APPrint apPrint, String type, int player, NetworkItem item) {
+        this.apPrint = apPrint;
+        this.type = type;
+        this.player = player;
+        this.item = item;
+    }
+}

src/main/java/dev/koifysh/archipelago/helper/DeathLink.java

@@ -8,15 +8,15 @@
 
 import static dev.koifysh.archipelago.Client.client;
 
-
+/**
+ * a helper-class for sending and receiving death links.
+ * <br>
+ * enable death links by calling {@link #setDeathLinkEnabled(boolean)}
+ */
 public class DeathLink {
 
     static private double lastDeath = 0;
 
-    public static boolean isDeathLink(BouncedPacket bounced) {
-        return bounced.tags.contains("DeathLink");
-    }
-
     public static void receiveDeathLink(BouncedPacket bounced) {
         try {
             if ((Double) bounced.data.getOrDefault("time", 0d) == lastDeath)
@@ -29,6 +29,11 @@ public static void receiveDeathLink(BouncedPacket bounced) {
         }
     }
 
+    /**
+     * helper for sending a death link bounce packet. you can send these without enabling death link first, but it is frowned upon.
+     * @param source A String that is the name of the player sending the death link (does not have to be slot name)
+     * @param cause A String that is the cause of this death. may be empty.
+     */
     public static void SendDeathLink(String source, String cause) {
         lastDeath = (double)System.currentTimeMillis() / 1000D;
 
@@ -42,6 +47,10 @@ public static void SendDeathLink(String source, String cause) {
         client.sendBounce(deathLinkPacket);
     }
 
+    /**
+     * Enable or Disable receiving death links.
+     * @param enabled set to TRUE to enable death links, FALSE to disable.
+     */
     public static void setDeathLinkEnabled(boolean enabled) {
         if(enabled)
             client.addTag("DeathLink");