From 93ad52b623ebd7c6f5ff834f3e53795e0436393c Mon Sep 17 00:00:00 2001 From: keithxun Date: Tue, 12 Nov 2024 00:04:21 +0800 Subject: [PATCH] Fix table --- docs/DeveloperGuide.md | 175 +++++++++++++++++++++-------------------- 1 file changed, 90 insertions(+), 85 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index a93eec40a3b..bbb47c25fa4 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -5,7 +5,6 @@ pageNav: 3 --- --> - # HallPointer Developer Guide @@ -71,8 +70,6 @@ While the `Storage` component provides an abstraction layer for persistent data, Ideally, the `Storage` interface would fully abstract storage details by exposing methods like `getHallPointerData()` or `getUserPreferences()`, thus hiding specifics like `ReadOnlyHallPointer`. However, for simplicity and to meet the application’s needs, `Storage` directly returns these specific data structures. - - The sections below give more details about each component. ### UI component @@ -139,7 +136,7 @@ The `Model` component has the following responsibilites: - Storing the HallPointer data (i.e. any `Member` and `Session` objects) in memory for easy access. - Storing the currently 'selected' `Member` objects (e.g. the results of a search query) in a separate _filtered_ list, one which is exposed to outsiders as an unmodifiable `ObservableList` that can be 'observed'. This allows the UI to observe the list and automatically update when the data in the list changes. -- Storing a `UserPref` object that represents the user’s preferences, and exposing to the outside as a `ReadOnlyUserPref` object. +- Storing a `UserPref` object that represents the user’s preferences, and exposing to the outside as a `ReadOnlyUserPref` object. It does not depend on any of the other three components, as the `Model` represents data entities of the application and domain, and thus should make sense on its own without depending on other components. @@ -154,6 +151,7 @@ Here is a partial and representative class diagram of the `Storage` component: The `Storage` component has the responsibility of saving HallPointer data and user preferences data to disk in JSON format, and then parsing them back into the corresponding objects when the application is re-opened. It inherits from both `Storage` and `UserPrefStorage`, which means it can be treated as either one (if only the functionality of only one is needed). + - depends on some classes in the `Model` component (because the `Storage` component's job is to save/retrieve objects that belong to the `Model`) ### Common classes @@ -162,7 +160,6 @@ Classes used by multiple components are in the `hallpointer.address.commons` pac --- - ## **Documentation, logging, testing, configuration, dev-ops** - [Documentation guide](Documentation.md) @@ -192,7 +189,7 @@ Classes used by multiple components are in the `hallpointer.address.commons` pac Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unlikely to have) - `*` | Priority | As a …​ | I want to …​ | So that I can …​ | Remarks/Notes | -|----------|-----------------|------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|--------------------------------------------------------| +| -------- | --------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | `* * *` | First-time user | Explore the application using sample data | I can understand its features without manually entering data | | | `* * *` | First-time user | See a guide on how to use the application | I can better understand its functionalities | | | `* * *` | First-time user | Save the changes I made | I won’t have to redo my work after reopening the application | | @@ -211,10 +208,9 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli | `*` | User | View analytics or visual reports of attendance and participation | I can see trends and member engagement at a glance | Through charts or graphs to visualize data | | `*` | User | Sort members by name | I can locate a member easily | | | `*` | Frequent user | Automatically save changes as changes are made | I don’t lose progress if I forget to click save | Auto-save feature | -| `*` | Expert user | Perform all actions using the CLI | I can interact with the application more efficiently than with just a GUI | | - | -| `*` | User | Add notes for each member | I can track special situations or reasons for absences | | -| `*` | First-time user | Import data from an existing Google Sheets document or csv file | I can quickly upload my data without manual entry | | +| `*` | Expert user | Perform all actions using the CLI | I can interact with the application more efficiently than with just a GUI | Command Line Interface (CLI) | +| `*` | User | Add notes for each member | I can track special situations or reasons for absences | Member notes feature | +| `*` | First-time user | Import data from an existing Google Sheets document or CSV file | I can quickly upload my data without manual entry | Data import feature | ### Use cases @@ -227,28 +223,30 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli **Description**: This use case allows a CCA leader to add a new member to the CCA for attendance tracking and point allocation. **Preconditions**: + 1. The CCA Leader must know the details of the new member. **Main Success Scenario (MSS)**: + 1. CCA Leader inputs the `add_member` command with required details (name, room number, telegram and tags (optional)). - - Example: `add_member n/John Doe r/4-3-301 t/johndoe123 tag/logistics` + - Example: `add_member n/John Doe r/4-3-301 t/johndoe123 tag/logistics` 2. Hall Pointer validates the entered details for the new member. 3. Hall Pointer adds the member to the system and displays a success message. 4. The new member is displayed in the GUI. - - Use case ends. + - Use case ends. **Extensions**: - **2a. Hall Pointer detects an error in the entered data**. - - 2a1. Hall Pointer displays an error message with relevant details. - - 2a2. CCA Leader re-enters corrected data. - - Steps 2a1-2a2 are repeated until the input is valid. - - Use case resumes from step 3. -- **2b. The member to be added is already present in the system**. - - 2b1. Hall Pointer displays an error message: `This member already exists in the CCA system.` - - Use case ends. + - 2a1. Hall Pointer displays an error message with relevant details. + - 2a2. CCA Leader re-enters corrected data. + - Steps 2a1-2a2 are repeated until the input is valid. + - Use case resumes from step 3. +- **2b. The member to be added is already present in the system**. + - 2b1. Hall Pointer displays an error message: `This member already exists in the CCA system.` + - Use case ends. --- @@ -261,31 +259,33 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli **Description**: This use case allows a CCA leader to add a new CCA session to the system for tracking attendance and point allocation. **Preconditions**: + 1. The CCA Leader must know the details of the session such as name, date, points and associated members. **Main Success Scenario (MSS)**: + 1. CCA Leader inputs the `add_session` command with session details (session_name, date, and points, member_index). - - Example: `add_session s/Rehearsal d/24 Oct 2024 p/2 m/1` + - Example: `add_session s/Rehearsal d/24 Oct 2024 p/2 m/1` 2. Hall Pointer validates the entered session details. 3. Hall Pointer adds the session to the associated members and displays a success message. 4. The new session is displayed in the GUI. - - Use case ends. + - Use case ends. **Extensions**: - **2a. Hall Pointer detects an error in the entered data**. - - 2a1. Hall Pointer displays an error message with relevant details. - - 2a2. CCA Leader re-enters corrected data. - - Steps 2a1-2a2 are repeated until all data is correct. - - Use case resumes from step 3. + + - 2a1. Hall Pointer displays an error message with relevant details. + - 2a2. CCA Leader re-enters corrected data. + - Steps 2a1-2a2 are repeated until all data is correct. + - Use case resumes from step 3. - **2b. The session to be added is already present in at least one of the relevant members**. - - 2b1. Hall Pointer displays an error message: `Error: Session already exists.` - - Use case ends. + - 2b1. Hall Pointer displays an error message: `Error: Session already exists.` + - Use case ends. --- - #### Use Case: UC03 - Update Member Information **System**: Hall Pointer Application @@ -295,23 +295,25 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli **Description**: This use case allows a CCA leader to update the details of an existing member, such as room number, telegram, or tags. **Preconditions**: + 1. The member to be updated must exist in the system. **Main Success Scenario (MSS)**: + 1. CCA Leader inputs the `update_member` command with the member index and new details. - - Example: `update_member 1 n/John Doe r/9/10/203 t/johnDoe123 tag/friend` + - Example: `update_member 1 n/John Doe r/9/10/203 t/johnDoe123 tag/friend` 2. Hall Pointer validates the member and new details. 3. Hall Pointer updates the member information and displays a success message. - - `Member John Doe; Telegram: johnDoe123; Room: 9/10/203; Tags: [friend]'s details updated successfully.` + - `Member John Doe; Telegram: johnDoe123; Room: 9/10/203; Tags: [friend]'s details updated successfully.` 4. The updated member information is displayed in the GUI. - - Use case ends. + - Use case ends. **Extensions**: - **2a. Member index is invalid**. - - 2a1. Hall Pointer displays an error message: - - `Error: Invalid index specified.` - - Use case ends. + - 2a1. Hall Pointer displays an error message: + - `Error: Invalid index specified.` + - Use case ends. --- @@ -327,9 +329,10 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli None. **Main Success Scenario (MSS)**: + 1. CCA Leader inputs the `list` command. 2. Hall Pointer retrieves and displays all members in the GUI. - - Use case ends. + - Use case ends. ### Non-Functional Requirements @@ -343,7 +346,6 @@ None. 8. Code should be organized and documented to facilitate future updates or modifications. 9. The application should run seamlessly across different operating systems without requiring extensive configuration. - ### Glossary ### **HallPointer Developer Glossary** @@ -387,7 +389,6 @@ None. 13. **User Preferences:**\ Settings such as window size and logging levels that can be customized by users and saved in a configuration file (`config.json`) for Hall Pointer. - ## **Appendix: Instructions for manual testing** Given below are instructions to test the application manually. @@ -403,94 +404,91 @@ testers are expected to do more _exploratory_ testing. 1. Initial launch - 1. Download the `.jar` file and copy it into an empty folder. - 2. Open a terminal window and navigate to the directory where the `.jar` file is located. - 3. Execute `java -jar hallpointer.jar`.
- **Expected:** Shows the GUI with a set of sample data. The window size may not be optimal. + 1. Download the `.jar` file and copy it into an empty folder. + 2. Open a terminal window and navigate to the directory where the `.jar` file is located. + 3. Execute `java -jar hallpointer.jar`.
+ **Expected:** Shows the GUI with a set of sample data. The window size may not be optimal. 2. Saving Window Preferences - 1. Resize the window to an optimum size. Move the window to a different location. Close the window. - 2. Re-launch the application by double-clicking the `.jar` file.
- **Expected:** The most recent window size and location is retained. - + 1. Resize the window to an optimum size. Move the window to a different location. Close the window. + 2. Re-launch the application by double-clicking the `.jar` file.
+ **Expected:** The most recent window size and location is retained. ### Managing Members 1. Adding a member - 1. Test case: `add_member n/John Doe r/4-3-301 t/johndoe123 tag/logistics`
- **Expected:** Adds a contact named "John Doe" with specified room number and tags. Details of the added member shown in the status message. + 1. Test case: `add_member n/John Doe r/4-3-301 t/johndoe123 tag/logistics`
+ **Expected:** Adds a contact named "John Doe" with specified room number and tags. Details of the added member shown in the status message. - 2. Test case: `add_member n/John Doe`
- **Expected:** Displays an error message. + 2. Test case: `add_member n/John Doe`
+ **Expected:** Displays an error message. 2. Deleting a member - 1. Prerequisites: List all members using the `list_members` command. Multiple members in the list. + 1. Prerequisites: List all members using the `list_members` command. Multiple members in the list. - 2. Test case: `delete_member 1`
- **Expected:** First contact is deleted from the list. Details of the deleted contact are shown in the status message. + 2. Test case: `delete_member 1`
+ **Expected:** First contact is deleted from the list. Details of the deleted contact are shown in the status message. - 3. Test case: `delete_member 0`
- **Expected:** No member is deleted. Error details shown in the status message. + 3. Test case: `delete_member 0`
+ **Expected:** No member is deleted. Error details shown in the status message. - 4. Other incorrect delete commands to try: `delete_member`, `delete_member x`, `...` (where `x` is larger than the list size).
- **Expected:** Similar to previous. + 4. Other incorrect delete commands to try: `delete_member`, `delete_member x`, `...` (where `x` is larger than the list size).
+ **Expected:** Similar to previous. 3. Updating a member - 1. Test case: `update_member 1 t/johndoe123_updated n/John Doe`
- **Expected:** Updates the telegram handle and name for the member at index 1. - - 2. Test case: `update_member 2 tag/`
- **Expected:** Clears all tags for the member at index 2. + 1. Test case: `update_member 1 t/johndoe123_updated n/John Doe`
+ **Expected:** Updates the telegram handle and name for the member at index 1. + 2. Test case: `update_member 2 tag/`
+ **Expected:** Clears all tags for the member at index 2. ### Managing Sessions 1. Adding a session - 1. Test case: `add_session s/Rehearsal d/24 Oct 2024 p/2 m/1 m/3`
- **Expected:** Adds a session named "Rehearsal" on 24 Oct 2024 worth 2 points, associated with members at indexes 1 and 3 in the displayed list. + 1. Test case: `add_session s/Rehearsal d/24 Oct 2024 p/2 m/1 m/3`
+ **Expected:** Adds a session named "Rehearsal" on 24 Oct 2024 worth 2 points, associated with members at indexes 1 and 3 in the displayed list. 2. Deleting a session - 1. Prerequisites: Ensure a session with the specified name exists for members. - 2. Test case: `delete_session s/Rehearsal m/1 m/3`
- **Expected:** Deletes the session "Rehearsal" for members at indexes 1 and 3 in the displayed list. + 1. Prerequisites: Ensure a session with the specified name exists for members. + 2. Test case: `delete_session s/Rehearsal m/1 m/3`
+ **Expected:** Deletes the session "Rehearsal" for members at indexes 1 and 3 in the displayed list. ### Saving Data 1. Dealing with missing/corrupted data files - 1. Open the hallpointer.json file located in the data directory (this file is created after the application is first launched). Modify it by deleting the name of the first entry. + 1. Open the hallpointer.json file located in the data directory (this file is created after the application is first launched). Modify it by deleting the name of the first entry. - **Expected:** Upon restarting, all data should be cleared, and an empty Hall Pointer should be displayed. + **Expected:** Upon restarting, all data should be cleared, and an empty Hall Pointer should be displayed. 2. Confirming data persistence - 1. Add or modify member/session data. - 2. Exit the application and re-launch it.
- **Expected:** All previous data should be saved and displayed upon restart. + 1. Add or modify member/session data. + 2. Exit the application and re-launch it.
+ **Expected:** All previous data should be saved and displayed upon restart. ### Other Features 1. Clearing all entries - 1. Test case: `clear`
- **Expected:** Deletes all entries from the Hall Pointer. The list should be empty. + 1. Test case: `clear`
+ **Expected:** Deletes all entries from the Hall Pointer. The list should be empty. 2. Exiting the program - 1. Test case: `exit`
- **Expected:** Closes the application. + 1. Test case: `exit`
+ **Expected:** Closes the application. 3. Viewing help - 1. Test case: `help`
- **Expected:** Displays a message explaining how to access the help page. - + 1. Test case: `help`
+ **Expected:** Displays a message explaining how to access the help page. ## **Appendix: Instructions for manual testing** @@ -500,71 +498,78 @@ Team Size: 5 Currently, room identifiers must follow the format `block-floor-room number` (e.g., `10-3-100`), and only numeric values are supported for each component. We plan to enhance this feature by allowing non-numeric values for the `block`,`floor` and `room number`. **Example Requirement**: + > Room identifier should be in the format `block-floor-room`, allowing non-numeric values for `block` and `room number`: + > > - Example: `A-G-101B`, where `A` represents the block, `G` represents the floor, and `101B` represents the room number. This change will add flexibility by supporting alphanumeric characters in the block and room sections. - 2. **Planned Enhancement: Partial Search for Session Names** Currently, users can only search for sessions by entering the exact first word of the session name using the `find_sessions` command. This can be inconvenient for users who want to list all sessions or search using only part of the session name. We can mitigate this by introducing a new command `find_sessions_partial`. **Example Requirement**: + > The `find_sessions_partial` command should allow partial name searches so users can input only the first part of the session name to retrieve all matching sessions. + > > - Example: Searching with the keyword "BAD" would show all sessions starting with "BAD," rather than requiring the exact first word. This enhancement will improve user experience by making session searches more flexible and efficient. - 3. **Planned Enhancement: Flexible Member Search by Additional Fields and Partial Matching** Currently, users can only search for members by their full names, which can be challenging when managing a large number of members. Additionally, searching by room or other important fields, like the Telegram handle, is not supported. **Example Requirement**: + > Expand the `find_members` command to support searching by additional fields, such as `block/floor/room number` and `Telegram handle`. > Allow partial name matching in `find_members` to accommodate long names. + > > - Example: Users should be able to input a part of a member’s name, and the system will display all matching results. These enhancements will improve the usability of the `find_members` command, making it easier to locate members efficiently by various identifiers or by partial names. - 4. **Planned Enhancement: Command Aliases for Improved Usability** The current command names (e.g., `add_session`, `add_member`) are lengthy and require the use of underscores, which can be cumbersome for users to type frequently. **Example Requirement**: + > Introduce shorter command aliases as an alternative to full command names to reduce typing effort, especially for frequent actions. + > > - Example: Instead of typing `add_member`, users could simply type `addm` to execute the same command. This enhancement will streamline user interaction, making the application more efficient and user-friendly, especially for power users. - 5. **Planned Enhancement: `update_session` Command for Session Edits** Currently, session details—including members, session name, date, and points—are fixed upon creation and cannot be modified, which is problematic when adjustments are necessary. The current solution is to delete the session and create a new session with the updated details. **Example Requirement**: + > Add an `update_session` command to allow users to modify session details after creation, such as adding or removing members, correcting session name or date, and adjusting session points if updated later. + > > - Example: Users should be able to add a member who received a medical absence during the original session creation without creating a duplicate. This enhancement will improve flexibility and reduce the need for users to recreate sessions from scratch when updates are required. - 6. **Planned Enhancement: Filter and Sort Members by Tags** The tag feature allows users to categorize members into different teams or groups, but it can become challenging to locate specific groups as the number of members increases. **Example Requirement**: + > Implement a filter and sort feature for tags to help users manage members by groups or teams. + > > - Example: `filter_members_by_tag Team A` would display only members tagged as "Team A," while `sort_members_by_tag` would group all members with similar tags together. By adding these features, users can better manage and view group associations at scale. - 7. **Planned Enhancement: Allow Manual Point Adjustments** Currently, points can only be awarded or adjusted through sessions. This setup can be restrictive for users who need to manage points directly, without creating a session. **Example Requirement**: + > Introduce a command to manually add or adjust points for individual members, allowing flexible point management outside of sessions. + > > - Example: An `add_points` command could let users award or modify points for members directly, without requiring a session link, accommodating various tracking needs. This enhancement would allow users to manage point allocations more flexibly, streamlining adjustments and providing greater control over point tracking. - ---