Merge pull request #33

Javadoc-for-Sustenance-CavePaintings-GameController

src/main/java/it/polimi/ingsw/gc14/Controller/GameController.java

@@ -3,40 +3,114 @@ package it.polimi.ingsw.gc14.Controller;
 import it.polimi.ingsw.gc14.Model.Game;
 import it.polimi.ingsw.gc14.Model.Player;
 
+/**
+ * Controller class that manages interactions between the client-side logic
+ * and the {@link Game} model.
+ * It provides methods to add players and to perform game actions by delegating them to the model.
+ */
 public class GameController {
+
+    /**
+     * The game model managed by this controller.
+     */
     private Game model;
+
+    /**
+     * Creates a GameController associated with the specified game model.
+     *
+     * @param model the game model managed by this controller.
+     */
     public GameController(Game model) {
         this.model = model;
     }
+
+    /**
+     * Creates a GameController without an associated game model.
+     */
     public GameController() {
     }
+
+    /**
+     * Returns the game model managed by this controller.
+     *
+     * @return the game model managed by this controller.
+     */
     public Game getModel() {
         return model;
     }
+
+    /**
+     * Updates the game model managed by this controller.
+     *
+     * @param model the new game model managed by this controller.
+     */
     public void setModel(Game model) {
         this.model = model;
     }
+
+    /**
+     * Attempts to add a new player with the specified username to the game model.
+     *
+     * @param username the username of the player to add.
+     * @return {@code true} if the player is successfully added, {@code false} otherwise.
+     */
     public boolean addPlayer(String username) {
         return model.addPlayer(new Player(username));
     }
+
+    /**
+     * Attempts to draw an upper tribe card for the specified player from the specified position.
+     *
+     * @param playerUsername the username of the player performing the action.
+     * @param pos the position of the upper tribe card to draw.
+     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
+     *         or if the draw operation fails.
+     */
     public boolean drawUpperTribeCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
         if(player==null)
             return false;
         return model.DrawUpperTribeCardByIndex(model.getPlayerByUsername(playerUsername),pos);
     }
+
+    /**
+     * Attempts to draw a lower tribe card for the specified player from the specified position.
+     *
+     * @param playerUsername the username of the player performing the action.
+     * @param pos the position of the lower tribe card to draw.
+     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
+     *         or if the draw operation fails.
+     */
     public boolean drawLowerTribeCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
         if(player==null)
             return false;
         return model.DrawLowerTribeCardByIndex(model.getPlayerByUsername(playerUsername), pos);
     }
+
+    /**
+     * Attempts to draw an upper building card for the specified player from the specified position.
+     *
+     * @param playerUsername the username of the player performing the action.
+     * @param pos the position of the upper building card to draw.
+     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
+     *         or if the draw operation fails.
+     */
     public boolean drawUpperBuildingCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
         if(player==null)
             return false;
         return model.DrawUpperBuildingCardByIndex(model.getPlayerByUsername(playerUsername), pos);
     }
+
+    /**
+     * Attempts to draw a lower building card for the specified player from the specified position.
+     *
+     * @param playerUsername the username of the player performing the action.
+     * @param pos the position of the lower building card to draw.
+     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
+     *         or if the draw operation fails.
+     */
     public boolean drawLowerBuildingCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
         if(player==null)
@@ -44,18 +118,44 @@ public class GameController {
         return model.DrawLowerBuildingCardByIndex(model.getPlayerByUsername(playerUsername), pos);
     }
 
+    /**
+     * Attempts to pick an optional tribe card for the specified player from the specified position.
+     *
+     * @param playerUsername the username of the player performing the action.
+     * @param pos the position of the optional tribe card to pick.
+     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
+     *         or if the pick operation fails.
+     */
     public boolean pickOptionalTribeCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
         if(player==null)
             return false;
         return model.PickOptionalTribeCardByIndex(model.getPlayerByUsername(playerUsername), pos);
     }
+
+    /**
+     * Attempts to pick an optional building card for the specified player from the specified position.
+     *
+     * @param playerUsername the username of the player performing the action.
+     * @param pos the position of the optional building card to pick.
+     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
+     *         or if the pick operation fails.
+     */
     public boolean pickOptionalBuildingCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
         if(player==null)
             return false;
         return model.PickOptionalBuildingCard(model.getPlayerByUsername(playerUsername), pos);
     }
+
+    /**
+     * Attempts to perform the slot choice action for the specified player at the specified position.
+     *
+     * @param playerUsername the username of the player performing the action.
+     * @param pos the position of the chosen slot.
+     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
+     *         or if the slot choice operation fails.
+     */
     public boolean slotChoice(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
         if(player==null)//playerIndex>=model.)

src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/Events/CavePaintings.java

@@ -11,9 +11,31 @@ import it.polimi.ingsw.gc14.Model.Player;
 import java.util.ArrayList;
 
 public class CavePaintings extends EventCard {
+
+    /**
+     * The minimum number of Artist cards required to avoid the prestige penalty.
+     * Also, the bottom number on the card.
+     */
     private int NLower;
+
+    /**
+     * The amount of Prestige removed if the player has fewer Artist cards than {@code NLower}.
+     */
     private int NPrestigeRem; // NPrestigeLower
+
+    /**
+     * The Prestige multiplier applied if the player has at least {@code NLower} Artist cards.
+     */
     private int NPrestigeMul; // NPrestigeUpper
+
+    /**
+     * Creates a CavePaintings event card with the specified era and effect parameters.
+     *
+     * @param Era the era of the event card.
+     * @param NLower the minimum number of Artist cards required to avoid the prestige penalty.
+     * @param NPrestigeRem the amount of Prestige removed if the player has fewer Artist cards than {@code NLower}.
+     * @param NPrestigeMul the Prestige multiplier applied if the player has at least {@code NLower} Artist cards.
+     */
     public CavePaintings(int Era, int NLower, int NPrestigeRem, int NPrestigeMul) {
         super(Era, EventType.CAVE_PAINTINGS);
         this.NLower = NLower;
@@ -21,6 +43,16 @@ public class CavePaintings extends EventCard {
         this.NPrestigeMul = NPrestigeMul;
     }
 
+    /**
+     * Activates the CavePaintings event for the specified list of players.
+     * For each player, the number of Artist cards is computed together with the number
+     * of owned building cards having effect id equal to 9.
+     * The player gains Food equal to the number of such buildings multiplied by the number of Artist cards.
+     * If the player has fewer Artist cards than {@code NLower}, the player loses {@code NPrestigeRem} Prestige.
+     * Otherwise, the player gains Prestige equal to {@code NPrestigeMul} multiplied by the number of Artist cards.
+     *
+     * @param playerList the list of players affected by the event.
+     */
     @Override
     public void activateEvent (ArrayList <Player> playerList){
         for (Player player : playerList){
@@ -42,6 +74,12 @@ public class CavePaintings extends EventCard {
             }
         }
     }
+
+    /**
+     * Creates and returns a copy of this CavePaintings event card.
+     *
+     * @return a clone of this CavePaintings event card.
+     */
     @Override
     public EventCard clone()
     {

src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/Events/Sustenance.java

@@ -9,17 +9,45 @@ import it.polimi.ingsw.gc14.Model.Player;
 import java.util.ArrayList;
 
 public class Sustenance extends EventCard {
+
+    /**
+     * The prestige penalty multiplier applied for each unpaid Food unit.
+     */
     private int PrestigeDebt;
+
+    /**
+     * Returns the prestige penalty multiplier associated with this Sustenance event.
+     *
+     * @return the prestige penalty multiplier associated with this Sustenance event.
+     */
     public int getPrestigeDebt() {
         return PrestigeDebt;
     }
 
+    /**
+     * Creates a Sustenance event card with the specified era and prestige debt value.
+     *
+     * @param Era the era of the event card.
+     * @param PrestigeDebt the prestige penalty multiplier for unpaid Food units.
+     */
     public Sustenance(int Era, int PrestigeDebt) {
         super(Era, EventType.SUSTENANCE);
         this.PrestigeDebt = PrestigeDebt;
     }
 
-    // Sustenence va eseguito per ultimo tra gli eventi
+    /**
+     * Activates the Sustenance event for the specified list of players.
+     * For each player, the required Food is computed from the total number of characters,
+     * reduced by the contribution of Gatherers and by any applicable character discounts
+     * granted by owned building cards with effect id equal to 1.
+     * If the resulting Food debt is positive, the player must pay it with available Food.
+     * If the player does not have enough Food, all remaining Food is removed and the player
+     * loses Prestige equal to the unpaid Food debt multiplied by {@code PrestigeDebt}.
+     * This event is intended to be executed last among event effects.
+     *
+     * @param playerList the list of players affected by the event.
+     * @throws NullPointerException if {@code playerList} or one of its required elements is {@code null}.
+     */
     @Override
     public void activateEvent (ArrayList <Player> playerList) throws NullPointerException {
         for(Player player : playerList){
@@ -51,6 +79,12 @@ public class Sustenance extends EventCard {
             }
         }
     }
+
+    /**
+     * Creates and returns a copy of this Sustenance event card.
+     *
+     * @return a clone of this Sustenance event card.
+     */
     @Override
     public EventCard clone() {
         return new Sustenance(getEra(), PrestigeDebt);