Fix and complete JavaDoc comments

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

@@ -2,6 +2,18 @@ package it.polimi.ingsw.gc14.Model.Cards.Building;
 
 import it.polimi.ingsw.gc14.Model.Player;
 
+/**
+ * Defines the effect behavior of a building card.
+ *
+ * <p>Classes implementing this interface provide the specific effect
+ * applied to a player when the building card is activated.
+ */
 public interface BuildingEffect {
-    public void applyEffect(Player player);
+
+    /**
+     * Applies the building effect to the specified player.
+     *
+     * @param player the player affected by the building effect.
+     */
+    void applyEffect(Player player);
 }

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

@@ -1,5 +1,10 @@
 package it.polimi.ingsw.gc14.Model.Cards.Building;
 
+/**
+ * Represents the possible effect types of building cards.
+ /**
+ * Represents the possible effect types of building cards.
+ */
 public enum EffectType {
     FINAL, CARD_SET, INVENTOR_PAIR, ON_EVENT, ON_END_TURN, ON_ROUND_END
 }

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

@@ -7,6 +7,11 @@ import it.polimi.ingsw.gc14.Model.Player;
 
 import java.util.HashMap;
 
+/**
+ * Represents the building card number 10.
+ *
+ * <p>This class defines the specific behavior and effects of building card 10.
+ */
 public class Building10 extends BuildingCard {
 
     /**

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

@@ -5,6 +5,11 @@ import it.polimi.ingsw.gc14.Model.Cards.BuildingCard;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 import it.polimi.ingsw.gc14.Model.Player;
 
+/**
+ * Represents the building card number 11.
+ *
+ * <p>This class defines the specific behavior and effects of building card 11.
+ */
 public class Building11 extends BuildingCard {
 
     /**

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

@@ -4,7 +4,13 @@ import it.polimi.ingsw.gc14.Model.Cards.Building.EffectType;
 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.
+ */
 public class Building13 extends BuildingCard{
+
     /**
      * Creates a Building13 card with the specified era, price, and prestige value.
      *

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

@@ -6,8 +6,16 @@ import it.polimi.ingsw.gc14.Model.PlayableCard;
 import it.polimi.ingsw.gc14.Model.Player;
 
 import java.io.Serializable;
-import java.util.ArrayList;
+
+/**
+ * Represents a generic building card in the game.
+ *
+ * <p>A building card is a playable card with a price and a specific building
+ * effect. Concrete building cards extend this class to define their own
+ * behavior.
+ */
 public class BuildingCard extends PlayableCard implements Cloneable , BuildingEffect, Serializable {
+
      /**
      * The price of this building card.
      */

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

@@ -1,5 +1,10 @@
 package it.polimi.ingsw.gc14.Model.Cards.TribeCards;
 
+/**
+ * Represents the different types of character cards available in the game.
+ /**
+ * Represents the different types of character cards available in the game.
+ */
 public enum CharacterType {
     INVENTOR, BUILDER, GATHERER, ARTIST, SHAMAN, HUNTER
 }

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

@@ -4,12 +4,18 @@ import it.polimi.ingsw.gc14.Model.Cards.TribeCards.Character;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 import it.polimi.ingsw.gc14.Model.Player;
 
+/**
+ * Represents an Artist character card.
+ *
+ * <p>An Artist is a specific type of {@link Character} initialized with
+ * {@link CharacterType#ARTIST}.
+ */
 public class Artist extends Character {
 
     /**
      * Creates an Artist character card with the specified era.
      *
-     * @param Era the era of the Artist card
+     * @param Era the era of the Artist card.
      */
     public Artist(int Era) {
         super(Era, CharacterType.ARTIST);
@@ -18,8 +24,8 @@ public class Artist extends Character {
     /**
      * Creates an Artist character card with the specified Era and minimum number of players required to play it.
      *
-     * @param Era the era of the Artist card
-     * @param nMin the minimum number of players required for the card
+     * @param Era the era of the Artist card.
+     * @param nMin the minimum number of players required for the card.
      */
     public Artist(int Era,int nMin) {
         super(Era, CharacterType.ARTIST,nMin);

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

@@ -4,7 +4,14 @@ import it.polimi.ingsw.gc14.Model.Cards.TribeCards.Character;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 import it.polimi.ingsw.gc14.Model.Player;
 
+/**
+ * Represents a Builder character card.
+ *
+ * <p>A Builder is a specific type of {@link Character} that provides
+ * a reduction value when buying building cards.
+ */
 public class Builder extends Character {
+
     /**
      * The reduction value provided by this Builder card.
      */

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

@@ -4,7 +4,14 @@ import it.polimi.ingsw.gc14.Model.Cards.TribeCards.Character;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 import it.polimi.ingsw.gc14.Model.Player;
 
+/**
+ * Represents a Gatherer character card.
+ *
+ * <p>A Gatherer is a specific type of {@link Character} initialized with
+ * {@link CharacterType#GATHERER}.
+ */
 public class Gatherer extends Character {
+
     /**
      * Creates a Gatherer character card with the specified era.
      *

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

@@ -4,6 +4,12 @@ import it.polimi.ingsw.gc14.Model.Cards.TribeCards.Character;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 import it.polimi.ingsw.gc14.Model.Player;
 
+/**
+ * Represents a Hunter character card.
+ *
+ * <p>A Hunter is a specific type of {@link Character} initialized with
+ * {@link CharacterType#HUNTER}.
+ */
 public class Hunter extends Character {
 
     /**

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

@@ -3,6 +3,12 @@ import it.polimi.ingsw.gc14.Model.Cards.TribeCards.Character;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 import it.polimi.ingsw.gc14.Model.Player;
 
+/**
+ * Represents an Inventor character card.
+ *
+ * <p>An Inventor is a specific type of {@link Character} initialized with
+ * {@link CharacterType#INVENTOR}.
+ */
 public class Inventor extends Character {
     /**
      * The {@code Icons}'s ID. There are a total of 10 different Icons.

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

@@ -1,10 +1,15 @@
 package it.polimi.ingsw.gc14.Model.Cards.TribeCards.Characters;
 
-import it.polimi.ingsw.gc14.Model.Cards.TribeCard;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.Character;
 import it.polimi.ingsw.gc14.Model.Cards.TribeCards.CharacterType;
 import it.polimi.ingsw.gc14.Model.Player;
 
+/**
+ * Represents a Shaman character card.
+ *
+ * <p>A Shaman is a specific type of {@link Character} initialized with
+ * {@link CharacterType#SHAMAN}.
+ */
 public class Shaman extends Character {
     /**
      * The number of star {@code Icons} the card possesses.

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

@@ -1,5 +1,10 @@
 package it.polimi.ingsw.gc14.Model.Cards.TribeCards;
 
+/**
+ * Represents the different types of event cards available in the game.
+ /**
+ * Represents the different types of event cards available in the game.
+ */
 public enum EventType {
     SUSTENANCE, SHAMANIC_RITUAL, CAVE_PAINTINGS, HUNT
 }

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

@@ -10,6 +10,11 @@ import it.polimi.ingsw.gc14.Model.Cards.TribeCards.EventCard;
 import it.polimi.ingsw.gc14.Model.Player;
 import java.util.ArrayList;
 
+/**
+ * Represents a Cave Paintings event card.
+ *
+ * <p>This class defines the specific behavior of the Cave Paintings event.
+ */
 public class CavePaintings extends EventCard {
 
     /**

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

@@ -36,9 +36,9 @@ public class Hunt extends EventCard {
      * Each player takes 1 Food and gains Prestige Points for each Hunter in their tribe.
      *
      * Buildings influence:
-     *      Building 7: you take 1 Food and 1 additional Prestige Point for each Hunter
+     *      Building 7: the player takes 1 Food and 1 additional Prestige Point for each Hunter.
      *
-     * @param playerList contains all the players in the game
+     * @param playerList the list of all players in the game.
      */
     @Override
     public void activateEvent (ArrayList <Player> playerList){

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

@@ -8,6 +8,11 @@ import it.polimi.ingsw.gc14.Model.Cards.TribeCards.EventCard;
 import it.polimi.ingsw.gc14.Model.Player;
 import java.util.ArrayList;
 
+/**
+ * Represents a Sustenance event card.
+ *
+ * <p>This class defines the specific behavior of the Sustenance event.
+ */
 public class Sustenance extends EventCard {
 
     /**

src/main/java/it/polimi/ingsw/gc14/Model/Game.java

@@ -28,12 +28,20 @@ import it.polimi.ingsw.gc14.View.TUI.BorderStyle;
  */
 public class Game implements Serializable {
 
+    /**
+     * List of observers registered to receive updates when the game state changes.
+     *
+     * <p>The list is marked as {@code transient} because observers should not be
+     * serialized with the game model.
+     */
     private transient List<Observer> observers = new ArrayList<>(); // transient! non serializzare
 
+
     public void addObserver(Observer observer) {
         observers.add(observer);
     }
 
+
     private void notifyObservers() {
         for (Observer o : observers) {
             o.update(this);
@@ -42,7 +50,8 @@ public class Game implements Serializable {
 
     /**
      * Returns the list of players participating in the game.
-     * @return
+     *
+     * @return a copy of the list of players currently participating in the game.
      */
     public List<Player> getPlayers() {
         return playersList;
@@ -149,6 +158,7 @@ public class Game implements Serializable {
      *
      * @param Username the username of the player to search for.
      * @return the player with the specified username, or {@code null} if no such player exists.
+     * @throws IndexOutOfBoundsException if an index access error occurs.
      */
     public Player getPlayerByUsername(String Username) throws IndexOutOfBoundsException {
         return playersList.stream().filter(x->x.getUserName().equals(Username)).findFirst().orElse(null);

src/main/java/it/polimi/ingsw/gc14/Model/GamePackage/Board.java

@@ -48,9 +48,9 @@ public class Board implements Serializable {
     private int era;
 
     /**
-     * Creates and returns a new list containing the slots (tiles) of the game
+     * Creates and returns a new list containing the slots (tiles) of the game.
      *
-     * @return a copy of the slot list
+     * @return a copy of the slot list.
      */
     public List<Slot> getSlotList(){
         return slotList.stream().map(x->new Slot(x.getSlotId())).collect(Collectors.toList());
@@ -71,13 +71,13 @@ public class Board implements Serializable {
 
     /**
      *  Creates and initializes a new board:
-     *      - Generate the slotList using a method of DecksCreator
-     *      - Generate the tribeDeck
-     *      - Populate the lower list (if there is an event card, it's added to the upper list)
-     *      - Populate the upper list
-     *      - Generate the buildingDeck using a method of DecksCreator
+     *      - Generate the slotList using a method of DecksCreator.
+     *      - Generate the tribeDeck.
+     *      - Populate the lower list (if there is an event card, it's added to the upper list).
+     *      - Populate the upper list.
+     *      - Generate the buildingDeck using a method of DecksCreator.
      *
-     * @param nTotem        the number of players
+     * @param nTotem        the number of players.
      */
     public Board(int nTotem) {
         this.nTotem = nTotem;
@@ -120,12 +120,12 @@ public class Board implements Serializable {
      * Creates the tribeDeck. Loads the cards from each era, shuffle them, and then combine them in the final deck.
      * In the end, two special events (Sustenance and ShamanicRitual) are added.
      *
-     * @param nPlayers      the number of players
+     * @param nPlayers      the number of players.
      * @return a queue containing the cards in this order:
-     *      - Era 1
-     *      - Era 2
-     *      - Era 3
-     *      - Special events
+     *      - Era 1.
+     *      - Era 2.
+     *      - Era 3.
+     *      - Special events.
      */
     private Queue<TribeCard>  generateTribeDeck(int nPlayers) {
         ArrayList<TribeCard> era1= DecksCreator.loadTribeDeckByEra(1).stream().filter(x->x.getNMin()<=nPlayers).collect(Collectors.toCollection(ArrayList::new));
@@ -150,40 +150,40 @@ public class Board implements Serializable {
     }
 
     /**
-     * Take the selected card from the upper tribe list of the board
+     * Take the selected card from the upper tribe list of the board.
      *
-     * @param tribeCard is the card to remove
-     * @return true if the card is succesfully removed
+     * @param tribeCard is the card to remove.
+     * @return true if the card is succesfully removed.
      */
     public boolean removeUpperTribeCard(TribeCard tribeCard) {
         return upperListTribe.remove(tribeCard);
     }
 
     /**
-     * Take the selected card from the lower tribe list of the board
+     * Take the selected card from the lower tribe list of the board.
      *
-     * @param tribeCard is the card to remove
-     * @return true if succeed in removing the card
+     * @param tribeCard is the card to remove.
+     * @return true if succeed in removing the card.
      */
     public boolean removeLowerTribeCard(TribeCard tribeCard) {
         return lowerListTribe.remove(tribeCard);
     }
 
     /**
-     * Take the selected card from the upper building list of the board
+     * Take the selected card from the upper building list of the board.
      *
-     * @param buildingCard is the card to remove
-     * @return true if succeed in removing the card
+     * @param buildingCard is the card to remove.
+     * @return true if succeed in removing the card.
      */
     public boolean removeUpperBuildingCard(BuildingCard buildingCard) {
         return upperListBuilding.remove(buildingCard);
     }
 
     /**
-     * Take the selected card from the lower building list of the board
+     * Take the selected card from the lower building list of the board.
      *
-     * @param buildingCard is the card to remove
-     * @return true if succeed in removing the card
+     * @param buildingCard is the card to remove.
+     * @return true if succeed in removing the card.
      */
     public boolean removeLowerBuildingCard(BuildingCard buildingCard) {
         return lowerListBuilding.remove(buildingCard);
@@ -191,10 +191,11 @@ public class Board implements Serializable {
 
     /**
      * Goes to the next round.
-     *      - Clear the lower tribe row
-     *      - Moves the upper tribe row to the lower one
-     *      - Populate the upper tribe row
+     *      - Clear the lower tribe row.
+     *      - Moves the upper tribe row to the lower one.
+     *      - Populate the upper tribe row.
      *
+     * @return the current era after moving to the next round.
      */
     public int nextRound() {
         lowerListTribe.clear();
@@ -216,9 +217,9 @@ public class Board implements Serializable {
 
     /**
      * Changes the era of the game:
-     *      - Increase the era attribute
-     *      - Clear the lower building list and replace it with the upper building list
-     *      - Repopulate the upper building list
+     *      - Increase the era attribute.
+     *      - Clear the lower building list and replace it with the upper building list.
+     *      - Repopulate the upper building list.
      */
     private void nextEra() {
         era=era+1;

src/main/java/it/polimi/ingsw/gc14/Model/GamePackage/GameStages.java

@@ -1,5 +1,10 @@
 package it.polimi.ingsw.gc14.Model.GamePackage;
 
+/**
+ * Represents the possible stages of a game.
+ /**
+ * Represents the possible stages of a game.
+ */
 public enum GameStages {
     WAITING, SLOT_CHOICE, RESOLVING_ACTIONS, OPTIONAL_CARD_EFFECT, RESOLVING_EVENT, ENDING, ENDED
 }

src/main/java/it/polimi/ingsw/gc14/Model/OrderLogicCard.java

@@ -9,6 +9,12 @@ import java.io.Serializable;
 import java.util.*;
 import java.util.stream.Collectors;
 
+/**
+ * Abstract base class for all order logic cards.
+ *
+ * <p>An order logic card manages the turn order of the players and defines
+ * the behavior used to update the order during the game.
+ */
 public abstract class OrderLogicCard implements Serializable {
 
     /**

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

@@ -8,6 +8,12 @@ import it.polimi.ingsw.gc14.View.TUI.BorderStyle;
 import java.util.*;
 import java.util.stream.IntStream;
 
+/**
+ * Represents the order logic card used in a two-player game.
+ *
+ * <p>This class defines the specific turn-order behavior for games with
+ * two players.
+ */
 public class Order2 extends OrderLogicCard  {
 
     /**

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

@@ -9,6 +9,12 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.NoSuchElementException;
 
+/**
+ * Represents the order logic card used in a three-player game.
+ *
+ * <p>This class defines the specific turn-order behavior for games with
+ * three players.
+ */
 public class Order3 extends OrderLogicCard {
 
     /**

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

@@ -9,6 +9,12 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.NoSuchElementException;
 
+/**
+ * Represents the order logic card used in a four-player game.
+ *
+ * <p>This class defines the specific turn-order behavior for games with
+ * four players.
+ */
 public class Order4 extends OrderLogicCard {
 
     /**

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

@@ -9,6 +9,12 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.NoSuchElementException;
 
+/**
+ * Represents the order logic card used in a five-player game.
+ *
+ * <p>This class defines the specific turn-order behavior for games with
+ * five players.
+ */
 public class Order5 extends OrderLogicCard {
 
     /**

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

@@ -5,24 +5,43 @@ import it.polimi.ingsw.gc14.Model.Player;
 import java.io.Serializable;
 
 /**
- * Abstract base class for all order {@code logic cards}.
- * An {@code OrderLogicCard} manages a queue of {@code players} and defines the effects
- * applied when they are pushed back into the queue.
- * @see it.polimi.ingsw.gc14.Model.Player Player 
+ * Represents a player entry in an order logic card.
+ *
+ * <p>Each entry stores the player and whether that player has already
+ * performed an action in the current order sequence.
  */
 public class OrderPlayer implements Serializable {
+
+    /**
+     * The player associated with this order entry.
+     */
     public Player player;
+
+    /**
+     * Indicates whether the player has already played.
+     */
     public boolean played;
-    public OrderPlayer(Player player,boolean played){
-        this.player=player;
-        this.played=played;
+
+    /**
+     * Creates an order entry for the specified player.
+     *
+     * @param player the player associated with this order entry.
+     * @param played {@code true} if the player has already played;
+     *               {@code false} otherwise.
+     */
+    public OrderPlayer(Player player, boolean played) {
+        this.player = player;
+        this.played = played;
     }
 
     /**
-     * @return the string containing the username and whether it played or not.
+     * Returns a string containing the player's username and whether the player
+     * has already played.
+     *
+     * @return the string containing the username and whether the player has played.
      */
     @Override
     public String toString() {
-        return player.getUserName()+" "+played;
+        return player.getUserName() + " " + played;
     }
 }