Merge pull request #5 from LimZiJia/Add-Javadoc

Add javadoc

data/transactions.txt

@@ -1,2 +0,0 @@
-a 10.00
-b 10.00

src/main/java/balancer/Main.java

@@ -7,21 +7,32 @@
 import balancer.logic.parser.BalancerParser;
 import balancer.storage.Storage;
 
+/**
+ * The main entry point of the application.
+ */
 public class Main {
     private static final String SAVE_DIRECTORY_NAME = "/data/";
     private static final String SAVE_FILE_NAME = "transactions.txt";
+    private static final String INITIAL_LOAD_SUCCESS = "Successfully loaded transaction list from " + SAVE_FILE_NAME;
     private static BalancerParser balancerParser = new BalancerParser();
     private static Storage storage = new Storage(SAVE_DIRECTORY_NAME, SAVE_FILE_NAME);
     private static Logic logic = new Logic(balancerParser, storage);
 
+    /**
+     * Loads transaction list from one that is saved and prints success message if successful.
+     */
     private static void startUp() {
         try {
             storage.load();
+            System.out.println(INITIAL_LOAD_SUCCESS);
         } catch (Exception e) {
             System.out.println(e);
         }
     }
 
+    /**
+     * The main loop of the program that takes user inputs and executes them.
+     */
     private static void run() {
         Scanner scanner = new Scanner(System.in);
 
@@ -33,8 +44,11 @@ private static void run() {
                 break;
             }
         }
-
     }
+
+    /**
+     * The abstracted flow of the application. It does a start-up sequence and runs.
+     */
     public static void main(String[] args) {
         startUp();
         run();

src/main/java/balancer/logic/Logic.java

@@ -5,15 +5,30 @@
 import balancer.logic.parser.BalancerParser;
 import balancer.storage.Storage;
 
+/**
+ * The runs the logic of the application. Takes in the user input and gets the {@code CommandResult}.
+ */
 public class Logic {
     private BalancerParser balancerParser;
     private Storage storage;
 
+    /**
+     * The constructor for {@code Logic}.
+     *
+     * @param balancerParser Used to parse user inputs.
+     * @param storage        Where all commands execute on.
+     */
     public Logic(BalancerParser balancerParser, Storage storage) {
         this.balancerParser = balancerParser;
         this.storage = storage;
     }
 
+    /**
+     * Executes user input command and returns the result.
+     *
+     * @param commandString The command entered by user.
+     * @return              The result of the command execution.
+     */
     public CommandResult execute(String commandString) {
         CommandResult commandResult;
         try {

src/main/java/balancer/logic/command/AddCommand.java

@@ -4,12 +4,22 @@
 
 import balancer.storage.Storage;
 
+/**
+ * Represents a {@code AddCommand} to add a transaction for a specific individual.
+ * Upon execution, adds the transaction to the storage and saves the changes.
+ */
 public class AddCommand extends Command {
     public static final String COMMAND_WORD = "add";
     private static final String ADD_COMMAND_SUCCESS = "'s transaction has been successfully added!";
     private final String name;
     private final int amount;
 
+    /**
+     * Constructs an {@code AddCommand} with the specified name and amount.
+     *
+     * @param name   the name of the individual involved in the transaction.
+     * @param amount the amount of the transaction.
+     */
     public AddCommand(String name, int amount) {
         this.name = name;
         this.amount = amount;

src/main/java/balancer/logic/command/CalculateCommand.java

@@ -7,6 +7,11 @@
 import balancer.storage.Transaction;
 import balancer.storage.TransactionComparator;
 
+/**
+ * Represents a {@code CalculateCommand} to generate the minimal list of transactions needed to balance expenses.
+ * Uses a greedy algorithm where every step, at least one giver or receiver will give or receive what they owe or are
+ * owed.
+ */
 public class CalculateCommand extends Command {
     public static final String COMMAND_WORD = "calculate";
 
@@ -24,6 +29,15 @@ public CommandResult execute(Storage storage) {
         return new CommandResult(result);
     }
 
+    /**
+     * Preprocesses the {@code HashMap} that is received from {@code storage}. Calculates the average (baseline) that
+     * everybody should end up spending and transforms the {@code HashMap} into an {@code ArrayList<Transaction>}
+     * of how much participants owe or are owed. It also removes everyone not involved in the final list of transactions
+     * (they already contributed exactly the average).
+     *
+     * @param hashmap Taken straight from the storage. Maps names to {@code Transaction}.
+     * @return        An {@code ArrayList<Transaction>} of the processed {@code HashMap}.
+     */
     private ArrayList<Transaction> preprocess(HashMap<String, Transaction> hashmap) {
         ArrayList<Transaction> current = new ArrayList<>(hashmap.values());
         float total = 0;
@@ -46,6 +60,14 @@ private ArrayList<Transaction> preprocess(HashMap<String, Transaction> hashmap)
         return current;
     }
 
+    /**
+     * The main algorithm that takes in an {@code ArrayList<Transaction>} and generates the minimum number of
+     * transactions needed to balance the payments.
+     *
+     * @param processed The preprocessed {@code ArrayList<Transaction>}.
+     * @return          The String representation of the list of transactions that need to occur in the form of
+     *                  {@code person1 has to pay person2 $X.XX}.
+     */
     private String greedy(ArrayList<Transaction> processed) {
         StringBuilder sb = new StringBuilder();
         TransactionComparator comparator = new TransactionComparator();

src/main/java/balancer/logic/command/Command.java

@@ -4,6 +4,16 @@
 
 import balancer.storage.Storage;
 
+/**
+ * Represents a command to be executed by the application.
+ */
 public abstract class Command {
+    /**
+     * Executes a command and returns a result message or exit encapsulated in {@code CommandResult}.
+     *
+     * @param storage      {@code Storage} which the command should operate on.
+     * @return             Feedback to the user or exit encapsulated by {@code CommandResult}
+     * @throws IOException Some {@code Command} need to save to file and might throw this exception.
+     */
     public abstract CommandResult execute(Storage storage) throws IOException;
 }

src/main/java/balancer/logic/command/CommandResult.java

@@ -1,16 +1,30 @@
 package balancer.logic.command;
 
+/**
+ * Encapsulates the result of executing a command.
+ */
 public class CommandResult {
     private final String feedbackToUser;
 
     /** The application should exit. */
     private final boolean exit;
 
+    /**
+     * Constructs the result of {@code Command} execution.
+     *
+     * @param feedbackToUser A String to be shown to the user.
+     * @param exit           If true, application exits.
+     */
     public CommandResult(String feedbackToUser, boolean exit) {
         this.feedbackToUser = feedbackToUser;
         this.exit = exit;
     }
 
+    /**
+     * This constructor is used for results that are only feedback to user (not {@code ExitCommand}).
+     *
+     * @param feedbackToUser A String to be shown to the user.
+     */
     public CommandResult(String feedbackToUser) {
         this.feedbackToUser = feedbackToUser;
         this.exit = false;

src/main/java/balancer/logic/command/DeleteCommand.java

@@ -4,17 +4,30 @@
 
 import balancer.storage.Storage;
 
+/**
+ * Represents a {@code DeleteCommand} that deletes entries of a person or of every person.
+ */
 public class DeleteCommand extends Command {
     public static final String COMMAND_WORD = "delete";
     public static final String DELETE_COMMAND_SUCCESS = "Delete was successful!";
     private String name;
     private boolean isAll;
 
+    /**
+     * Constructor for deleting a single person from the transaction list.
+     *
+     * @param name Name of person to delete
+     */
     public DeleteCommand(String name) {
         this.name = name;
         this.isAll = false;
     }
 
+    /**
+     * Constructor for deleting every person from the transaction list.
+     *
+     * @param isAll If true, delete every person.
+     */
     public DeleteCommand(boolean isAll) {
         this.name = null;
         this.isAll = isAll;

src/main/java/balancer/logic/command/ExitCommand.java

@@ -2,6 +2,9 @@
 
 import balancer.storage.Storage;
 
+/**
+ * Represents a {@code ExitCommand} to exit the application.
+ */
 public class ExitCommand extends Command {
     public static final String EXIT_COMMAND_SUCCESS = "Your transactions has been saved. Good bye!";
     public static final String COMMAND_WORD = "exit";

src/main/java/balancer/logic/command/ListCommand.java

@@ -6,6 +6,9 @@
 import balancer.storage.Storage;
 import balancer.storage.Transaction;
 
+/**
+ * Represents a {@code ListCommand} to list all the transactions (aggregated) that happened so far.
+ */
 public class ListCommand extends Command {
     public static final String COMMAND_WORD = "list";
     public static final String EMPTY_STRING_REPLY = "List is empty!";
@@ -20,7 +23,7 @@ public CommandResult execute(Storage storage) {
             sb.append("\n");
         }
 
-        String list = sb.isEmpty() ? EMPTY_STRING_REPLY : sb.toString();
+        String list = sb.length() == 0 ? EMPTY_STRING_REPLY : sb.toString();
         return new CommandResult(list);
     }
 }

src/main/java/balancer/logic/parser/AddParser.java

@@ -3,8 +3,10 @@
 import balancer.logic.command.AddCommand;
 import balancer.logic.parser.exceptions.ParserException;
 
+/**
+ * Parses commands starting with "add" and generates a {@code AddCommand}.
+ */
 public class AddParser implements Parser<AddCommand> {
-
     @Override
     public AddCommand parse(String userInput) throws ParserException {
         // Input will be of the form 'Name amount' and should be non-null

src/main/java/balancer/logic/parser/BalancerParser.java

@@ -8,10 +8,20 @@
 import balancer.logic.command.ListCommand;
 import balancer.logic.parser.exceptions.ParserException;
 
+/**
+ * A class that parses inputs of the user and gets the relevant {@code Command}.
+ */
 public class BalancerParser {
     public static final String PARSE_ERROR_MESSAGE =
             "The command you entered is not recognised or of the wrong format.";
 
+    /**
+     * Parses user inputs and produces corresponding {@code Command} or exceptions.
+     *
+     * @param userInput        The user's input.
+     * @return                 A {@code Command}.
+     * @throws ParserException For when a command is of the wrong format or unrecognised.
+     */
     public Command parseCommand(String userInput) throws ParserException {
         String[] split = userInput.split(" ", 2);
         String commandWord = split[0];

src/main/java/balancer/logic/parser/DeleteParser.java

@@ -3,6 +3,9 @@
 import balancer.logic.command.DeleteCommand;
 import balancer.logic.parser.exceptions.ParserException;
 
+/**
+ * Parses commands starting with "delete" and generates a {@code DeleteCommand}.
+ */
 public class DeleteParser implements Parser<DeleteCommand> {
     public static final String WORD_FOR_DELETE_ALL = "all!";
     @Override

src/main/java/balancer/logic/parser/Parser.java

@@ -3,8 +3,12 @@
 import balancer.logic.command.Command;
 import balancer.logic.parser.exceptions.ParserException;
 
+/**
+ * Interface for command parsers.
+ *
+ * @param <T> The type of command returned after parsing the {@code String}.
+ */
 public interface Parser<T extends Command> {
-
     /**
      * Parses {@code userInput} into a command and returns it.
      */

src/main/java/balancer/storage/Storage.java

@@ -9,17 +9,31 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
+/**
+ * Represents the in-memory version of the transaction list.
+ */
 public class Storage {
+    /** The path to the directory of the save file */
     private static Path pathDir;
+    /** The path to the save file */
     private static Path pathFile;
     private HashMap<String, Transaction> transactions = new HashMap<>();
 
+    /**
+     * Constructor for the {@code Storage} that specifies the save locations.
+     */
     public Storage(String dir, String name) {
         String userDir = System.getProperty("user.dir");
         pathDir = Paths.get(userDir + dir);
         pathFile = Paths.get(userDir + dir + name);
     }
 
+    /**
+     * Adds or updates transaction to the {@code HashMap}.
+     *
+     * @param name   Name of the person to add or update.
+     * @param amount The initial or update transaction amount.
+     */
     public void addTransaction(String name, int amount) {
         Transaction current = transactions.get(name);
         if (current == null) {
@@ -46,6 +60,11 @@ public void deleteAll() {
         transactions.clear();
     }
 
+    /**
+     * Saves a copy of the {@code HashMap} to a file.
+     *
+     * @throws IOException
+     */
     public void save() throws IOException {
         assert pathDir != null : "Your directory is missing!";
         // Create directory if it does not exist
@@ -62,10 +81,15 @@ public void save() throws IOException {
         Files.createFile(pathFile);
         // Writing to the file
         List<Transaction> transactionList = new ArrayList<>(transactions.values());
-        List<String> saveString = transactionList.stream().map(Transaction::toString).toList();
+        List<String> saveString = transactionList.stream().map(Transaction::toString).collect(Collectors.toList());
         Files.write(pathFile, saveString);
     }
 
+    /**
+     * Loads {@code HashMap} converted from a file. Used to initialise the application.
+     *
+     * @throws IOException
+     */
     public void load() throws IOException {
         assert pathDir != null : "Your directory is missing!";
         // Create directory if it does not exist