From b76cad4938c5b5506e544c6ca268caa5b68b2fc2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Einar=20Sk=C3=B8ien?= Date: Wed, 25 Feb 2026 11:23:58 +0100 Subject: [PATCH] add javadoc in Exhange, Player and Portfolio --- .../idatt2003/gruppe42/Model/Exchange.java | 56 ++++++++++++++++++- .../idi/idatt2003/gruppe42/Model/Player.java | 19 +++++-- .../idatt2003/gruppe42/Model/Portfolio.java | 30 ++++++---- 3 files changed, 86 insertions(+), 19 deletions(-) diff --git a/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Exchange.java b/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Exchange.java index 467734a..9fb9000 100644 --- a/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Exchange.java +++ b/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Exchange.java @@ -4,7 +4,6 @@ import edu.ntnu.idi.idatt2003.gruppe42.Model.Transaction.Purchase; import edu.ntnu.idi.idatt2003.gruppe42.Model.Transaction.Sale; import edu.ntnu.idi.idatt2003.gruppe42.Model.Transaction.Transaction; - import java.math.BigDecimal; import java.util.ArrayList; import java.util.HashMap; @@ -12,6 +11,13 @@ import java.util.Map; import java.util.Random; +/** + * Represents a stock exchange where players can buy and sell shares. + *

+ * The {@code Exchange} keeps track of available stocks, the current week in the simulation, + * and allows players to perform transactions such as buying or selling shares. + *

+ */ public class Exchange { private String name; private int week; @@ -19,6 +25,12 @@ public class Exchange { private Random random; private List stocks; + /** + * Constructs a new {@code Exchange} with a name and a list of stocks. + * + * @param name the name of the exchange (e.g., "NYSE") + * @param stocks the initial list of available stocks on the exchange + */ public Exchange(String name, List stocks) { this.name = name; this.week = 0; @@ -35,14 +47,32 @@ public int getWeek() { return week; } + /** + * Checks if the exchange has a stock with the given symbol. + * + * @param symbol the stock symbol to check + * @return {@code true} if the stock exists on the exchange, {@code false} otherwise + */ public boolean hasStock(String symbol) { return stockMap.containsKey(symbol); } + /** + * Returns the stock associated with the given symbol. + * + * @param symbol the symbol of the stock to retrieve + * @return the {@code Stock} object, or {@code null} if not found + */ public Stock getStock(String symbol) { return stockMap.get(symbol); } + /** + * Finds stocks by company name. + * + * @param searchTerm the company name to search for + * @return a list of {@code Stock} objects whose company name matches the search term + */ public List findStocks(String searchTerm) { List foundStocks = new ArrayList<>(); @@ -54,6 +84,17 @@ public List findStocks(String searchTerm) { return foundStocks; } + /** + * Allows a player to buy a stock from the exchange. + *

+ * The player’s money is withdrawn by the quantity amount, and a {@code Purchase} transaction is returned. + *

+ * + * @param symbol the symbol of the stock to buy + * @param quantity the amount of stock to buy + * @param player the player performing the purchase + * @return a {@code Purchase} transaction representing the purchase + */ public Transaction buy(String symbol, BigDecimal quantity, Player player) { player.withdrawMoney(quantity); @@ -64,12 +105,25 @@ public Transaction buy(String symbol, BigDecimal quantity, Player player) { return new Purchase(share, week); } + /** + * Allows a player to sell a share on the exchange. + *

+ * The player receives money based on the sale calculation, and a {@code Sale} transaction is returned. + *

+ * + * @param share the share to sell + * @param player the player performing the sale + * @return a {@code Sale} transaction representing the sale + */ public Transaction sell(Share share, Player player) { SaleCalculator saleCalculator = new SaleCalculator(share); player.addMoney(saleCalculator.calculateTotal()); return new Sale(share, week); } + /** + * Advances the simulation by 1 week. + */ public void advance() { week += 1; } diff --git a/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Player.java b/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Player.java index b5dff97..d505c60 100644 --- a/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Player.java +++ b/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Player.java @@ -4,8 +4,12 @@ import java.math.BigDecimal; /** - * Player represents the user, the money they own, and their portfolio. - * The class includes methods for adding and withdrawing money from the players portfolio. + * Represents a player in the stock market simulation. + *

+ * A {@code Player} has a name, starting money, current money balance, + * a {@link Portfolio} of shares, and a {@link TransactionArchive} of past transactions. + * The player can add or withdraw money, and manage their portfolio through purchases and sales. + *

*/ public class Player { private final String name; @@ -15,9 +19,10 @@ public class Player { private TransactionArchive transactionArchive; /** + * Constructs a new {@code Player} with a name and starting money. * - * @param name - * @param startingMoney + * @param name the name of the player + * @param startingMoney the initial amount of money the player has */ public Player(String name, BigDecimal startingMoney) { this.name = name; @@ -45,16 +50,18 @@ public BigDecimal getMoney() { } /** + * Adds the specified amount of money to the player's balance. * - * @param amount is the amount that will be added to players account. + * @param amount the amount to add to the player's account */ public void addMoney(BigDecimal amount) { money = money.add(amount); } /** + * Withdraws the specified amount of money from the player's balance. * - * @param amount is the amount that will be withdrawn from players account. + * @param amount the amount to withdraw from the player's account */ public void withdrawMoney(BigDecimal amount) { money = money.subtract(amount); diff --git a/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Portfolio.java b/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Portfolio.java index 0c39fb4..e1ef3ec 100644 --- a/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Portfolio.java +++ b/src/main/java/edu/ntnu/idi/idatt2003/gruppe42/Model/Portfolio.java @@ -4,23 +4,27 @@ import java.util.List; /** - * Portfolio represents a collection of {@link Share} objects owned by a {@link Player}. - * The class includes methods for adding, removing and getting shares from the portfolio. + * Represents a collection of {@link Share} objects owned by a {@link Player}. + *

+ * A {@code Portfolio} allows adding, removing, and querying shares. + * It serves as the player's collection of owned shares. + *

*/ public class Portfolio { private List shares; /** - * The constructor of the {@link Portfolio} class. + * Constructs an empty {@code Portfolio}. */ public Portfolio() { this.shares = new ArrayList<>(); } /** - * Method for adding a share to a portfolio. - * @param share represents the share to be added to the portfolio. - * @return true or false based on if the operation was successful or not. + * Adds a share to the portfolio. + * + * @param share the {@code Share} to add + * @return {@code true} if the share was successfully added, {@code false} if the share was {@code null} */ public boolean addShare(Share share) { if (share == null) { @@ -31,9 +35,11 @@ public boolean addShare(Share share) { } /** - * Method for removing a share to a portfolio. - * @param share represents the share to be removed from the portfolio. - * @return true or false based on if the operation was successful or not. + * Removes a share from the portfolio. + * + * @param share the {@code Share} to remove + * @return {@code true} if the share was successfully removed, + * {@code false} if the share was {@code null} or not present in the portfolio */ public boolean removeShare(Share share) { if (share == null || !shares.contains(share)) { @@ -48,9 +54,9 @@ public List getShares() { } /** - * Method for checking if a portfolio contains a given share. - * @param share represents the share to be checked. - * @return true or false based on if the share was found or not. + * Checks whether the portfolio contains a given share. + * @param share the {@code Share} to check for + * @return {@code true} if the share exists in the portfolio, {@code false} if {@code null} or not found */ public boolean contains(Share share) { return share != null && shares.contains(share);