Improve the documentation for the server package

2 files changed, 128 insertions, 2 deletions

diff --git a/src/ch/epfl/xblast/server/Main.java b/src/ch/epfl/xblast/server/Main.java
index 98bbb3d..aff499b 100644
--- a/src/ch/epfl/xblast/server/Main.java
+++ b/src/ch/epfl/xblast/server/Main.java
@@ -13,6 +13,11 @@ public final class Main {
         // Static class
     }
 
+    /**
+     * Starts a new server.
+     *
+     * @param args arguments given to the server (i.e. number of players required for the game to start)
+     */
     public static void main(String[] args) {
         Integer expectedClients = ArgumentChecker.parseIntOrNull(ArgumentChecker.getOrNull(args, 0));
         String iface = ArgumentChecker.getOrNull(args, 1);
diff --git a/src/ch/epfl/xblast/server/Server.java b/src/ch/epfl/xblast/server/Server.java
index 8a4b09b..015d771 100644
--- a/src/ch/epfl/xblast/server/Server.java
+++ b/src/ch/epfl/xblast/server/Server.java
@@ -21,14 +21,29 @@ import java.util.*;
  */
 public class Server {
 
-    public static final int DEFAULT_PORT = 2016;
+    /**
+     * Default parameters of the server.
+     */
     private static final long REFRESH_RATE = (long) (50 * 1E6); // nanosecond
-
     private static final int DEFAULT_EXPECTED_CLIENTS = PlayerID.values().length;
+    public static final int DEFAULT_PORT = 2016;
+
+    /**
+     * ID of an observer.
+     */
     public static final byte OBSERVER = -1;
 
+    /**
+     * A Channel.
+     */
     private static class Channel {
 
+        /**
+         * Transform a list of bytes to an array of bytes.
+         *
+         * @param l the given list of bytes
+         * @return the array built from the given list
+         */
         private static byte[] toByteArray(List<Byte> l) {
             byte[] arr = new byte[l.size()];
 
@@ -38,6 +53,13 @@ public class Server {
             return arr;
         }
 
+        /**
+         * Create the socket which will be listened.
+         *
+         * @param host hostname
+         * @param port port to be listened
+         * @return the socket build from the given params
+         */
         private static InetSocketAddress listeningInterface(String host, int port) {
             if (Objects.isNull(host))
                 return new InetSocketAddress(port);
@@ -45,6 +67,12 @@ public class Server {
                 return new InetSocketAddress(host, port);
         }
 
+        /**
+         * Open a UDP channel.
+         *
+         * @param iface listened socket
+         * @return a UDP channel
+         */
         private static DatagramChannel openChannel(InetSocketAddress iface) {
             try {
                 DatagramChannel chan = DatagramChannel.open(StandardProtocolFamily.INET);
@@ -57,16 +85,33 @@ public class Server {
             }
         }
 
+        /**
+         * The UDP communication channel.
+         */
         private final DatagramChannel channel;
 
+        /**
+         * Instantiates a new Channel.
+         *
+         * @param iface listened socket
+         */
         Channel(InetSocketAddress iface) {
             this.channel = openChannel(iface);
         }
 
+        /**
+         * Instantiates a new Channel.
+         *
+         * @param host hostname
+         * @param port port to be listened
+         */
         Channel(String host, Integer port) {
             this(listeningInterface(host, Optional.ofNullable(port).orElse(DEFAULT_PORT)));
         }
 
+        /**
+         * Close the channel.
+         */
         void closeChannel() {
             try {
                 this.channel.close();
@@ -75,6 +120,12 @@ public class Server {
             }
         }
 
+        /**
+         * Accept the registration of a new client.
+         *
+         * @param registrations
+         * @return a list of the clients.
+         */
         List<SocketAddress> acceptRegistrations(int registrations) {
             List<SocketAddress> clients = new ArrayList<>(registrations);
 
@@ -87,6 +138,11 @@ public class Server {
             return Collections.unmodifiableList(clients);
         }
 
+        /**
+         * Collect actions from the players.
+         *
+         * @return a list map containing the actions related to each player
+         */
         Map<SocketAddress, PlayerAction> collectActions() {
             Map<SocketAddress, PlayerAction> actions = new HashMap<>();
             Optional<Map.Entry<SocketAddress, PlayerAction>> action;
@@ -100,6 +156,12 @@ public class Server {
             return Collections.unmodifiableMap(actions);
         }
 
+        /**
+         * Send data through the socket.
+         *
+         * @param content data to be send
+         * @param dst recepient of the data
+         */
         void send(List<Byte> content, SocketAddress dst) {
             try {
                 ByteBuffer buf = ByteBuffer.wrap(toByteArray(content));
@@ -109,6 +171,12 @@ public class Server {
             }
         }
 
+        /**
+         * Receive a Byte from the socket.
+         *
+         * @param block
+         * @return an Optional containing the received data
+         */
         private Optional<Map.Entry<SocketAddress, Byte>> receiveByte(boolean block) {
             try {
                 ByteBuffer buf = ByteBuffer.allocate(1);
@@ -124,6 +192,12 @@ public class Server {
             }
         }
 
+        /**
+         * Receive a player action from the socket.
+         *
+         * @param block
+         * @return an Optional containing the received player action
+         */
         private Optional<Map.Entry<SocketAddress, PlayerAction>> receiveAction(boolean block) {
             try {
                 Map.Entry<SocketAddress, Byte> actionByte = this.receiveByte(block).get();
@@ -134,6 +208,11 @@ public class Server {
             }
         }
 
+        /**
+         * Accept an action from the socket.
+         *
+         * @return the accepted action
+         */
         private Map.Entry<SocketAddress, PlayerAction> acceptAction() {
             Optional<Map.Entry<SocketAddress, PlayerAction>> action;
 
@@ -144,6 +223,11 @@ public class Server {
             return action.get();
         }
 
+        /**
+         * Accept the registration of a player
+         *
+         * @return the address of the new player
+         */