From b01ffd62b8b3e90773c1611ab981a603277c1502 Mon Sep 17 00:00:00 2001 From: MatteoPellegrino05 Date: Wed, 20 May 2026 17:42:42 +0200 Subject: [PATCH] docs: refine JavaDoc for model, board and order classes --- .../ingsw/gc14/Model/Cards/BuildingCard.java | 27 ++++++++++++------- .../Model/Cards/TribeCards/Character.java | 11 ++++---- .../Model/Cards/TribeCards/EventCard.java | 6 ++--- .../polimi/ingsw/gc14/Model/DecksCreator.java | 4 +-- .../ingsw/gc14/Model/GamePackage/Board.java | 9 ++++--- .../ingsw/gc14/Model/OrderLogicCard.java | 21 ++++++++++----- .../ingsw/gc14/Model/Orders/Order2.java | 4 +-- .../ingsw/gc14/Model/Orders/Order3.java | 2 +- .../ingsw/gc14/Model/Orders/Order4.java | 2 +- .../ingsw/gc14/Model/Orders/Order5.java | 4 +-- .../it/polimi/ingsw/gc14/Model/Player.java | 18 +++++++------ 11 files changed, 63 insertions(+), 45 deletions(-) diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/Cards/BuildingCard.java b/src/main/java/it/polimi/ingsw/gc14/Model/Cards/BuildingCard.java index 0d97326..aa2f201 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Cards/BuildingCard.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Cards/BuildingCard.java @@ -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. + * + *

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. + *

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()); } -} +} \ No newline at end of file diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/Character.java b/src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/Character.java index baed2bb..28877b3 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/Character.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/Character.java @@ -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. + * + *

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. *

Includes: *

  • {@link it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType Type} *

    @@ -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); -} +} \ No newline at end of file diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/EventCard.java b/src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/EventCard.java index b92e1c0..07bd61e 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/EventCard.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Cards/TribeCards/EventCard.java @@ -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 playerList); // End Functions -} - - +} \ No newline at end of file diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/DecksCreator.java b/src/main/java/it/polimi/ingsw/gc14/Model/DecksCreator.java index 93006f1..ffe490e 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/DecksCreator.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/DecksCreator.java @@ -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; diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/GamePackage/Board.java b/src/main/java/it/polimi/ingsw/gc14/Model/GamePackage/Board.java index 6e3023c..9dfe9e8 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/GamePackage/Board.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/GamePackage/Board.java @@ -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 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 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 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 lowerListBuilding; @@ -275,4 +278,4 @@ public class Board implements Serializable { upperListBuilding.addAll(buildingCardsAllEras.get(2)); } } -} +} \ No newline at end of file diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/OrderLogicCard.java b/src/main/java/it/polimi/ingsw/gc14/Model/OrderLogicCard.java index 6246856..6751815 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/OrderLogicCard.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/OrderLogicCard.java @@ -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. + * + *

    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. * + *

    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 { } -} +} \ No newline at end of file diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order2.java b/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order2.java index 2a0868b..4a73da0 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order2.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order2.java @@ -32,7 +32,7 @@ public class Order2 extends OrderLogicCard { /** * Applies the effect associated with the specified position index for the given player. *

    If {@code index == 0}, the player gains 1 Food and the building effect is applied. - *

    If {@code index == 1}, the player tries to remove 1 Food; if the player pay it, + *

    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"; } -} +} \ No newline at end of file diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order3.java b/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order3.java index 95b3713..3629b3b 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order3.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order3.java @@ -33,7 +33,7 @@ public class Order3 extends OrderLogicCard { * Applies the effect associated with the specified position index for the given player. *

    If {@code index == 0}, the player gains 2 Food and the building effect is applied. *

    If {@code index == 1}, no effect is applied. - *

    If {@code index == 2}, the player tries to remove 1 Food; if the player pay it, + *

    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. diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order4.java b/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order4.java index 2617845..4b4db23 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order4.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order4.java @@ -34,7 +34,7 @@ public class Order4 extends OrderLogicCard { *

    If {@code index == 0}, the player gains 2 Food and the building effect is applied. *

    If {@code index == 1}, the player gains 1 Food and the building effect is applied. *

    If {@code index == 2}, no effect is applied. - *

    If {@code index == 3}, the player tries to remove 1 Food; if the player pay it, + *

    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. diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order5.java b/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order5.java index 5b3b843..64e31da 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order5.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order5.java @@ -35,7 +35,7 @@ public class Order5 extends OrderLogicCard { *

    If {@code index == 1}, the player gains 1 Food and the building effect is applied. *

    If {@code index == 2}, no effect is applied. *

    If {@code index == 3}, no effect is applied. - *

    If {@code index == 4}, the player tries to remove 1 Food; if the player pay it, + *

    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"; } -} +} \ No newline at end of file diff --git a/src/main/java/it/polimi/ingsw/gc14/Model/Player.java b/src/main/java/it/polimi/ingsw/gc14/Model/Player.java index 204e60e..7aff52b 100644 --- a/src/main/java/it/polimi/ingsw/gc14/Model/Player.java +++ b/src/main/java/it/polimi/ingsw/gc14/Model/Player.java @@ -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: - * 

    {@code UserName is empty or exceeds maximum permitted length.}
    +     *                                  
    {@code UserName is empty or exceeds maximum permitted length.}
    
      *
      * @see #UserName
      * @see #MAX_VALUE
@@ -336,4 +338,4 @@ public class Player implements Serializable {
         return table.build();
     }
     // endregion functions
-}
+}
\ No newline at end of file