Merge pull request #31

Javadoc,-per-le-classi-EventCard-Character-BuildingCard-TribeCard

src/main/java/it/polimi/ingsw/gc14/Model/Cards/BuildingCard.java

@@ -8,24 +8,76 @@ import it.polimi.ingsw.gc14.Model.Player;
 import java.util.ArrayList;
 
 public class BuildingCard extends PlayableCard implements Cloneable , BuildingEffect {
+
+    /**
+     * The price of this building card.
+     */
     private int price;
+
+    /**
+     * Returns the price of this building card.
+     *
+     * @return the price of this building card.
+     */
     public int getPrice() {
         return price;
     }
+
+    /**
+     * Indicates whether this building card has already been bought.
+     */
     private boolean bought;
+
+    /**
+     * The type of effect associated with this building card.
+     */
     protected EffectType effectType;
+
+    /**
+     * The identifier of the effect associated with this building card.
+     */
     protected int effectId;
+
+    /**
+     * The prestige value of this building card.
+     */
     private int prestigeValue;
+
+    /**
+     * Returns the prestige value of this building card.
+     *
+     * @return the prestige value of this building card.
+     */
     public int  getPrestigeValue() {
         return prestigeValue;
     }
+
+    /**
+     * Returns the identifier of the effect associated with this building card.
+     *
+     * @return the effect identifier of this building card.
+     */
     public int getEffectId() {
         return effectId;
     }
+
+    /**
+     * Returns the type of effect associated with this building card.
+     *
+     * @return the effect type of this building card.
+     */
     public EffectType getEffectType() {
         return effectType;
     }
 
+    /**
+     * Creates a building card with the specified era, price, and prestige value.
+     *
+     * @param era the era of the building card.
+     * @param price the price of the building card.
+     * @param prestigeValue the prestige value of the building card.
+     * @throws IllegalArgumentException if {@code price <= 0} or {@code prestigeValue < 0}
+     */
     public BuildingCard(int era,int price,int prestigeValue) throws IllegalArgumentException{
         super(era);
         if (price > 0) {
@@ -41,6 +93,20 @@ public class BuildingCard extends PlayableCard implements Cloneable , BuildingEf
 
         bought = false;
     }
+
+
+    /**
+     * Creates a building card with the specified effect identifier, era, price,
+     * and prestige value.
+     * The effect type is determined from the given effect identifier.
+     *
+     * @param effectId the identifier of the effect associated with the building card.
+     * @param era the era of the building card.
+     * @param price the price of the building card.
+     * @param prestigeValue the prestige value of the building card.
+     * @throws IllegalArgumentException if the effect identifier is not valid,
+     *         if {@code price <= 0}, or if {@code prestigeValue < 0}
+     */
     public BuildingCard(int effectId ,int era,int price,int prestigeValue) throws IllegalArgumentException{
         this.effectId = effectId;
         switch (effectId){
@@ -72,12 +138,28 @@ public class BuildingCard extends PlayableCard implements Cloneable , BuildingEf
         this(era,price,prestigeValue);
     }
 
-
+    /**
+     * Creates and returns a copy of this building card.
+     *
+     * @return a clone of this building card.
+     */
     @Override
     public BuildingCard clone()
     {
         return new BuildingCard(effectId,getEra(),getPrice(),getPrestigeValue());
     }
+
+    /**
+     * Attempts to buy this building card for the specified player.
+     * The purchase succeeds only if the card has not already been bought
+     * and the player can pay its price in Food.
+     * If the purchase succeeds, the card is added to the player's building cards
+     * and marked as bought.
+     *
+     * @param player the player attempting to buy the building card.
+     * @return {@code true} if the building card is successfully bought,
+     *         {@code false} otherwise.
+     */
     public boolean buy(Player player) {
         if( bought || !player.removeFood(getPrice()))
             return false;
@@ -85,8 +167,20 @@ public class BuildingCard extends PlayableCard implements Cloneable , BuildingEf
         bought=true;
         return true;
     }
+
+    /**
+     * Applies the effect of this building card to the specified player.
+     *
+     * @param player the player to whom the effect is applied.
+     */
+    @Override
     public void applyEffect(Player player){};
 
+    /**
+     * Returns the string representation of this building card.
+     *
+     * @return the string representation of this building card.
+     */
     @Override
     public String toString() {
         return "Era:"+String.valueOf(getEra())+" Price:"+String.valueOf(getPrice())+" Prestige:"+String.valueOf(getPrestigeValue());

src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCard.java

@@ -3,24 +3,71 @@ package it.polimi.ingsw.gc14.Model.Cards;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.Character;
 import it.polimi.ingsw.gc14.Model.PlayableCard;
 
+/**
+ * Abstract base class for all tribe cards.
+ * A TribeCard is a {@link PlayableCard} that may either be an event card
+ * or a non-event card, and may optionally specify a minimum number of players.
+ */
 public abstract class TribeCard extends PlayableCard {
+
+    /**
+     * Indicates whether this tribe card is an event card.
+     */
     private boolean isEventCard;
+
+    /**
+     * Returns whether this tribe card is an event card.
+     *
+     * @return {@code true} if this card is an event card, {@code false} otherwise.
+     */
     public boolean IsEventCard() {
         return isEventCard;
     }
 
+    /**
+     * The minimum number of players required for this tribe card.
+     */
     private int nMin=0;
+
+    /**
+     * Returns the minimum number of players required for this tribe card.
+     *
+     * @return the minimum number of players required for this tribe card.
+     */
     public int getNMin() {
         return nMin;
     }
+
+    /**
+     * Creates a tribe card with the specified era and event-card flag.
+     * The minimum number of players is set to 0.
+     *
+     * @param Era the era of the tribe card.
+     * @param isEventCard whether the card is an event card.
+     */
     public TribeCard(int Era,boolean isEventCard) {
         this(Era,isEventCard,0);
     }
+
+    /**
+     * Creates a tribe card with the specified era, event-card flag,
+     * and minimum number of players.
+     *
+     * @param Era the era of the tribe card.
+     * @param isEventCard whether the card is an event card.
+     * @param nMin the minimum number of players required for the card.
+     */
     public TribeCard(int Era,boolean isEventCard,int nMin) {
         super(Era);
         this.nMin=nMin;
         this.isEventCard=isEventCard;
     }
+
+    /**
+     * Creates and returns a copy of this tribe card.
+     *
+     * @return a clone of this tribe card.
+     */
     @Override
     public abstract TribeCard clone();
 }

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

@@ -3,29 +3,75 @@ package it.polimi.ingsw.gc14.Model.Cards.TribeCards;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCard;
 import it.polimi.ingsw.gc14.Model.Player;
 
-
+/**
+ * Abstract base class for all character cards.
+ * A Character is a {@link TribeCard} that is not an event card and is associated.
+ * with a specific {@link CharacterType}.
+ */
 public abstract class  Character extends TribeCard implements Cloneable {
+
+    /**
+     * The specific type of this character card.
+     */
     private CharacterType type;
+
+    /**
+     * Returns the type of this character card.
+     *
+     * @return the type of this character card.
+     */
     public CharacterType getType() {
         return type;
     }
 
+    /**
+     * Creates a character card with the specified era and character type.
+     *
+     * @param Era the era of the character card.
+     * @param type the type of the character card.
+     */
     public Character(int Era, CharacterType type){
         super(Era,false );
         this.type = type;
     }
+
+    /**
+     * Creates a character card with the specified era, character type,
+     * and minimum number of players.
+     *
+     * @param Era the era of the character card.
+     * @param type the type of the character card.
+     * @param nMin the minimum number of players required for the card.
+     */
     public Character(int Era, CharacterType type,int nMin){
         super(Era,false ,nMin);
         this.type = type;
     }
 
+    /**
+     * Returns the string representation of this character card.
+     * The returned string includes the string representation of the superclass
+     * and the string representation of the character type.
+     *
+     * @return the string representation of this character card.
+     */
     @Override
     public String toString() {
         return super.toString()+" "+type.toString();
     }
 
+    /**
+     * Creates and returns a copy of this character card.
+     *
+     * @return a clone of this character card.
+     */
     @Override
     public abstract Character clone();
 
+    /**
+     * Inserts this character card into the appropriate collection of the specified player.
+     *
+     * @param player the player who receives the character card.
+     */
     public abstract void insert(Player player);
 }

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

@@ -6,13 +6,37 @@ import it.polimi.ingsw.gc14.Model.Player;
 import java.util.ArrayList;
 import java.lang.reflect.Array;
 
+/**
+ * Abstract base class for all event cards.
+ * An EventCard is a {@link TribeCard} marked as an event card and associated.
+ * with a specific {@link EventType}.
+ */
 public abstract class EventCard extends TribeCard {
+
     // Getters
+
+    /**
+     * The specific type of this event card.
+     */
     private EventType type;
+
+    /**
+     * Returns the type of this event card.
+     *
+     * @return the type of this event card.
+     */
     public EventType getType() { return type; }
+
     // End getters
 
     // Constructors
+
+    /**
+     * Creates an event card with the specified era and event type.
+     *
+     * @param Era the era of the event card.
+     * @param type the type of the event card.
+     */
     public EventCard(int Era, EventType type) {
         super(Era,true);
         this.type = type;
@@ -20,15 +44,34 @@ public abstract class EventCard extends TribeCard {
     // End Constructors
 
     // Function
+
+    /**
+     * Creates and returns a copy of this event card.
+     *
+     * @return a clone of this event card.
+     */
     @Override
     public abstract TribeCard clone();
 
+    /**
+     * Returns the string representation of this event card.
+     * The returned string includes the string representation of the superclass
+     * and the string representation of the event type.
+     *
+     * @return the string representation of this event card.
+     */
     @Override
     public String toString() {
         return super.toString()+" "+type.toString();
     }
 
+    /**
+     * Activates the effect of this event card on the specified list of players.
+     *
+     * @param playerList the list of players affected by the event.
+     */
     public abstract void activateEvent (ArrayList <Player> playerList);
+
     // End Functions
 }