Merge pull request #233 from RCPilot1604/branch-more-javadoc

Branch more javadoc

src/main/java/tutorlink/command/AddStudentCommand.java

@@ -2,26 +2,45 @@
 
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.List;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 
 import tutorlink.appstate.AppState;
 import tutorlink.commons.Commons;
 import tutorlink.exceptions.IllegalValueException;
 import tutorlink.exceptions.TutorLinkException;
 import tutorlink.result.CommandResult;
 
-import java.util.List;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-
+/**
+ * Command to add a student to the system. It requires the student's matriculation number and name.
+ * The matriculation number is validated using a regular expression.
+ */
 public class AddStudentCommand extends Command {
 
+    // Prefixes for the arguments (matriculation number and name)
     public static final String[] ARGUMENT_PREFIXES = {"i/", "n/"};
+
+    // Command word to identify the add_student command
     public static final String COMMAND_WORD = "add_student";
 
+    /**
+     * Executes the add student command. It validates the matriculation number and adds the student
+     * to the system if valid. If the matriculation number or name is missing, an exception is thrown.
+     *
+     * @param appState The current state of the application which holds all data.
+     * @param hashmap A map containing arguments passed to the command (expected to have matriculation number and name).
+     * @return The result of the command execution, including a success message.
+     * @throws TutorLinkException If there is an error with the matriculation number or if required parameters are
+     *                missing.
+     */
     @Override
     public CommandResult execute(AppState appState, HashMap<String, String> hashmap) throws TutorLinkException {
+        // Retrieve the matriculation number and name from the hashmap
         String matricNumber = hashmap.get(ARGUMENT_PREFIXES[0]);
         String name = hashmap.get(ARGUMENT_PREFIXES[1]);
+
+        // Ensure both matric number and name are provided
         if (matricNumber == null || name == null) {
             List<String> nullParameters = new ArrayList<>();
             if (matricNumber == null) {
@@ -30,18 +49,29 @@ public CommandResult execute(AppState appState, HashMap<String, String> hashmap)
             if (name == null) {
                 nullParameters.add(ARGUMENT_PREFIXES[1]);
             }
-            throw new IllegalValueException(String.format(Commons.ERROR_NULL,
-                    String.join(", ", nullParameters)));
+            throw new IllegalValueException(String.format(Commons.ERROR_NULL, String.join(", ", nullParameters)));
         }
+
+        // Validate the matriculation number using a regular expression
         Pattern pattern = Pattern.compile(Commons.MATRIC_NUMBER_REGEX);
         Matcher matcher = pattern.matcher(matricNumber);
         if (!matcher.find()) {
             throw new IllegalValueException(Commons.ERROR_ILLEGAL_MATRIC_NUMBER);
         }
+
+        // Add the student to the system
         appState.students.addStudent(matricNumber, name);
+
+        // Return a success message
         return new CommandResult(String.format(Commons.ADD_STUDENT_SUCCESS, name, matricNumber));
     }
 
+    /**
+     * Returns the prefixes for the arguments expected by this command.
+     * In this case, the prefixes are "i/" for the matriculation number and "n/" for the name.
+     *
+     * @return The array of argument prefixes.
+     */
     @Override
     public String[] getArgumentPrefixes() {
         return ARGUMENT_PREFIXES;

src/main/java/tutorlink/command/DeleteComponentCommand.java

@@ -9,26 +9,61 @@
 import tutorlink.lists.ComponentList;
 import tutorlink.result.CommandResult;
 
-public class DeleteComponentCommand extends Command{
+/**
+ * Command to delete a component from the system. It will delete the component from the component list
+ * and remove associated grades. It also updates the percentage scores of all students.
+ */
+public class DeleteComponentCommand extends Command {
+
+    // Prefix for the argument (component name)
     public static final String[] ARGUMENT_PREFIXES = {"c/"};
+
+    // Command keyword to identify the delete_component command
     public static final String COMMAND_WORD = "delete_component";
 
+    /**
+     * Executes the delete component command. Deletes the component from the system's list and
+     * removes all associated grades.
+     *
+     * @param appState The current state of the application which holds all data.
+     * @param hashmap A map containing arguments passed to the command (expected to have the component name with
+     *                prefix "c/").
+     * @return The result of the command execution, including success message.
+     * @throws TutorLinkException If the component name is invalid or not found.
+     */
     @Override
     public CommandResult execute(AppState appState, HashMap<String, String> hashmap) throws TutorLinkException {
+        // Retrieve the component name from the hashmap
         String componentName = hashmap.get(ARGUMENT_PREFIXES[0]);
-        if(componentName == null) {
-            throw new IllegalValueException(String.format(Commons.ERROR_NULL,ARGUMENT_PREFIXES[0]));
+
+        // Ensure the component name is provided
+        if (componentName == null) {
+            throw new IllegalValueException(String.format(Commons.ERROR_NULL, ARGUMENT_PREFIXES[0]));
         }
+
+        // Search for the component in the list
         ComponentList componentsToDelete = appState.components.findComponent(componentName);
-        if(componentsToDelete.size() == 0) {
+
+        // If no component is found, throw an exception
+        if (componentsToDelete.size() == 0) {
             throw new ComponentNotFoundException(String.format(Commons.ERROR_COMPONENT_NOT_FOUND, componentName));
         }
+
+        // Delete the component and its associated grades, then update student scores
         appState.components.deleteComponent(componentsToDelete.getComponentArrayList().get(0));
         appState.grades.deleteGradesByComponent(componentName);
         appState.updateAllStudentPercentageScores();
+
+        // Return a success message
         return new CommandResult(String.format(Commons.DELETE_COMPONENT_SUCCESS, componentName));
     }
 
+    /**
+     * Returns the prefixes for the arguments expected by this command.
+     * In this case, the prefix is "c/" for the component name.
+     *
+     * @return The array of argument prefixes.
+     */
     @Override
     public String[] getArgumentPrefixes() {
         return ARGUMENT_PREFIXES;

src/main/java/tutorlink/command/DeleteStudentCommand.java

@@ -10,27 +10,58 @@
 import tutorlink.exceptions.TutorLinkException;
 import tutorlink.result.CommandResult;
 
+/**
+ * Command to delete a student from the system. It requires the student's matriculation number,
+ * validates the matriculation number format, and deletes the student and their associated grades.
+ */
 public class DeleteStudentCommand extends Command {
 
+    // Prefix for the argument (matriculation number)
     public static final String[] ARGUMENT_PREFIXES = {"i/"};
+
+    // Command word to identify the delete_student command
     public static final String COMMAND_WORD = "delete_student";
 
+    /**
+     * Executes the delete student command. It validates the matriculation number format,
+     * deletes the student from the system and removes their associated grades.
+     *
+     * @param appState The current state of the application which holds all data.
+     * @param hashmap A map containing arguments passed to the command (expected to have the matriculation number).
+     * @return The result of the command execution, including a success message.
+     * @throws TutorLinkException If the matriculation number is invalid or not found.
+     */
     @Override
     public CommandResult execute(AppState appState, HashMap<String, String> hashmap) throws TutorLinkException {
+        // Retrieve the matriculation number from the hashmap
         String matricNumber = hashmap.get(ARGUMENT_PREFIXES[0]);
+
+        // Ensure matriculation number is provided
         if (matricNumber == null) {
             throw new IllegalValueException(String.format(Commons.ERROR_NULL, ARGUMENT_PREFIXES[0]));
         }
+
+        // Validate the matriculation number using a regular expression
         Pattern pattern = Pattern.compile(Commons.MATRIC_NUMBER_REGEX);
         Matcher matcher = pattern.matcher(matricNumber);
         if (!matcher.find()) {
             throw new IllegalValueException(Commons.ERROR_ILLEGAL_MATRIC_NUMBER);
         }
+
+        // Delete the student and their associated grades
         appState.students.deleteStudent(matricNumber);
         appState.grades.deleteGradesByMatric(matricNumber);
+
+        // Return a success message
         return new CommandResult(String.format(Commons.DELETE_STUDENT_SUCCESS, matricNumber));
     }
 
+    /**
+     * Returns the prefixes for the arguments expected by this command.
+     * In this case, the prefix is "i/" for the matriculation number.
+     *
+     * @return The array of argument prefixes.
+     */
     @Override
     public String[] getArgumentPrefixes() {
         return ARGUMENT_PREFIXES;

src/main/java/tutorlink/command/FindStudentCommand.java

@@ -9,28 +9,59 @@
 import tutorlink.result.CommandResult;
 import tutorlink.appstate.AppState;
 
+/**
+ * Command to find a student by either their matriculation number or their name.
+ * The command can search for a student by matriculation number or by name, but not both.
+ * If neither is provided, an exception is thrown.
+ */
 public class FindStudentCommand extends Command {
 
+    // Prefixes for the arguments (matriculation number and name)
     public static final String[] ARGUMENT_PREFIXES = {"i/", "n/"};
+
+    // Command word to identify the find_student command
     public static final String COMMAND_WORD = "find_student";
 
+    /**
+     * Executes the find student command. It searches for a student by their matriculation number
+     * or by their name, depending on which argument is provided.
+     *
+     * @param appstate The current state of the application which holds all data.
+     * @param hashmap A map containing arguments passed to the command (either matriculation number or name).
+     * @return The result of the command execution, which includes a string representation of the student(s).
+     * @throws TutorLinkException If neither a matriculation number nor a name is provided,
+     *          or if an invalid search is made.
+     */
     @Override
     public CommandResult execute(AppState appstate, HashMap<String, String> hashmap) throws TutorLinkException {
+        // Retrieve the matriculation number and name from the hashmap
         String matricNumber = hashmap.get(ARGUMENT_PREFIXES[0]);
         String name = hashmap.get(ARGUMENT_PREFIXES[1]);
         StudentList students;
+
+        // Ensure at least one argument (matriculation number or name) is provided
         if (name == null && matricNumber == null) {
             throw new IllegalValueException(Commons.ERROR_STUDENT_BOTH_NULL);
         }
+
+        // If a matriculation number is provided, search by matriculation number
         if (hashmap.containsKey(ARGUMENT_PREFIXES[0])) {
             students = appstate.students.findStudentByMatricNumber(matricNumber);
-            assert students.getStudentArrayList().size() <= 1; //there should only be 1 unique matric number
+            assert students.getStudentArrayList().size() <= 1;
         } else {
             students = appstate.students.findStudentByName(name);
         }
+
+        // Return the result as a string representation of the found student(s)
         return new CommandResult(students.toString());
     }
 
+    /**
+     * Returns the prefixes for the arguments expected by this command.
+     * In this case, the prefixes are "i/" for the matriculation number and "n/" for the name.
+     *
+     * @return The array of argument prefixes.
+     */
     @Override
     public String[] getArgumentPrefixes() {
         return ARGUMENT_PREFIXES;