docs: refine JavaDoc for model, board and order classes

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.
+     * <p>The effective cost is reduced by the total reduction value provided
-     * If the purchase succeeds, the card is added to the player's building cards
+     * by the player's Builder cards, without dropping below zero. The purchase
-     * and marked as bought.
+     * 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){};

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.
+ *
+ * <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
+     * Returns a string representation of this {@code Character}. This specific variation is used in the {@code Game}'s
-     * toString to print a more detailed version.
+     * toString to provide a more detailed version.
      * <p>Includes:
      * <li>{@link it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType Type}
      * </p>

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 {
@@ -101,5 +101,3 @@ public abstract class EventCard extends TribeCard {
 
     // End Functions
 }
-
-

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;

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<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;
 
 

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.
+     *
+     * <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 position of the player associated with the specified username
-     * Returns the {@code Player}'s position based on it's {@code Username}.
+     * within the current order list.
-     * @param username The desired {@code Player}'s username.
+     *
-     * @return {@code int} - the {@code Player}'s position.
+     * @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)

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

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

src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order4.java

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

src/main/java/it/polimi/ingsw/gc14/Model/Orders/Order5.java

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

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
+     * Note: {@link #FoodValue} cannot be negative, so the method returns
-     * return {@code False} if {@code Value} is greater than the
+     * {@code false} if {@code Value} is greater than the amount of {@code Food}
-     * amount of {@code Food} the Player possesses, {@code False} otherwise.
+     * 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
+     * @return {@code Boolean} - {@code true} if the Food is successfully removed,
-     * the amount of {@code Food} the Player possesses, {@code False} otherwise.
+     *         {@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