From 6a6d36705445d393ce188df43adabb0090cacd5e Mon Sep 17 00:00:00 2001
From: Andrew Lalis <andrewlalisofficial@gmail.com>
Date: Tue, 6 Jul 2021 15:03:28 +0200
Subject: [PATCH] Added more javadoc.

---
 .../nl/andrewlalis/aos_client/Client.java     | 25 +++++++++++
 .../aos_client/MessageTransceiver.java        | 43 ++++++++++++++++++-
 2 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/client/src/main/java/nl/andrewlalis/aos_client/Client.java b/client/src/main/java/nl/andrewlalis/aos_client/Client.java
index 3642e87..5363d44 100644
--- a/client/src/main/java/nl/andrewlalis/aos_client/Client.java
+++ b/client/src/main/java/nl/andrewlalis/aos_client/Client.java
@@ -27,6 +27,14 @@ public class Client {
 
 	private final GameFrame frame;
 
+	/**
+	 * Initializes and starts the client, connecting immediately to a server
+	 * according to the given host, port, and username.
+	 * @param serverHost The server's host name or ip to connect to.
+	 * @param serverPort The server's port to connect to.
+	 * @param username The player's username to use when connecting.
+	 * @throws IOException If the connection could not be initialized.
+	 */
 	public Client(String serverHost, int serverPort, String username) throws IOException {
 		this.soundManager = new SoundManager();
 		this.chatManager = new ChatManager(this.soundManager);
@@ -59,6 +67,11 @@ public class Client {
 		return world;
 	}
 
+	/**
+	 * Updates the client's version of the world according to an update packet
+	 * that was received from the server.
+	 * @param update The update packet from the server.
+	 */
 	public void updateWorld(WorldUpdate update) {
 		if (this.world == null) return;
 		this.world.getBullets().clear();
@@ -95,6 +108,11 @@ public class Client {
 		return myPlayer;
 	}
 
+	/**
+	 * Updates the client's own player data according to an update from the
+	 * server.
+	 * @param update The updated player information from the server.
+	 */
 	public void updatePlayer(PlayerDetailUpdate update) {
 		if (this.myPlayer == null) return;
 		this.myPlayer.setHealth(update.getHealth());
@@ -102,6 +120,10 @@ public class Client {
 		this.myPlayer.setGun(new Gun(this.myPlayer.getGun().getType(), update.getGunCurrentClipBulletCount(), update.getGunClipCount()));
 	}
 
+	/**
+	 * Sends a player control state message to the server, which indicates that
+	 * the player's controls have been updated, due to a key or mouse event.
+	 */
 	public void sendPlayerState() {
 		try {
 			this.messageTransceiver.sendData(DataTypes.PLAYER_CONTROL_STATE, myPlayer.getId(), myPlayer.getState().toBytes());
@@ -110,6 +132,9 @@ public class Client {
 		}
 	}
 
+	/**
+	 * Shuts down the client.
+	 */
 	public void shutdown() {
 		this.chatManager.unbindTransceiver();
 		System.out.println("Chat manager shutdown.");
diff --git a/client/src/main/java/nl/andrewlalis/aos_client/MessageTransceiver.java b/client/src/main/java/nl/andrewlalis/aos_client/MessageTransceiver.java
index 6a859cf..41ae7f6 100644
--- a/client/src/main/java/nl/andrewlalis/aos_client/MessageTransceiver.java
+++ b/client/src/main/java/nl/andrewlalis/aos_client/MessageTransceiver.java
@@ -13,15 +13,44 @@ import java.util.concurrent.Executors;
 
 /**
  * This thread is responsible for handling TCP message communication with the
- * server.
+ * server. During its {@link MessageTransceiver#run()} method, it will try to
+ * receive objects from the server, and process them.
+ * <p>
+ *     It also manages an internal UDP transceiver for sending and receiving
+ *     high volume, lightweight data packets about things like world updates and
+ *     player input events.
+ * </p>
  */
 public class MessageTransceiver extends Thread {
+	/**
+	 * A reference to the client that this transceiver thread is working for.
+	 */
 	private final Client client;
 
+	/**
+	 * The TCP socket that's used for communication.
+	 */
 	private final Socket socket;
+
+	/**
+	 * An internal datagram transceiver that is used for UDP communication.
+	 */
 	private final DataTransceiver dataTransceiver;
+
+	/**
+	 * Output stream that is used for sending objects to the server.
+	 */
 	private final ObjectOutputStream out;
+
+	/**
+	 * Input stream that is used for receiving objects from the server.
+	 */
 	private final ObjectInputStream in;
+
+	/**
+	 * A single-threaded executor that is used to queue and send messages to the
+	 * server sequentially without blocking the main transceiver thread.
+	 */
 	private final ExecutorService writeService = Executors.newFixedThreadPool(1);
 
 	private volatile boolean running = true;
@@ -80,6 +109,11 @@ public class MessageTransceiver extends Thread {
 		}
 	}
 
+	/**
+	 * Sends a message to the server, by submitting it to the write service's
+	 * queue.
+	 * @param message The message to send.
+	 */
 	public void send(Message message) {
 		if (this.socket.isClosed()) return;
 		this.writeService.submit(() -> {
@@ -92,6 +126,13 @@ public class MessageTransceiver extends Thread {
 		});
 	}
 
+	/**
+	 * Sends a packet via UDP to the server.
+	 * @param type The type of data to send.
+	 * @param playerId The id of the player.
+	 * @param data The data to send.
+	 * @throws IOException If the data could not be sent.
+	 */
 	public void sendData(byte type, int playerId, byte[] data) throws IOException {
 		ByteBuffer buffer = ByteBuffer.allocate(1 + Integer.BYTES + data.length);
 		buffer.put(type);