Merge pull request #74 from rubenpirreram/javadoc-fixes

Javadoc fixes

src/main/java/it/polimi/ingsw/gc14/ClientLauncherTUI.java

@@ -4,16 +4,32 @@ import it.polimi.ingsw.gc14.Network.NetworkEvent;
 import it.polimi.ingsw.gc14.Network.RMI.Client.RMIClient;
 import it.polimi.ingsw.gc14.Network.TCP.Client.TCPClient;
 import it.polimi.ingsw.gc14.View.TUI.TUI;
-
 import java.util.Scanner;
 
+/**
+ * Entry point for the TUI-based game client.
+ * Handles the initial setup by asking the user for a username, the desired number of players,
+ * and the preferred network protocol (RMI or TCP).
+ * Once connected to the server, it continuously reads and dispatches user input to the controller.
+ */
 public class ClientLauncherTUI {
-    //TODO Javadoc
-    TUI view;
-    public void main() throws InterruptedException {
-        view=new TUI(null);
-        ClientController controller = new ClientController(view);
 
+    /**
+     * The TUI view associated with this client.
+     */
+    TUI view;
+
+    /**
+     * Starts the TUI client.
+     * Prompts the user for a username, the desired number of players, and the network protocol.
+     * Attempts to connect to the server using either RMI or TCP depending on the selection.
+     * If the connection is successful, enters a loop to continuously read and process user input.
+     *
+     * @throws InterruptedException if the thread is interrupted while waiting.
+     */
+    public void main() throws InterruptedException {
+        view = new TUI(null);
+        ClientController controller = new ClientController(view);
         Scanner scanner = new Scanner(System.in);
         System.out.println("Selezionare nome utente: ");
         String username = scanner.next();
@@ -22,9 +38,6 @@ public class ClientLauncherTUI {
         int proposedNumPlayers = scanner.nextInt();
         System.out.println("Selezionare RMI[0] o TCP[1]: ");
         int networkType = scanner.nextInt();
-
-
-
         // RMI
         if (networkType == 0) {
             // Connect
@@ -36,16 +49,9 @@ public class ClientLauncherTUI {
                 return;
             }
             controller.setClient(client);
-
+            while (true) {
-            // Play
-            //while(controller.localController.getModel()==null){
-            //    scanner.nextInt();
-            //}
-            while(true) {
                 getInput(scanner, controller, username);
             }
-
-
             // TCP
         } else if (networkType == 1) {
             // Connect
@@ -57,33 +63,53 @@ public class ClientLauncherTUI {
                 return;
             }
             controller.setClient(client);
-
             // Play
-            while(true) {
+            while (true) {
                 getInput(scanner, controller, username);
             }
         }
-
         scanner.close();
     }
 
-
+    /**
-
+     * Reads a single action from the user and dispatches it to the controller.
+     * The action is identified by a string code. Most actions also require a position index
+     * (e.g. the index of the card to draw from a list), which is read as a second input.
+     * Actions that do not require a position (7, 8, 9, A, B, C) skip the position prompt.
+     * <p>
+     * Available actions:
+     * <ul>
+     *   <li>{@code 0} - Choose a slot by index.</li>
+     *   <li>{@code 1} - Draw an upper building card by index.</li>
+     *   <li>{@code 2} - Draw an upper tribe card by index.</li>
+     *   <li>{@code 3} - Draw a lower building card by index.</li>
+     *   <li>{@code 4} - Draw a lower tribe card by index.</li>
+     *   <li>{@code 5} - Pick an optional tribe card by index.</li>
+     *   <li>{@code 6} - Pick an optional building card by index.</li>
+     *   <li>{@code 7} - Skip the optional card choice.</li>
+     *   <li>{@code 8} - Skip the upper draw.</li>
+     *   <li>{@code 9} - Skip the lower draw.</li>
+     *   <li>{@code A} - Render the full game view.</li>
+     *   <li>{@code B} - Render the board view.</li>
+     *   <li>{@code C} - Render the player view.</li>
+     * </ul>
+     *
+     * @param scanner    the scanner used to read user input.
+     * @param controller the client controller to which actions are dispatched.
+     * @param username   the username of the current player.
+     */
     private void getInput(Scanner scanner, ClientController controller, String username) {
         String action = scanner.next();
-        int pos=-1;
+        int pos = -1;
-        if(!action.equals("7")&&!action.equals("8")&&!action.equals("9")&&!action.equals("A")&&!action.equals("B")&&!action.equals("C")) {
+        if (!action.equals("7") && !action.equals("8") && !action.equals("9") && !action.equals("A") && !action.equals("B") && !action.equals("C")) {
-            try
+            try {
-            {
                 System.out.println("Insert the required position:");
                 pos = scanner.nextInt();
-            }
+            } catch (Exception e) {
-            catch(Exception e)
-            {
                 System.out.println("ERROR: Invalid input(expected number)");
             }
         }
-        switch(action) {
+        switch (action) {
             case "0" -> controller.slotChoice(username, pos);
             case "1" -> controller.drawUpperTribeCard(username, pos);
             case "2" -> controller.drawUpperBuildingCard(username, pos);
@@ -97,8 +123,7 @@ public class ClientLauncherTUI {
             case "A" -> view.fullRender();
             case "B" -> view.renderBoard();
             case "C" -> view.renderPlayer();
+            default -> {}
         }
-
-        return;
     }
 }

src/main/java/it/polimi/ingsw/gc14/LimitedList.java

@@ -1,22 +1,42 @@
 package it.polimi.ingsw.gc14;
-
 import java.util.ArrayList;
 
-//TODO Javadoc
+/**
+ * An {@link ArrayList} with a configurable size limit and an associated action.
+ * When the number of elements reaches or exceeds the limit, the specified action is automatically triggered.
+ *
+ * @param <T> the type of elements held in this list.
+ */
 public class LimitedList<T> extends ArrayList<T> {
-    //TODO Javadoc
+
+    /**
+     * The maximum number of elements allowed in the list before the action is triggered.
+     */
     private int limit;
 
-    //TODO Javadoc
+    /**
+     * The action to execute when the list size reaches or exceeds the limit.
+     */
     private Runnable action;
 
-    //TODO Javadoc
+    /**
+     * Creates a new {@code LimitedList} with the specified limit and action.
+     *
+     * @param limit  the maximum number of elements before the action is triggered.
+     * @param action the action to execute when the limit is reached.
+     */
     public LimitedList(int limit, Runnable action) {
         this.limit = limit;
         this.action = action;
     }
 
-    //TODO Javadoc
+    /**
+     * Adds the specified element to the list.
+     * If the list size reaches or exceeds the limit after the insertion, the configured action is triggered.
+     *
+     * @param element the element to add.
+     * @return {@code true} if the element was successfully added.
+     */
     @Override
     public boolean add(T element) {
         boolean result = super.add(element);
@@ -26,16 +46,30 @@ public class LimitedList<T> extends ArrayList<T> {
         return result;
     }
 
-    //TODO Javadoc
+    /**
+     * Sets a new size limit for this list.
+     *
+     * @param num the new limit.
+     */
     public void setLimit(int num) {
-        this.limit=num;
+        this.limit = num;
     }
 
-    //TODO Javadoc
+    /**
-    public int getLimit(){return limit;}
+     * Returns the current size limit of this list.
+     *
+     * @return the current limit.
+     */
+    public int getLimit() {
+        return limit;
+    }
 
-    //TODO Javadoc
+    /**
+     * Sets a new action to execute when the list size reaches or exceeds the limit.
+     *
+     * @param action the new action to set.
+     */
     public void setAction(Runnable action) {
-        this.action=action;
+        this.action = action;
     }
 }

src/main/java/it/polimi/ingsw/gc14/Model/DecksCreator.java

@@ -15,10 +15,19 @@ import java.io.*;
 import java.lang.reflect.Type;
 import java.util.*;
 
-//TODO javadoc
+/**
+ * Utility class responsible for loading and creating decks of cards and slots for the game.
+ * Cards are loaded from JSON resource files and instantiated according to their type and parameters.
+ */
 public class DecksCreator {
 
-    //TODO javadoc
+    /**
+     * Loads the tribe card deck for the specified era from the corresponding JSON resource file.
+     *
+     * @param era the era number (1, 2, or 3).
+     * @return a list of {@link TribeCard} objects for the specified era.
+     * @throws IllegalArgumentException if {@code era} is not 1, 2, or 3.
+     */
     public static List<TribeCard> loadTribeDeckByEra(int era) throws IllegalArgumentException
     {
         return switch (era) {
@@ -29,7 +38,13 @@ public class DecksCreator {
         };
     }
 
-    //TODO javadoc
+    /**
+     * Loads a tribe card deck from the specified JSON resource file path.
+     *
+     * @param resourcePath the path to the JSON resource file.
+     * @return a list of {@link TribeCard} objects defined in the resource file.
+     * @throws RuntimeException if the resource file is not found or an error occurs while reading it.
+     */
     public static List<TribeCard> loadTribeDeck(String resourcePath) {
         Gson gson = new Gson();
         Type listType = new com.google.gson.reflect.TypeToken<List<TribeCardDefinition>>(){}.getType();
@@ -51,14 +66,26 @@ public class DecksCreator {
         }
     }
 
-    //TODO javadoc
+    /**
+     * Loads the building card deck for the specified era, filtering cards from the global building deck.
+     *
+     * @param era the era number (1, 2, or 3).
+     * @return a list of {@link BuildingCard} objects belonging to the specified era.
+     * @throws IllegalArgumentException if {@code era} is not 1, 2, or 3.
+     */
     public static List<BuildingCard> loadBuildingDeckByEra(int era) throws IllegalArgumentException
     {
         if(era<=0 || era>3) throw new IllegalArgumentException();
         return loadBuildingDeck("/Cards/buildingCards.json").stream().filter(x->x.getEra()==era).toList();
     }
 
-    //TODO javadoc
+    /**
+     * Loads the full building card deck from the specified JSON resource file path.
+     *
+     * @param resourcePath the path to the JSON resource file.
+     * @return a list of {@link BuildingCard} objects defined in the resource file.
+     * @throws RuntimeException if the resource file is not found or an error occurs while reading it.
+     */
     public static List<BuildingCard> loadBuildingDeck(String resourcePath) {
         Gson gson = new Gson();
         Type listType = new com.google.gson.reflect.TypeToken<List<BuildingCardDefinition>>(){}.getType();
@@ -80,7 +107,12 @@ public class DecksCreator {
         }
     }
 
-    //TODO javadoc
+    /**
+     * Creates and returns the list of slots used as the game board.
+     * Slots are labeled with the letters A through G.
+     *
+     * @return a list of {@link Slot} objects representing the game board.
+     */
     public static List<Slot> loadSlotDeck()
     {
         List<Slot> slots = new ArrayList<>();
@@ -90,7 +122,15 @@ public class DecksCreator {
         return slots;
     }
 
-    //TODO javadoc
+    /**
+     * Instantiates a {@link TribeCard} from the given definition.
+     * Depending on whether the card is an event or a character, the appropriate subclass is created
+     * using the type and parameters specified in the definition.
+     *
+     * @param def the {@link TribeCardDefinition} containing the card's type, era, and parameters.
+     * @return the instantiated {@link TribeCard}.
+     * @throws IllegalArgumentException if the card type is unknown or the parameters are invalid.
+     */
     private static TribeCard createCard(TribeCardDefinition def) {
         int era = def.era;
 
@@ -138,7 +178,14 @@ public class DecksCreator {
         };
     }
 
-    //TODO javadoc
+    /**
+     * Instantiates a {@link BuildingCard} from the given definition.
+     * The appropriate subclass is selected based on the effect ID specified in the definition.
+     * If no specific subclass matches the effect ID, a base {@link BuildingCard} is created.
+     *
+     * @param def the {@link BuildingCardDefinition} containing the card's effect ID, era, price, prestige value, and parameters.
+     * @return the instantiated {@link BuildingCard}.
+     */
     private static BuildingCard createCard(BuildingCardDefinition def) {
         return switch (def.effectId) {
             case 0 -> new Building0(def.era, def.price, def.prestigeValue);
@@ -153,7 +200,11 @@ public class DecksCreator {
 
     }
 
-    //TODO javadoc
+    /**
+     * Internal data class representing the raw definition of a tribe card as loaded from a JSON file.
+     * Contains the card type, era, whether it is armed, whether it is an event card,
+     * and a list of additional parameters.
+     */
     private static class TribeCardDefinition {
         String type;
         int era;
@@ -162,7 +213,10 @@ public class DecksCreator {
         List<Object> params; // Object per gestire boolean e int misti
     }
 
-    //TODO javadoc
+    /**
+     * Internal data class representing the raw definition of a building card as loaded from a JSON file.
+     * Contains the effect ID, era, price, prestige value, and a list of additional parameters.
+     */
     private static class BuildingCardDefinition {
         int effectId;
         int era;

src/main/java/it/polimi/ingsw/gc14/Network/RMI/Client/RMIClient.java

@@ -40,7 +40,7 @@ public class RMIClient  implements IClient {
         this.port = port;
     }
 
-    //TODO Javadoc fix
+
     /**
      * Connects to the RMI server and attempts to join the game.
      * Looks up the RMI registry to retrieve the {@link IGameServer} stub.