Docs: refine JavaDoc for building effects and controllers

src/main/java/it/polimi/ingsw/gc14/Controller/GameController.java

@@ -5,9 +5,10 @@ import it.polimi.ingsw.gc14.Model.Player;
 import it.polimi.ingsw.gc14.Model.Totems;
 
 /**
- * Controller class that manages interactions between the client-side logic
- * and the {@link Game} model.
- * It provides methods to add players and to perform game actions by delegating them to the model.
+ * Controller responsible for managing interactions with the {@link Game} model.
+ *
+ * <p>It provides methods to update the game state by delegating player-related
+ * actions and game actions to the underlying model.
  */
 public class GameController {
 
@@ -36,7 +37,8 @@ public class GameController {
      *
      * @param username the username of the player who disconnected.
      * @return {@code true} if the disconnection is handled successfully,
-     *         {@code false} if no player with the specified username exists.
+     *         {@code false} if no player with the specified username exists
+     *         or if the operation fails.
      */
     public boolean DisconnectedPlayer(String username)
     {
@@ -51,7 +53,8 @@ public class GameController {
      *
      * @param username the username of the player who reconnected.
      * @return {@code true} if the reconnection is handled successfully,
-     *         {@code false} if no player with the specified username exists.
+     *         {@code false} if no player with the specified username exists
+     *         or if the operation fails.
      */
     public boolean ReconnectPlayer(String username)
     {
@@ -83,19 +86,21 @@ public class GameController {
      * Attempts to add a new player with the specified username to the game model.
      *
      * @param username the username of the player to add.
-     * @return {@code true} if the player is successfully added, {@code false} otherwise.
+     * @return {@code true} if the player is successfully added,
+     *         {@code false} otherwise.
      */
     public boolean addPlayer(String username) {
         return model.addPlayer(new Player(username));
     }
 
     /**
-     * Attempts to draw an upper tribe card for the specified player from the specified position.
+     * Attempts to draw an upper tribe card for the specified player
+     * from the specified position.
      *
      * @param playerUsername the username of the player performing the action.
      * @param pos the position of the upper tribe card to draw.
-     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
-     *         or if the draw operation fails.
+     * @return {@code true} if the action succeeds,
+     *         {@code false} if the player does not exist or if the draw operation fails.
      */
     public boolean drawUpperTribeCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
@@ -105,12 +110,13 @@ public class GameController {
     }
 
     /**
-     * Attempts to draw a lower tribe card for the specified player from the specified position.
+     * Attempts to draw a lower tribe card for the specified player
+     * from the specified position.
      *
      * @param playerUsername the username of the player performing the action.
      * @param pos the position of the lower tribe card to draw.
-     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
-     *         or if the draw operation fails.
+     * @return {@code true} if the action succeeds,
+     *         {@code false} if the player does not exist or if the draw operation fails.
      */
     public boolean drawLowerTribeCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
@@ -120,12 +126,13 @@ public class GameController {
     }
 
     /**
-     * Attempts to draw an upper building card for the specified player from the specified position.
+     * Attempts to draw an upper building card for the specified player
+     * from the specified position.
      *
      * @param playerUsername the username of the player performing the action.
      * @param pos the position of the upper building card to draw.
-     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
-     *         or if the draw operation fails.
+     * @return {@code true} if the action succeeds,
+     *         {@code false} if the player does not exist or if the draw operation fails.
      */
     public boolean drawUpperBuildingCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
@@ -135,12 +142,13 @@ public class GameController {
     }
 
     /**
-     * Attempts to draw a lower building card for the specified player from the specified position.
+     * Attempts to draw a lower building card for the specified player
+     * from the specified position.
      *
      * @param playerUsername the username of the player performing the action.
      * @param pos the position of the lower building card to draw.
-     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
-     *         or if the draw operation fails.
+     * @return {@code true} if the action succeeds,
+     *         {@code false} if the player does not exist or if the draw operation fails.
      */
     public boolean drawLowerBuildingCard(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
@@ -153,9 +161,9 @@ public class GameController {
     /**
      * Skips the card drawing action for the specified player.
      *
-     * @param playerUsername the username of the player who wants to skip the turn action.
-     * @return {@code true} if the skip action is valid and successfully performed;
-     *         {@code false} if the player does not exist or the action is not valid.
+     * @param playerUsername the username of the player performing the action.
+     * @return {@code true} if the skip action is valid and successfully performed,
+     *         {@code false} if the player does not exist or if the action is not valid.
      */
     public boolean SkipTurn(String playerUsername) {
         Player player= model.getPlayerByUsername(playerUsername);
@@ -167,12 +175,13 @@ public class GameController {
 
 
     /**
-     * Attempts to perform the slot choice action for the specified player at the specified position.
+     * Attempts to perform the slot choice action for the specified player
+     * at the specified position.
      *
      * @param playerUsername the username of the player performing the action.
      * @param pos the position of the chosen slot.
-     * @return {@code true} if the action succeeds, {@code false} if the player does not exist
-     *         or if the slot choice operation fails.
+     * @return {@code true} if the action succeeds,
+     *         {@code false} if the player does not exist or if the slot choice operation fails.
      */
     public boolean slotChoice(String playerUsername,int pos) {
         Player player= model.getPlayerByUsername(playerUsername);
@@ -185,9 +194,10 @@ public class GameController {
      * Applies the totem choice made by the player associated with the specified username.
      *
      * @param playerUsername the username of the player making the choice.
-     * @param totem          the name of the selected totem.
+     * @param totem the name of the selected totem.
      * @return {@code true} if the choice is handled successfully,
-     *         {@code false} if no player with the specified username exists.
+     *         {@code false} if no player with the specified username exists
+     *         or if the choice operation fails.
      */
     public boolean TotemChoice(String playerUsername,String totem) {
         Player player= model.getPlayerByUsername(playerUsername);
@@ -195,4 +205,4 @@ public class GameController {
             return false;
         return model.TotemChoice(player, Totems.valueOf(totem));
     }
-}
+}