Merge branch 'master' of https://github.com/yeekian/tp into branch-Us…

…erGuide

docs/DeveloperGuide.md

@@ -1,11 +1,29 @@
 # Developer Guide
 
+## Table of Contents
+- [Acknowledgements](#acknowledgements)
+- [Design](#design)
+    - [Architecture](#architecture)
+- [Implementation](#implementation)
+    - [Add/Delete Student/Component Feature](#adddelete-studentcomponent-feature)
+    - [Find Student Feature](#find-student-feature)
+    - [Add/Delete Grade Feature](#adddelete-grade-feature)
+    - [Storage Load Feature](#storage-load-feature)
+- [Appendix A: Product Scope](#appendix-a-product-scope)
+- [Appendix B: User Stories](#appendix-b-user-stories)
+- [Appendix C: Non-Functional Requirements](#appendix-c-non-functional-requirements)
+- [Appendix D: Glossary](#appendix-d-glossary)
+- [Appendix E: Instructions for Manual Testing](#appendix-e-instructions-for-manual-testing)
+
+
+---
+
 ## Acknowledgements
 
-{list here sources of all reused/adapted ideas, code, documentation, and third-party libraries -- include links to the
-original source as well}
+This project was inspired by our experiences using the Canvas learning management system. While Canvas serves large educational environments well, we envisioned a simpler, offline tool tailored for small classes that prioritizes essential features like grade tracking, student management, and assessment organization. Thus, TutorLink was born.
 
-## Design & implementation
+The design and feature set of TutorLink were developed from scratch, drawing inspiration from the need for a lightweight, offline solution for managing class assignments and reducing administrative overhead in small class environments. No code or external sources were directly referenced or reused in the development of TutorLink.
+## Design
 
 ### Architecture
 
@@ -43,14 +61,13 @@ Where <code>ref</code> frame is a placeholder for each command's specific operat
 #### Setup:
 
 During the setup phase of `TutorLink`, the following operations are performed:
-1. `Ui` displays welcome message
-2. `StudentStorage`, `ComponentStorage` and `GradeStorage` objects are instantiated
-3. `ArrayList` of Student, Component and Grade are obtained from the respective Storage classes
-4. `AppState` object is instantiated, passing the `ArrayList`s in step 3
+1. `StudentStorage`, `ComponentStorage` and `GradeStorage` objects are instantiated
+2. `ArrayList` of Student, Component and Grade are obtained from the respective Storage classes
+3. `AppState` object is instantiated, passing the `ArrayList`s in step 3
+4. `Ui` displays welcome message
 
 ![Setup.png](diagrams/Setup.png)
 
-The specific implementation of noteworthy operations are presented below:
 The specific implementation of noteworthy operations are presented below: 
 
 ### Add/Delete Student/Component Feature
@@ -77,7 +94,7 @@ The following sequence diagrams depict the exact steps involved in the `AddStude
 
 - `DeleteStudentCommand.execute(AppState appState, HashMap<String, String> arguments)`: Removes a student via the following
   steps:
-    1. Retrieves and validates the matriculation number from arguments, throwing `IllegaValueException` exception
+    1. Retrieves and validates the matriculation number from arguments, throwing `IllegalValueException` exception
        if matriculation number is null.
     2. Searches for and deletes the student from `AppState`. Throws `StudentNotFoundException` if no student matching the matriculation number
        is found.
@@ -148,24 +165,26 @@ The sequence diagram of the DeleteGradeCommand is shown below.
 The `StudentStorage`, `GradeStorage` and `ComponentStorage` classes implement the feature to load data from the 
 data `.txt` files into their respective List objects at the start of the program.
 
-The load list methods for the Storage classes have largely similar logic flows.  
+The load list methods for the Storage classes have largely similar logic flows. To avoid repetition, 
+only the implementation for `GradeStorage` is shown.
 
-#### Key Operations
-
-The following section and sequence diagram elaborate on the implementation of the `loadGradeList` method in `GradeStorage`:
+The following section and sequence diagram elaborate on the implementation of the `loadGradeList` method in `GradeStorage`,
+as referenced in [Setup](#setup):
 
 ![GradeStorage.png](diagrams/GradeStorage.png)
 
 1. TutorLink constructs a new `GradeStorage`.
-2. TutorLink calls `loadGradeList`.
-3. `GradeStorage` creates a new `ArrayList` of `Grade`s.
-4. `GradeStorage` creates a new `Scanner` with the path to the file.
+2. `GradeStorage` creates a new `ArrayList` of `String`s for discarded entries.
+3. TutorLink calls `loadGradeList`.
+4. `GradeStorage` creates a new `ArrayList` of `Grade`s.
 5. While there are next lines in the data file:
-   - `Scanner` returns the current file line as a String and moves to the next file line.
+   - FileScanner returns the current file line as a String and moves to the next file line.
    - `GradeStorage` calls its `getGradeFromFileLine` method with the file line.
    - If the file line references a valid `Component` and a valid `Student`, a `Grade` is returned and added to the `ArrayList`.
-   - If not (e.g. if data file was corrupted), the file line is simply ignored, and the loop continues to the next iteration.
+   - If not (e.g. file line was corrupted), the file line is added to `discardedEntries`,
+   and the loop continues to the next iteration.
 6. The `ArrayList` of `Grade`s is returned to TutorLink.
+7. TutorLink calls `getDiscardedEntries`, and the discarded entries are displayed by UI.
 
 ## Appendix A: Product Scope
 
@@ -394,18 +413,20 @@ This appendix provides a guide for manually testing various features of TutorLin
 
 ---
 
-### Handling Missing or Corrupted Data Files
+### Handling Missing Files or Corrupted Data
 
 1. **Simulate Missing Data Files**:
     - Delete one or more files from the `data` folder (`studentlist.txt`, `componentlist.txt`, `gradelist.txt`).
     - Re-launch TutorLink.
 
    **Expected**: TutorLink creates new empty files if missing. The application should not crash, and it should operate normally.
 
-2. **Simulate Corrupted Data Files**:
-    - Open any data file and add random text or invalid data structure, then save.
+2. **Simulate Corrupted Data**:
+    - Open any data file and add random text or invalid data entry, then save.
     - Re-launch TutorLink.
 
-   **Expected**: TutorLink should detect the corrupted data, provide an error message or recreate a new empty file if unreadable. The application should not crash.
+   **Expected**: TutorLink should detect the corrupted or invalid data, 
+   display them to the user as entries to be discarded, and only load valid data entries.
+   The application should not crash.
 
----
+---

docs/UserGuide.md

@@ -7,15 +7,30 @@
 ## Quick Start
 
 1. Ensure you have Java 17 or above installed in your Computer.
-2. Download the latest .jar file  of `TutorLink` from [here](http://link.to/duke).
+2. Download the latest .jar file  of `TutorLink` from [here](https://github.com/AY2425S1-CS2113-W13-4/tp/releases/tag/v2.1).
 3. Copy the file to the folder you want to use as the home folder for your TutorLink.
 4. Open a command terminal, cd into the folder you put the jar file in, and use the java -jar TutorLink.jar command to run the application.
 
 Your command terminal should look similar to the one below.
 
 ![tutorlink_startup.png](tutorlink_startup.png)
+
+## Important Notes on Commands:
+When inputting commands into `TutorLink`, kindly take note of the following:
+- Commands with duplicate parameters will be rejected. *i.e* `add_student n/John Doe n/John Doe i/A1234567X`
+- Parameters must be separated by at least one space character, otherwise the entire continuous string following a prefix
+will be considered a single parameter. *i.e* `add_student i/A1234567X n/John Doei/A1234567X` will be intepreted as adding
+a student with the name of `John Doei/A1234567X` and matric number `A1234567X`.
+- Parameters can be supplied in any order. *i.e* `add_student n/John i/A1234567X` is the same as `add_student i/A1234567X n/John`
+- **IMPORTANT**: Descriptions should **NOT** contain any separator tokens: `|` as this character is used for storage). 
+Including these may yield unpredictable results with the `Storage` component. 
+- Matric Number (`i/` argument) is case insensitive. Therefore, `A1234567X` is the same as `a1234567x`. Matric numbers 
+will be converted to uppercase for storage.
+- Similarly, all other will be converted to lowercase for storage.
 ## Features 
 
+<div style="page-break-after: always;"></div>
+
 ### Adding a Student: `add_student`
 
 Adds a student to your class.
@@ -53,6 +68,8 @@ Displays a list of all students in the class.
 
 ---
 
+<div style="page-break-after: always;"></div>
+
 ### Finding a Student: `find_student`
 
 Adds a student to your class.
@@ -94,6 +111,8 @@ Removes an existing grading component from the class.
 
 ---
 
+<div style="page-break-after: always;"></div>
+
 ### Listing Components: `list_component`
 
 Displays all grading components and their respective weights for a class.
@@ -115,7 +134,7 @@ Records a grade for a specific student in a particular assignment or exam compon
   - `SCORE`: The score to be recorded. Note that score cannot exceed the max score of the component.
 
 - **Example**:
-  - `add_grade i/A1234567X c/Quiz 1 s/85` adds the grade of Quiz 1 for the student with the matric number of A1234567X with a score of 85.
+  - `add_grade i/A1234567X c/Quiz 1 s/45` adds the grade of Quiz 1 for the student with the matric number of A1234567X with a score of 45.
 
 ---
 
@@ -133,6 +152,8 @@ Removes a previously recorded grade for a specific student and component.
 
 ---
 
+<div style="page-break-after: always;"></div>
+
 ### Listing Grades: `list_grade`
 
 Views all recorded grades for a specific student or all students, and final percentage calculation. If the weightage of components does not add up to 100% (i.e., the course is still in progress), "IP" (In Progress) will be shown instead of a final percentage.
@@ -168,30 +189,40 @@ The data from the student, component and grade lists are stored in `studentlist.
 respectively, located in the `[JAR file location]/data/` directory.
 
 ---
-## Notes:
-- Matric Number (`i/` argument) is case insensitive. Therefore, `A1234567X` is the same as `a1234567x`. Matric numbers 
-will be converted to uppercase for storage. 
-- (coming soon) All other arguments are case insensitive and will be converted to lowercase for storage. 
+
+<div style="page-break-after: always;"></div>
+
 ## FAQ
 
 **Q**: How do I transfer my data to another computer?
 
 **A**: To transfer data, simply copy the `TutorLink` home folder (where the `.jar` file and data files are located) to your new computer. Then, download Java 17 (if not already installed), place the `.jar` file in the copied folder, and run `java -jar TutorLink.jar` from that folder.
 
+**Q**: Can I update data by directly editing the data files?
+
+**A**: Do so at your own risk. If changes to the data file alter its format, invalid file lines will discarded 
+during startup, and displayed in the command line for verification. While TutorLink can detect most invalid file entries, 
+certain edits can cause unexpected behaviour. Therefore, it is not recommended to edit the data files
+unless you are confident you can do so correctly.
+
 ---
 
+<div style="page-break-after: always;"></div>
+
 ## Command Summary
 
 | **Command**        | **Description**                                              | **Example**                           |
 |--------------------|--------------------------------------------------------------|---------------------------------------|
+| `help`             | Displays list of commands                                    | `help`                                |
 | `add_student`      | Adds a student to the class roster                           | `add_student i/A1234567X n/John Doe`  |
 | `delete_student`   | Deletes a student from the class roster                      | `delete_student i/A1234567X`          |
 | `list_student`     | Lists all students in the class                              | `list_student`                        |
 | `find_student`     | Finds a student in the class roster by name or matric number | `find_student i/A1234567X n/John Doe` |
 | `add_component`    | Adds a new grading component to the class                    | `add_component c/Quiz 1 w/30 m/50`    |
 | `delete_component` | Deletes a grading component from the class                   | `delete_component c/Quiz 1`           |
+| `update_component` | Updates a component with a new maxscore or weight            | `update_component c/Quiz 1 w/40 m/60` |
 | `list_component`   | Lists all grading components                                 | `list_component`                      |
-| `add_grade`        | Adds a grade for a student for a specific component          | `add_grade i/A1234567X c/Quiz 1 s/85` |
+| `add_grade`        | Adds a grade for a student for a specific component          | `add_grade i/A1234567X c/Quiz 1 s/45` |
 | `delete_grade`     | Deletes a student's grade for a specific component           | `delete_grade i/A1234567X c/Quiz 1`   |
 | `list_grade`       | Lists all grades for a student                               | `list_grade i/A1234567X`              |
 | `bye`              | Exits the program                                            | `bye`                                 |

docs/diagrams/AddComponentCommand.puml

@@ -19,6 +19,8 @@ C -> H : get("m/")
 activate H
 C <-- H : maxScoreNumber
 deactivate H
+destroy H
+
 
 opt componentName or weightageNumber or maxScoreNumber is null
 [<-- C : throw IllegalValueException
@@ -47,4 +49,6 @@ deactivate R
 
 [<-- C : CommandResult
 end
+destroy R
+destroy C
 @enduml

docs/diagrams/AddGradeCommand.puml

@@ -55,6 +55,7 @@ deactivate R
 deactivate C
 
 end
-
+destroy R
+destroy C
 
 @enduml

docs/diagrams/AddStudentCommand.puml

@@ -21,4 +21,6 @@ deactivate R
 [<-- C : CommandResult
 deactivate C
 end
+destroy R
+destroy C
 @enduml

docs/diagrams/ArchitectureSequenceGrouped.puml

@@ -1 +1 @@
-@startuml!include Style.pumlparticipant ":TutorLink" as TL LOGIC_COLOR_5participant ":Ui" as UI LOGIC_COLOR_6participant ":Parser" as P LOGIC_COLOR_7participant ":XYZCommand" as C LOGIC_COLOR_3participant ":AppState" as A LOGIC_COLOR_2participant ":XYZStorage" as S LOGIC_COLOR_4[->TLactivate TLref over TL, UI : setuploop until exit command issued    TL -> UI: getUserInput()    activate UI    TL <-- UI: line    deactivate UI    TL -> P : getCommand(line)    activate P    create C    P -> C    activate C    P <-- C : XYZCommand    deactivate C    TL <-- P: XYZCommand    deactivate P    TL -> C : getArgumentPrefixes()    activate C    TL <-- C : argumentPrefixes    deactivate C    TL -> P: getArguments(argumentPrefixes, line)    activate P    TL <-- P : HashMap<String,String>    deactivate P    TL -> C : execute(appState, arguments)    activate C    ref over C, A : specific command execution    alt command execution success        TL <-- C : CommandResult        deactivate C        TL -> UI : displayResult()        activate UI        TL <-- UI        deactivate UI    else TutorLinkException        TL -> UI : displayException(exception)        activate UI        TL <-- UI        deactivate UI    end    TL -> TL : saveAllLists()    activate TL    TL -> S : save Student, Component and Grade Lists    activate S    TL <-- S    deactivate S    TL --> TL    deactivate TLendTL->UI: displayGoodbyeMessage()activate UITL <-- UIdeactivate UI[<--TLdeactivate TL@enduml
+@startuml!include Style.pumlparticipant ":TutorLink" as TL LOGIC_COLOR_5participant ":Ui" as UI LOGIC_COLOR_6participant ":Parser" as P LOGIC_COLOR_7participant ":XYZCommand" as C LOGIC_COLOR_3participant ":AppState" as A LOGIC_COLOR_2participant ":XYZStorage" as S LOGIC_COLOR_4[->TLactivate TLref over TL, UI : setuploop until exit command issued    TL -> UI: getUserInput()    activate UI    TL <-- UI: line    deactivate UI    TL -> P : getCommand(line)    activate P    create C    P -> C    activate C    P <-- C : XYZCommand    deactivate C    TL <-- P: XYZCommand    deactivate P    TL -> C : getArgumentPrefixes()    activate C    TL <-- C : argumentPrefixes    deactivate C    TL -> P: getArguments(argumentPrefixes, line)    activate P    TL <-- P : HashMap<String,String>    deactivate P    TL -> C : execute(appState, arguments)    activate C    ref over C, A : specific command execution    alt command execution success        TL <-- C : CommandResult        deactivate C        destroy C        TL -> UI : displayResult()        activate UI        TL <-- UI        deactivate UI    else TutorLinkException        TL -> UI : displayException(exception)        activate UI        TL <-- UI        deactivate UI    end    TL -> TL : saveAllLists()    activate TL    TL -> S : save Student, Component and Grade Lists    activate S    TL <-- S    deactivate S    TL --> TL    deactivate TLendTL->UI: displayGoodbyeMessage()activate UITL <-- UIdeactivate UI[<--TLdeactivate TL@enduml

docs/diagrams/DeleteComponentCommand.puml

@@ -13,6 +13,7 @@ C -> H : get("n/")
 activate H
 C <-- H : componentName
 deactivate H
+destroy H
 
 opt componentName is null
     [<-- C : throw IllegalValueException
@@ -43,4 +44,7 @@ deactivate R
 
 [<-- C : CommandResult
 end
+destroy R
+destroy C
+
 @enduml

docs/diagrams/DeleteGradeCommand.puml

@@ -39,6 +39,7 @@ deactivate R
 deactivate C
 
 end
-
+destroy R
+destroy C
 
 @enduml

docs/diagrams/DeleteStudentCommand.puml

@@ -30,4 +30,6 @@ deactivate R
 [<-- C : CommandResult
 deactivate C
 end
+destroy R
+destroy C
 @enduml

docs/diagrams/FindStudentCommand.puml

@@ -30,4 +30,6 @@ deactivate R
 [<-- C : CommandResult
 deactivate C
 end
+destroy R
+destroy C
 @enduml

docs/diagrams/GradeStorage.puml

@@ -2,13 +2,22 @@
 
 !include Style.puml
 participant ":TutorLink" as TL LOGIC_COLOR_5
+participant ":Ui" as UI LOGIC_COLOR_6
+
 participant "gradeStorage: GradeStorage" as GS LOGIC_COLOR_4
-participant "grades: ArrayList<Grade>" as AL LOGIC_COLOR_6
-[->TL : setupAllLists()
-activate TL
+participant "grades: ArrayList<Grade>" as AL LOGIC_COLOR_3
+participant "discardedEntries: ArrayList<String>" as DE LOGIC_COLOR_7
+
+group sd load grade data
+
 create GS
-TL -> GS: new GradeStorage(GRADE_FILE_PATH, initialComponentList, initialStudentList)
+TL -> GS: new GradeStorage(filepath, components, students)
 activate GS
+create DE
+GS -> DE: new ArrayList<String>()
+activate DE
+GS <-- DE: discardedEntries: String
+deactivate DE
 TL <-- GS: gradeStorage: GradeStorage
 deactivate GS
 
@@ -21,9 +30,7 @@ activate AL
 GS <-- AL: grades: Grade
 deactivate AL
 
-
-
-loop fileScanner.hasNext()
+loop file has next line
     GS -> GS: getGradeFromFileLine(currentLine: String)
     activate GS
     GS --> GS: newGrade: Grade
@@ -35,14 +42,27 @@ loop fileScanner.hasNext()
         GS <-- AL
         deactivate AL
     else InvalidDataFileLineException
+        GS -> DE: add(currentLine: String)
+        activate DE
+        GS <-- DE
+        deactivate DE
     end
 
 end
 
-
 TL <-- GS: grades: Grade
 deactivate GS
-[<--TL
-deactivate TL
+
+TL -> GS: getDiscardedEntries()
+activate GS
+TL <-- GS: discardedGrades: String
+deactivate GS
+
+TL -> UI: displayDiscardedEntries(discardedGrades)
+activate UI
+TL <-- UI
+deactivate UI
+
+end
 
 @enduml