Add: JavaDoc for Game constructors and game action methods

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

@@ -123,10 +123,21 @@ public class Game implements Serializable {
         return playersList.stream().filter(x->x.getUserName().equals(Username)).findFirst().orElse(null);
     }
 
-
+    /**
+     * Returns the configured number of players for this game.
+     *
+     * @return the configured number of players for this game.
+     */
     public int getNPlayers() {
         return nPlayers;
     }
+
+    /**
+     * Creates a game with the specified number of players.
+     *
+     * @param nPlayers the configured number of players for the game.
+     * @throws IllegalArgumentException if {@code nPlayers < 0} or {@code nPlayers > 5}.
+     */
     public Game(int nPlayers) throws IllegalArgumentException{
         if(nPlayers < 0||nPlayers > 5)
             throw new IllegalArgumentException();
@@ -141,11 +152,24 @@ public class Game implements Serializable {
         playersList = new ArrayList<>();
         OptionalCardQueue = new LinkedList<>();
     }
+
+    /**
+     * Creates a game with 0 configured players.
+     */
     public Game()
     {
         this(0);
     }
 
+    /**
+     * Attempts to add the specified player to the game.
+     * The operation succeeds only if the configured number of players is not 0,
+     * the current game stage is {@code WAITING}, and the player is not already present.
+     * If the number of players reaches the configured maximum, the game is initialized.
+     *
+     * @param player the player to add to the game.
+     * @return {@code true} if the player is successfully added, {@code false} otherwise.
+     */
     public boolean addPlayer(Player player) {
         if(this.nPlayers==0)
         {
@@ -162,6 +186,12 @@ public class Game implements Serializable {
         }
         return true;
     }
+
+    /**
+     * Initializes the game after all required players have been added.
+     * The method creates the appropriate order logic card according to the number of players,
+     * selects the first current player, and updates the game stage to {@code SLOT_CHOICE}.
+     */
     public void init() {
 
         switch (nPlayers) {
@@ -182,7 +212,18 @@ public class Game implements Serializable {
         currentState.GameStageUpdate(GameStages.SLOT_CHOICE);
     }
 
-    //region Cotroller Methods
+    //region Controller Methods
+
+    /**
+     * Attempts to assign the slot at the specified index to the specified player.
+     * The operation succeeds only if the index is valid, the current game stage is {@code SLOT_CHOICE},
+     * the specified player is the current player, and the selected slot is not already assigned.
+     * If the slot is successfully assigned, the next player setup is triggered.
+     *
+     * @param player the player performing the slot choice.
+     * @param slotIndex the index of the selected slot.
+     * @return {@code true} if the slot choice succeeds, {@code false} otherwise.
+     */
     public boolean SlotChoiceByIndex(Player player, int slotIndex) {
         if(slotIndex<0 || slotIndex>=slotMap.size())
             return  false;
@@ -206,6 +247,20 @@ public class Game implements Serializable {
     }
 
     //region Drawing Methods
+
+    /**
+     * Attempts to draw the upper tribe card at the specified index for the specified player.
+     * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS},
+     * the specified player is the current player, at least one upper card draw is still available,
+     * and the selected tribe card is not an event card.
+     * If successful, the card is inserted into the player's collection, removed from the board,
+     * and the number of remaining upper draws is decremented.
+     * If both upper and lower draws become zero, the next player setup is triggered.
+     *
+     * @param player the player performing the draw.
+     * @param cardIndex the index of the upper tribe card to draw.
+     * @return {@code true} if the draw succeeds, {@code false} otherwise.
+     */
     public boolean DrawUpperTribeCardByIndex(Player player,int cardIndex) {
         if( cardIndex<0 || cardIndex >=board.upperListTribe.size())
             return false;
@@ -232,6 +287,20 @@ public class Game implements Serializable {
         return true;
 
     }
+
+    /**
+     * Attempts to draw the lower tribe card at the specified index for the specified player.
+     * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS},
+     * the specified player is the current player, at least one lower card draw is still available,
+     * and the selected tribe card is not an event card.
+     * If successful, the card is inserted into the player's collection, removed from the board,
+     * and the number of remaining lower draws is decremented.
+     * If both lower and upper draws become zero, the next player setup is triggered.
+     *
+     * @param player the player performing the draw.
+     * @param cardIndex the index of the lower tribe card to draw.
+     * @return {@code true} if the draw succeeds, {@code false} otherwise.
+     */
     public boolean DrawLowerTribeCardByIndex(Player player, int cardIndex) {
         if( cardIndex<0 || cardIndex >=board.lowerListTribe.size())
             return false;
@@ -261,6 +330,18 @@ public class Game implements Serializable {
 
     }
 
+    /**
+     * Attempts to draw the upper building card at the specified index for the specified player.
+     * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS},
+     * the specified player is the current player, at least one upper card draw is still available,
+     * and the selected building card can be bought by the player.
+     * If successful, the building card is removed from the board and the number of remaining upper draws is decremented.
+     * If both upper and lower draws become zero, the next player setup is triggered.
+     *
+     * @param player the player performing the draw.
+     * @param cardIndex the index of the upper building card to draw.
+     * @return {@code true} if the draw succeeds, {@code false} otherwise.
+     */
     public boolean DrawUpperBuildingCardByIndex(Player player,int cardIndex) {
         if( cardIndex<0 || cardIndex >=board.upperListBuilding.size())
             return false;
@@ -287,6 +368,19 @@ public class Game implements Serializable {
 
         return true;
     }
+
+    /**
+     * Attempts to draw the lower building card at the specified index for the specified player.
+     * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS},
+     * the specified player is the current player, at least one lower card draw is still available,
+     * and the selected building card can be bought by the player.
+     * If successful, the building card is removed from the board and the number of remaining lower draws is decremented.
+     * If both lower and upper draws become zero, the next player setup is triggered.
+     *
+     * @param player the player performing the draw.
+     * @param cardIndex the index of the lower building card to draw.
+     * @return {@code true} if the draw succeeds, {@code false} otherwise.
+     */
     public boolean DrawLowerBuildingCardByIndex(Player player,int cardIndex) {
         if( cardIndex<0 || cardIndex >=board.lowerListBuilding.size())
             return false;