docs: refine JavaDoc for model, board and order classes

2026-05-20 17:42:42 +02:00
parent 78a3edddf9
commit b01ffd62b8
11 changed files with 63 additions and 45 deletions
@@ -16,7 +16,7 @@ import java.io.Serializable;
 */
 public class BuildingCard extends PlayableCard implements Cloneable , BuildingEffect, Serializable {

-     /**
+    /**
     * The price of this building card.
     */
    private int price;
@@ -102,8 +102,10 @@ public class BuildingCard extends PlayableCard implements Cloneable , BuildingEf
    }

    /**
-     * Creates a building card with the specified era, price, and prestige value.
+     * Creates a building card with the specified image identifier, era, price,
+     * and prestige value.
     *
+     * @param idIMG the image identifier of 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.
@@ -160,7 +162,7 @@ public class BuildingCard extends PlayableCard implements Cloneable , BuildingEf
                this.effectType=EffectType.ON_EVENT;
                break;
            case 12:
-                    this.effectType=EffectType.ON_ROUND_END;
+                this.effectType=EffectType.ON_ROUND_END;
                break;
            default:
                throw new IllegalArgumentException();
@@ -227,10 +229,12 @@ public class BuildingCard extends PlayableCard implements Cloneable , BuildingEf

    /**
     * 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.
+     *
+     * <p>The effective cost is reduced by the total reduction value provided
+     * by the player's Builder cards, without dropping below zero. The purchase
+     * succeeds only if the card has not already been bought and the player can
+     * pay the resulting amount of Food. If successful, 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,
@@ -253,9 +257,12 @@ public class BuildingCard extends PlayableCard implements Cloneable , BuildingEf
    }

    /**
-     * Applies the effect of this building card to the specified player.
+     * Default implementation of the building effect.
     *
-     * @param player the player to whom the effect is applied.
+     * <p>This method does not perform any operation and can be overridden
+     * by specific building cards that define an active effect.
+     *
+     * @param player the player to whom the effect may be applied.
     */
    @Override
    public void applyEffect(Player player){};
@@ -269,4 +276,4 @@ public class BuildingCard extends PlayableCard implements Cloneable , BuildingEf
    public String toString() {
        return "⎕:" + " ID:" + String.valueOf(getEffectId())+ " $:"+String.valueOf(getPrice())+" PV:"+String.valueOf(getPrestigeValue());
    }
-}
+}
@@ -5,7 +5,8 @@ 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.
+ *
+ * <p>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 {
@@ -77,8 +78,6 @@ public abstract class  Character extends TribeCard implements Cloneable {

    /**
     * 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.
     */
@@ -89,8 +88,8 @@ public abstract class  Character extends TribeCard implements Cloneable {


    /**
-     * Prints a string representation of this {@code Character}. This specific variation is used in the {@code Game}'s
-     * toString to print a more detailed version.
+     * Returns a string representation of this {@code Character}. This specific variation is used in the {@code Game}'s
+     * toString to provide a more detailed version.
     * <p>Includes:
     * <li>{@link it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType Type}
     * </p>
@@ -118,4 +117,4 @@ public abstract class  Character extends TribeCard implements Cloneable {
     * @param player the player who receives the character card.
     */
    public abstract void insert(Player player);
-}
+}
@@ -8,7 +8,7 @@ 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.
+ * An EventCard is a {@link TribeCard} marked as an event card and associated
 * with a specific {@link EventType}.
 */
 public abstract class EventCard extends TribeCard {
@@ -100,6 +100,4 @@ public abstract class EventCard extends TribeCard {
    public abstract void activateEvent (ArrayList <Player> playerList);

    // End Functions
-}
-
-
+}
@@ -202,7 +202,7 @@ public class DecksCreator {

    /**
     * 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,
+     * Contains the card identifier, type, era, whether it is armed, whether it is an event card,
     * and a list of additional parameters.
     */
    private static class TribeCardDefinition {
@@ -216,7 +216,7 @@ public class DecksCreator {

    /**
     * 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.
+     * Contains the card identifier, effect ID, era, price, prestige value, and a list of additional parameters.
     */
    private static class BuildingCardDefinition {
        String id;
@@ -25,7 +25,10 @@ public class Board implements Serializable {
    /** tribeDeck is the deck from where you draw tribe cards as characters and events. */
    private Queue<TribeCard> tribeDeck;

-    /** The upper row of tribe cards. There must be (num. of players + 4) character cards + Event cards */
+    /**
+     * The upper row of tribe cards. It contains a total of
+     * {@code nTotem + 4} tribe cards, which may include both character and event cards.
+     */
    public List<TribeCard> upperListTribe;

    /**
@@ -38,7 +41,7 @@ public class Board implements Serializable {
    /** Contains all the building cards of the upper list. When a new era starts, all its building cards are placed here */
    public List<BuildingCard> upperListBuilding;

-    /** Contains all the building cards of the upper list. When a new era starts, the old era's buildings are moved from the upper to the lower list */
+    /** Contains all the building cards of the lower list. When a new era starts, the old era's buildings are moved from the upper to the lower list */
    public List<BuildingCard> lowerListBuilding;


@@ -275,4 +278,4 @@ public class Board implements Serializable {
            upperListBuilding.addAll(buildingCardsAllEras.get(2));
        }
    }
-}
+}
@@ -60,8 +60,12 @@ public abstract class OrderLogicCard implements Serializable {


    }
+
    /**
-     * Adds the player to the end of the queue, without effects.
+     * Moves the specified player to the end of the queue without applying effects.
+     *
+     * <p>Any previous occurrence of the player is removed from both the queue
+     * and the order list before the player is added again.
     *
     * @param player the player to be pushed into the queue.
     */
@@ -75,6 +79,9 @@ public abstract class OrderLogicCard implements Serializable {
    /**
     * Removes and returns the first player in the queue.
     *
+     * <p>The first order entry that has not yet been marked as played
+     * is marked as played before removing the player from the queue.
+     *
     * @return the first player in the queue, or {@code null} if the queue is empty.
     */
    public Player pull(){
@@ -121,10 +128,12 @@ public abstract class OrderLogicCard implements Serializable {
    }

    /**
-     * TODO rifare javadoc
-     * Returns the {@code Player}'s position based on it's {@code Username}.
-     * @param username The desired {@code Player}'s username.
-     * @return {@code int} - the {@code Player}'s position.
+     * Returns the position of the player associated with the specified username
+     * within the current order list.
+     *
+     * @param username the username of the player whose position is requested.
+     * @return the player's position, or {@code -1} if no player with the specified
+     *         username is present in the order list.
     * @see Player
     */
    public int getPosition(String username)
@@ -139,4 +148,4 @@ public abstract class OrderLogicCard implements Serializable {
    }


-}
+}
@@ -32,7 +32,7 @@ public class Order2 extends OrderLogicCard  {
    /**
     * Applies the effect associated with the specified position index for the given player.
     * <p>If {@code index == 0}, the player gains 1 Food and the building effect is applied.
-     * <p>If {@code index == 1}, the player tries to remove 1 Food; if the player pay it,
+     * <p>If {@code index == 1}, the player tries to remove 1 Food; if the player cannot pay it,
     * the player loses 2 Prestige.
     *
     * @param player the player to whom the effect is applied.
@@ -88,4 +88,4 @@ public class Order2 extends OrderLogicCard  {
        table.addRow(stringList);
        return "TURN ORDER\n" + table.build() + "\n";
    }
-}
+}
@@ -33,7 +33,7 @@ public class Order3 extends OrderLogicCard {
     * Applies the effect associated with the specified position index for the given player.
     * <p>If {@code index == 0}, the player gains 2 Food and the building effect is applied.
     * <p>If {@code index == 1}, no effect is applied.
-     * <p>If {@code index == 2}, the player tries to remove 1 Food; if the player pay it,
+     * <p>If {@code index == 2}, the player tries to remove 1 Food; if the player cannot pay it,
     * the player loses 2 Prestige.
     *
     * @param player the player to whom the effect is applied.
@@ -34,7 +34,7 @@ public class Order4 extends OrderLogicCard {
     * <p>If {@code index == 0}, the player gains 2 Food and the building effect is applied.
     * <p>If {@code index == 1}, the player gains 1 Food and the building effect is applied.
     * <p>If {@code index == 2}, no effect is applied.
-     * <p>If {@code index == 3}, the player tries to remove 1 Food; if the player pay it,
+     * <p>If {@code index == 3}, the player tries to remove 1 Food; if the player cannot pay it,
     * the player loses 2 Prestige.
     *
     * @param player the player to whom the effect is applied.
@@ -35,7 +35,7 @@ public class Order5 extends OrderLogicCard {
     * <p>If {@code index == 1}, the player gains 1 Food and the building effect is applied.
     * <p>If {@code index == 2}, no effect is applied.
     * <p>If {@code index == 3}, no effect is applied.
-     * <p>If {@code index == 4}, the player tries to remove 1 Food; if the player pay it,
+     * <p>If {@code index == 4}, the player tries to remove 1 Food; if the player cannot pay it,
     * the player loses 2 Prestige.
     *
     * @param player the player to whom the effect is applied.
@@ -101,4 +101,4 @@ public class Order5 extends OrderLogicCard {
        table.addRow(stringList);
        return "TURN ORDER\n" + table.build() + "\n";
    }
-}
+}
@@ -149,15 +149,16 @@ public class Player implements Serializable {

    /**
     * Removes {@code Value} amount of {@code Food} from the Player.
-     * Note: {@link #FoodValue} cannot be negative, so the method will
-     * return {@code False} if {@code Value} is greater than the
-     * amount of {@code Food} the Player possesses, {@code False} otherwise.
+     * Note: {@link #FoodValue} cannot be negative, so the method returns
+     * {@code false} if {@code Value} is greater than the amount of {@code Food}
+     * the Player possesses, and {@code true} otherwise.
+     *
     * @param Value The amount of {@code Food} to be removed.
     *              Should be positive for expected results
     *              (otherwise the method will add the absolute
     *              value of {@code Value}).
-     * @return {@code Boolean} - {@code True} if {@code Value} is greater than
-     * the amount of {@code Food} the Player possesses, {@code False} otherwise.
+     * @return {@code Boolean} - {@code true} if the Food is successfully removed,
+     *         {@code false} otherwise.
     * @see #FoodValue
     */
    public Boolean removeFood(int Value){
@@ -200,10 +201,11 @@ public class Player implements Serializable {

    /**
     * Constructor for the class {@code Player}. Each Player is uniquely identified by the {@link #UserName}.
+     *
     * @param UserName Unique String identifier for a Player.
-     * @throws IllegalArgumentException When {@code UserName} is {@code null} or exceeds {@link #MAX_VALUE}
+     * @throws IllegalArgumentException when {@code UserName} is empty or exceeds {@link #MAX_VALUE},
     *                                  with message:
-     *                                  <pre>{@code UserName is empty or exceeds maximum permitted length.}<pre>
+     *                                  <pre>{@code UserName is empty or exceeds maximum permitted length.}</pre>
     *
     * @see #UserName
     * @see #MAX_VALUE
@@ -336,4 +338,4 @@ public class Player implements Serializable {
        return table.build();
    }
    // endregion functions
-}
+}