Docs: refine JavaDoc for building effects and controllers

src/main/java/it/polimi/ingsw/gc14/Model/Cards/Building/Effects/Building0.java

@@ -8,28 +8,34 @@ import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 
 
 /**
- * From the moment you buy this building, every time you complete a set of 6 different characters, you gain 5 food.
- * Note: sets of characters already present before purchasing the building do not count.
+ * Building effect that grants 5 food for each new complete set of
+ * 6 different character types obtained after purchasing this building.
+ *
+ * <p>Character sets already completed before the building is purchased
+ * are stored during initialization and do not provide food.
  */
 public class Building0 extends BuildingCard {
 
     /**
-     * The purchased attribute is used to indicate whether the card has already been initialized.
+     * Indicates whether the building effect has already been initialized
+     * after purchase.
      */
     boolean purchased ;
 
     /**
-     * The numSet attribute indicates how many complete sets the player has.
+     * Number of complete character sets already counted by this building effect.
      */
     private int numSet;
 
     /**
-     * Constructor of the building.
+     * Creates a building with the specified image identifier, era, price
+     * and prestige value.
      *
      * @param idImage the image identifier of the building.
      * @param era the game era of the building.
      * @param price the price in food of the building.
-     * @param prestigeValue the number of Prestige Points gained from this building at the end of the game.
+     * @param prestigeValue the number of Prestige Points granted by this building
+     *                      at the end of the game.
      */
     public Building0(String idImage,int era,int price,int prestigeValue) {
         super(idImage,era,price,prestigeValue);
@@ -40,10 +46,12 @@ public class Building0 extends BuildingCard {
     }
 
     /**
-     * Constructor of the building
-     * @param era The game era of the building.
-     * @param price The price (in food) of the building.
-     * @param prestigeValue The number of Prestige Points gained from this building at the end of the game.
+     * Creates a building with the specified era, price and prestige value.
+     *
+     * @param era the game era of the building.
+     * @param price the price in food of the building.
+     * @param prestigeValue the number of Prestige Points granted by this building
+     *                      at the end of the game.
      */
     public Building0(int era,int price,int prestigeValue) {
         super(era,price,prestigeValue);
@@ -54,9 +62,12 @@ public class Building0 extends BuildingCard {
     }
 
     /**
-     * Method used to purchase the building. It also handles its initialization.
-     * @param player The player who buys the building.
-     * @return The outcome of the operation.
+     * Attempts to purchase the building and initializes its effect if the
+     * purchase succeeds.
+     *
+     * @param player the player who attempts to buy the building.
+     * @return {@code true} if the building is successfully purchased and initialized,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean buy(Player player)
@@ -68,9 +79,12 @@ public class Building0 extends BuildingCard {
     }
 
     /**
-     * Initializes the building by counting the number of complete sets at the moment of purchase.
-     * The building can only be initialized once.
-     * @param player The player who owns the building, whose cards are counted to determine the number of sets.
+     * Initializes the building effect by storing the number of complete
+     * character sets already owned by the player at the moment of purchase.
+     *
+     * <p>The initialization is performed only once.
+     *
+     * @param player the player who owns the building.
      */
     public void initialize(Player player)
     {
@@ -88,8 +102,13 @@ public class Building0 extends BuildingCard {
     }
 
     /**
-     * Method to clone the building: it creates an exact copy.
-     * @return The new copy of the building
+     * Creates a new building instance with the same configuration values
+     * as this card.
+     *
+     * <p>The runtime state of the effect, such as initialization status and
+     * counted character sets, is not copied.
+     *
+     * @return a new building card with the same base properties.
      */
     @Override
     public BuildingCard clone() {
@@ -97,10 +116,13 @@ public class Building0 extends BuildingCard {
     }
 
     /**
-     * Calculates the current number of card sets and subtracts the previous value (i.e., the number of newly obtained sets).
-     * The player gains an amount of food equal to 5 times this result.
-     * @param player The player who owns the building.
-     * @throws IllegalArgumentException thrown if the specified player does not own this card.
+     * Applies the building effect to the specified player.
+     *
+     * <p>The method counts the complete character sets currently owned by the player
+     * and grants 5 food for each set completed since the last stored value.
+     *
+     * @param player the player who owns the building.
+     * @throws IllegalArgumentException if the specified player does not own this card.
      */
     @Override
     public void applyEffect(Player player) throws IllegalArgumentException {
@@ -120,4 +142,4 @@ public class Building0 extends BuildingCard {
         numSet=min_temp;
     };
 
-}
+}

src/main/java/it/polimi/ingsw/gc14/Model/Cards/Building/Effects/Building1.java

@@ -5,27 +5,31 @@ import it.polimi.ingsw.gc14.Model.Cards.BuildingCard;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 
 /**
- * During the Sustenance Event, you have a discount of 1 food token on the total you
- * would have to pay, for each of the indicated characters in your tribe.
+ * Building effect that grants a discount of 1 food during the Sustenance Event
+ * for each character of the indicated type present in the player's tribe.
  */
 public class Building1 extends BuildingCard {
 
     /**
-     * The icon attribute indicates the character type involved in the building effect.
+     * Character type involved in the building effect.
      */
     private CharacterType icon ;
 
     /**
-     * @return The character type associated with this building effect.
+     * Returns the character type associated with this building effect.
+     *
+     * @return the character type associated with this building effect.
      */
     public CharacterType getIcon() {return icon;}
 
     /**
-     * Constructor of the building.
-     * @param era The game era of the building.
-     * @param price The price (in food) of the building.
-     * @param prestigeValue The number of Prestige Points gained from this building at the end of the game.
-     * @param icon The character type used by the building effect.
+     * Creates a building with the specified era, price, prestige value
+     * and character type involved in its effect.
+     *
+     * @param era the game era of the building.
+     * @param price the price in food of the building.
+     * @param prestigeValue the number of Prestige Points gained from this building at the end of the game.
+     * @param icon the character type used by the building effect.
      */
     public Building1(int era, int price,int prestigeValue, CharacterType icon) {
         super(era,price,prestigeValue);
@@ -35,7 +39,8 @@ public class Building1 extends BuildingCard {
     }
 
     /**
-     * Constructor of the building.
+     * Creates a building with the specified image identifier, era, price,
+     * prestige value and character type involved in its effect.
      *
      * @param idIMG the image identifier of the building.
      * @param era the game era of the building.
@@ -51,8 +56,10 @@ public class Building1 extends BuildingCard {
     }
 
     /**
-     * Method to clone the building: it creates an exact copy.
-     * @return The new copy of the building.
+     * Creates a new building instance with the same configuration values
+     * as this card.
+     *
+     * @return a new building card with the same base properties and icon.
      */
     @Override
     public BuildingCard clone() {
@@ -60,17 +67,13 @@ public class Building1 extends BuildingCard {
     }
 
     /**
-     * Prints a string representation of this {@code Building1}. This specific variation is used in the {@code Game}'s
-     * toString to print a more detailed version.
-     * <p>includes:
-     * <li>{@link #icon Icon}
-     * </p>
-     * @return {@code String} - a string representation of this {@code Building1}.
-     * @see it.polimi.ingsw.gc14.Model.Game Game
-     * @see it.polimi.ingsw.gc14.Model.GamePackage.Board Board
+     * Returns a string representation of this building, including the character
+     * type associated with its effect.
+     *
+     * @return a string representation of this building.
      */
     @Override
     public String toString() {
         return super.toString() + " Icon: " + this.icon.toString().charAt(0);
     }
-}
+}

src/main/java/it/polimi/ingsw/gc14/Model/Cards/Building/Effects/Building10.java

@@ -8,9 +8,10 @@ import it.polimi.ingsw.gc14.Model.Player;
 import java.util.HashMap;
 
 /**
- * Represents the building card number 10.
+ * At the end of the game, the player gains 6 Prestige Points
+ * for each complete set of character types in their tribe.
  *
- * <p>This class defines the specific behavior and effects of building card 10.
+ * <p>A complete set contains one character card of each {@link CharacterType}.
  */
 public class Building10 extends BuildingCard {
 
@@ -53,8 +54,9 @@ public class Building10 extends BuildingCard {
 
     /**
      * Applies the effect of this building card to the specified player.
-     * The effect grants 6 prestige points for each complete set of character cards.
-     * owned by the player, where a complete set contains one card of each.
+     *
+     * <p>The effect grants 6 Prestige Points for each complete set of character
+     * cards owned by the player, where a complete set contains one card of each
      * {@link CharacterType}.
      *
      * @param player the player to whom the effect is applied.

src/main/java/it/polimi/ingsw/gc14/Model/Cards/Building/Effects/Building11.java

@@ -6,9 +6,11 @@ import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 import it.polimi.ingsw.gc14.Model.Player;
 
 /**
- * Represents the building card number 11.
+ * At the end of the game, the player gains Prestige Points based on the number
+ * of cards of the indicated character type in their tribe.
  *
- * <p>This class defines the specific behavior and effects of building card 11.
+ * <p>The gained amount is equal to the number of matching character cards
+ * multiplied by the building's prestige multiplier.
  */
 public class Building11 extends BuildingCard {
 
@@ -85,8 +87,8 @@ public class Building11 extends BuildingCard {
      * The effect grants prestige points equal to the number of cards of the
      * associated CharacterType owned by the player, multiplied by the prestige multiplier.
      *
-     * @param player the player to whom the effect is applied-
-     * @throws IllegalArgumentException if the player does not own this building card-
+     * @param player the player to whom the effect is applied.
+     * @throws IllegalArgumentException if the player does not own this building card.
      */
     @Override
     public void applyEffect(Player player) throws IllegalArgumentException {
@@ -96,15 +98,10 @@ public class Building11 extends BuildingCard {
     }
 
     /**
-     * Prints a string representation of this {@code Building1}. This specific variation is used in the {@code Game}'s
-     * toString to print a more detailed version.
-     * <p>includes:
-     * <li>{@link #icon Icon}
-     * <li>{@link #PrestigeMul Prestige Multiplier}
-     * </p>
-     * @return {@code String} - a string representation of this {@code Building1}.
-     * @see it.polimi.ingsw.gc14.Model.Game Game
-     * @see it.polimi.ingsw.gc14.Model.GamePackage.Board Board
+     * Returns a string representation of this {@code Building11}, including the
+     * character type associated with its effect and its prestige multiplier.
+     *
+     * @return a string representation of this {@code Building11}.
      */
     @Override
     public String toString() {

src/main/java/it/polimi/ingsw/gc14/Model/Cards/Building/Effects/Building13.java

@@ -5,9 +5,8 @@ import it.polimi.ingsw.gc14.Model.Cards.BuildingCard;
 import it.polimi.ingsw.gc14.Model.Player;
 
 /**
- * Represents the building card number 13.
- *
- * <p>This class defines the specific behavior and effects of building card 13.
+ * At the end of the game, this building grants 25 Prestige Points
+ * to the player who owns it.
  */
 public class Building13 extends BuildingCard{
 
@@ -49,7 +48,8 @@ public class Building13 extends BuildingCard{
     }
 
     /**
-     * Applies the effect of this building card to the specified player.
+     * Applies the effect of this building card to the specified player,
+     * granting 25 Prestige Points.
      *
      * @param player the player to whom the effect is applied.
      * @throws IllegalArgumentException if the player does not own this building card.

src/main/java/it/polimi/ingsw/gc14/Model/Cards/Building/Effects/Building4.java

@@ -8,23 +8,28 @@ import it.polimi.ingsw.gc14.Model.Player;
 import java.util.HashMap;
 
 /**
- * From the moment you purchase this building, every time you obtain a pair of identical inventors, you gain 3 food.
- * This effect doesn't apply to already owned pairs at the time of purchase.
+ * Building effect that grants 3 food for each new pair of identical inventors
+ * obtained after purchasing this building.
+ *
+ * <p>Pairs of identical inventors already owned at the moment of purchase
+ * are stored during initialization and do not provide food.
  */
 public class Building4 extends BuildingCard {
 
     /**
-     * The purchased attribute is used to indicate whether the card has already been initialized.
+     * Indicates whether the building effect has already been initialized
+     * after purchase.
      */
     boolean purchased ;
 
     /**
-     * The numPair attribute indicates how many pairs of inventors the player has.
+     * Number of inventor pairs already counted by this building effect.
      */
     int numPair;
 
     /**
-     * Constructor of the building
+     * Creates a building with the specified era, price and prestige value.
+     *
      * @param era The game era of the building.
      * @param price The price (in food) of the building.
      * @param prestigeValue The number of Prestige Points gained from this building at the end of the game.
@@ -36,7 +41,8 @@ public class Building4 extends BuildingCard {
     }
 
     /**
-     * Constructor of the building.
+     * Creates a building with the specified image identifier, era, price
+     * and prestige value.
      *
      * @param idIMG the image identifier of the building.
      * @param era the game era of the building.
@@ -50,9 +56,12 @@ public class Building4 extends BuildingCard {
     }
 
     /**
-     * Initializes the building by counting the number of pairs of inventors at the moment of purchase.
-     * The building can only be initialized once.
-     * @param player the player who owns the building, whose inventors are counted to determine the number of pairs.
+     * Initializes the building effect by storing the number of pairs of identical
+     * inventors already owned by the player at the moment of purchase.
+     *
+     * <p>The initialization is performed only once.
+     *
+     * @param player the player who owns the building.
      */
     public void initialize(Player player)
     {
@@ -79,9 +88,12 @@ public class Building4 extends BuildingCard {
     }
 
     /**
-     * Method used to purchase the building. It also handles its initialization.
+     * Attempts to purchase the building and initializes its effect if the
+     * purchase succeeds.
+     *
      * @param player The player who buys the building.
-     * @return The outcome of the operation.
+     * @return {@code true} if the building is successfully purchased and initialized,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean buy(Player player)
@@ -93,8 +105,13 @@ public class Building4 extends BuildingCard {
     }
 
     /**
-     * Method to clone the building: it creates an exact copy.
-     * @return The new copy of the building.
+     * Creates a new building instance with the same configuration values
+     * as this card.
+     *
+     * <p>The runtime state of the effect, such as initialization status and
+     * counted inventor pairs, is not copied.
+     *
+     * @return a new building card with the same base properties.
      */
     @Override
     public BuildingCard clone() {
@@ -102,8 +119,11 @@ public class Building4 extends BuildingCard {
     }
 
     /**
-     * Calculates the current number of pairs and subtracts the previous value (i.e., the number of newly obtained pairs).
-     * The player gains an amount of food equal to 3 times this result.
+     * Applies the building effect to the specified player.
+     *
+     * <p>The method counts the current number of pairs of identical inventors
+     * and grants 3 food for each pair obtained since the last stored value.
+     *
      * @param player The player who owns the building.
      * @throws IllegalArgumentException Thrown if the specified player does not own this card.
      */
@@ -132,4 +152,4 @@ public class Building4 extends BuildingCard {
         player.addFood(3*(temp-numPair));
         numPair = temp;
     };
-}
+}

src/main/java/it/polimi/ingsw/gc14/Model/Cards/Building/Effects/Building8.java

@@ -47,7 +47,11 @@ public class Building8 extends BuildingCard {
     }
 
     /**
-     * For each builder in the player's hand, the player gains double the Prestige Point indicated on the builder card.
+     * Applies the building effect by granting additional Prestige Points equal to
+     * the Prestige Value of each Builder card owned by the player.
+     *
+     * <p>This effectively doubles the contribution of Builder cards to the final score.
+     *
      * @param player The player who owns the building.
      * @throws IllegalArgumentException Thrown if the specified player does not own this building.
      */
@@ -60,4 +64,4 @@ public class Building8 extends BuildingCard {
         }
     }
 
-}
+}