diff --git a/copyright.txt b/copyright.txt index 93aa2a39ce2..0f9d9dd247b 100644 --- a/copyright.txt +++ b/copyright.txt @@ -1,9 +1,4 @@ Some code adapted from http://code.makery.ch/library/javafx-8-tutorial/ by Marco Jakob Copyright by Susumu Yoshida - http://www.mcdodesign.com/ -- address_book_32.png -- AddressApp.ico - -Copyright by Jan Jan Kovařík - http://glyphicons.com/ -- calendar.png -- edit.png +- address_book_32.png (renamed to hall_pointer_32.png) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index 2430ca7eb60..22b0dccd45b 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -15,8 +15,8 @@ pageNav: 3 ## **Acknowledgements** -Libraries used: [JavaFX](https://openjfx.io/), [Jackson](https://github.com/FasterXML/jackson), [JUnit5](https://github.com/junit-team/junit5) - +Libraries used: [JavaFX](https://openjfx.io/), [Jackson](https://github.com/FasterXML/jackson), [JUnit5](https://github.com/junit-team/junit5).\ +This project is based on the AddressBook-Level3 project created by the [SE-EDU initiative](https://se-education.org). --- @@ -32,74 +32,75 @@ Refer to the guide [_Setting up and getting started_](SettingUp.md). -The **_Architecture Diagram_** given above explains the high-level design of the App. +The **_Architecture Diagram_** given above explains the high-level design of the application. -Given below is a quick overview of main components and how they interact with each other. +Given below is a quick overview of the main components of the application and how they interact with each other. **Main components of the architecture** -**`Main`** (consisting of classes [`Main`](https://github.com/AY2425S1-CS2103T-W14-3/tp/blob/master/src/main/java/hallpointer/address/Main.java) and [`MainApp`](https://github.com/AY2425S1-CS2103T-W14-3/tp/blob/master/src/main/java/hallpointer/address/MainApp.java)) is in charge of the app launch and shut down. +**`Main`** (consisting of classes [`Main`](https://github.com/AY2425S1-CS2103T-W14-3/tp/blob/master/src/main/java/hallpointer/address/Main.java) and [`MainApp`](https://github.com/AY2425S1-CS2103T-W14-3/tp/blob/master/src/main/java/hallpointer/address/MainApp.java)) is in charge of the application launch and shut down. -- At app launch, it initializes the other components in the correct sequence, and connects them up with each other. +- At application launch, it initializes the other components in the correct sequence, and connects them up with each other. - At shut down, it shuts down the other components and invokes cleanup methods where necessary. -The bulk of the app's work is done by the following four components: +[**`Commons`**](#common-classes) represents a collection of classes used by multiple other components. -- [**`UI`**](#ui-component): The UI of the App. -- [**`Logic`**](#logic-component): The command executor. -- [**`Model`**](#model-component): Holds the data of the App in memory. -- [**`Storage`**](#storage-component): Reads data from, and writes data to, the hard disk. +The bulk of the application's work is done by the following four components: -[**`Commons`**](#common-classes) represents a collection of classes used by multiple other components. +- [**`UI`**](#ui-component): The user interface of the app. +- [**`Logic`**](#logic-component): Handles parsing and executing the commands received through user input. +- [**`Model`**](#model-component): Holds the data of the application in memory. +- [**`Storage`**](#storage-component): Reads data from, and writes data to the hard disk. **How the architecture components interact with each other** -The _Sequence Diagram_ below shows how the components interact with each other for the scenario where the user issues the command `delete_member 1`. +The _Sequence Diagram_ below shows how the components interact with each other when the user issues the command `delete_member 1`. -Each of the four main components (also shown in the diagram above), +Each of the four main components (also shown in the diagram above) has these properties: -- defines its _API_ in an `interface` with the same name as the Component. -- implements its functionality using a concrete `{Component Name}Manager` class (which follows the corresponding API `interface` mentioned in the previous point. +- It defines its _API_ (Application Programming Interface) in an `interface` with the same name as the Component. +- It implements its functionality using a concrete `{Component Name}Manager` class (which follows the corresponding API `interface` mentioned above). -For example, the `Logic` component defines its API in the `Logic.java` interface and implements its functionality using the `LogicManager.java` class which follows the `Logic` interface. Other components interact with a given component through its interface rather than the concrete class (reason: to prevent outside component's being coupled to the implementation of a component), as illustrated in the (partial) class diagram below. +For example, the `Logic` component defines its API in the `Logic.java` interface and implements its functionality using the `LogicManager.java` class which follows the `Logic` interface. Other components interact with a given component through its interface rather than the concrete class (to prevent outside components being coupled to the concrete implementation of a component), as illustrated in the partial class diagram below. + While the `Storage` component provides an abstraction layer for persistent data, it also exposes access to specific data structures, such as `ReadOnlyHallPointer` and `UserPrefs`. This design balances abstraction with the need for practical access to certain data classes critical to the application’s functionality. 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 of each component. + +The sections below give more details about each component. ### UI component -The **API** of this component is specified in [`Ui.java`](https://github.com/AY2425S1-CS2103T-W14-3/tp/blob/master/src/main/java/hallpointer/address/ui/Ui.java) +As mentioned above, the **API** of this component is specified in [`Ui.java`](https://github.com/AY2425S1-CS2103T-W14-3/tp/blob/master/src/main/java/hallpointer/address/ui/Ui.java), and a partial but representative class diagram thereof is shown below. -The UI consists of a `MainWindow` that is made up of parts e.g.`CommandBox`, `ResultDisplay`, `MemberListPanel`, `StatusBarFooter` etc. All these, including the `MainWindow`, inherit from the abstract `UiPart` class which captures the commonalities between classes that represent parts of the visible GUI. +The UI consists of a `MainWindow` that is made up of various parts like `CommandBox`, `ResultDisplay`, `MemberListPanel`, `StatusBarFooter` and so on. All these, including the `MainWindow`, inherit from the abstract `UiPart` class which captures the commonalities between classes that represent parts of the visible GUI. -The `UI` component uses the JavaFx UI framework. The layout of these UI parts are defined in matching `.fxml` files that are in the `src/main/resources/view` folder. For example, the layout of the [`MainWindow`](https://ay2425s1-cs2103t-w14-3.github.io/tree/master/src/main/java/hallpointer/address/ui/MainWindow.java) is specified in [`MainWindow.fxml`](https://ay2425s1-cs2103t-w14-3.github.io/tree/master/src/main/resources/view/MainWindow.fxml) +The `UI` component uses the JavaFX UI framework. The layout of these UI parts are defined in matching `.fxml` files that are in the `src/main/resources/view` folder. For example, the layout of the [`MainWindow`](https://ay2425s1-cs2103t-w14-3.github.io/tree/master/src/main/java/hallpointer/address/ui/MainWindow.java) is specified in [`MainWindow.fxml`](https://ay2425s1-cs2103t-w14-3.github.io/tree/master/src/main/resources/view/MainWindow.fxml). -The `UI` component, +The `UI` component has the following responsibilities: -- executes user commands using the `Logic` component. -- listens for changes to `Model` data so that the UI can be updated with the modified data. -- keeps a reference to the `Logic` component, because the `UI` relies on the `Logic` to execute commands. -- depends on some classes in the `Model` component, as it displays `Member` object residing in the `Model`. +- Passing user commands to the `Logic` component using its reference thereof, so that the commands can be parsed and executed. +- Keeping the display up to date with `Model` data, by listening for changes in `Model` data to update the display when appropriate. + +It also depends on some classes in the `Model` component like the `Member` or `Session` objects residing in the `Model`, the details of which inform what sort of visual layout is appropriate. ### Logic component **API** : [`Logic.java`](https://github.com/AY2425S1-CS2103T-W14-3/tp/blob/master/src/main/java/hallpointer/address/logic/Logic.java) -Here's a (partial) class diagram of the `Logic` component: +Here's a partial and representative class diagram of the `Logic` component: -The sequence diagram below illustrates the interactions within the `Logic` component, taking `execute("delete_member 1")` API call as an example. +The sequence diagram below illustrates the interactions within the `Logic` component, taking an API call `execute("delete_member 1")` as an example. @@ -111,11 +112,11 @@ The sequence diagram below illustrates the interactions within the `Logic` compo How the `Logic` component works: -1. When `Logic` is called upon to execute a command, it is passed to an `Parser` object which in turn creates a parser that matches the command (e.g., `DeleteMemberCommandParser`) and uses it to parse the command. -2. This results in a `Command` object (more precisely, an object of one of its subclasses e.g., `DeleteCommand`) which is executed by the `LogicManager`. -3. The command can communicate with the `Model` when it is executed (e.g. to delete a member).
+1. When `Logic` is called upon to execute a command, the API call is passed to an `Parser` object, which in turn creates a parser that matches the command (e.g. `DeleteMemberCommandParser`) and uses it to parse the command. +2. This results in a `Command` object (more precisely, an object of one of its subclasses e.g. `DeleteCommand`) being created, which is then executed by the `LogicManager`. +3. The `Command` communicates with the `Model` when it is executed (e.g. to delete a member).
Note that although this is shown as a single step in the diagram above (for simplicity), in the code it can take several interactions (between the command object and the `Model`) to achieve. -4. The result of the command execution is encapsulated as a `CommandResult` object which is returned back from `Logic`. +4. The result of the command execution is encapsulated as a `CommandResult` object which is then returned by `Logic`. Here are the other classes in `Logic` (omitted from the class diagram above) that are used for parsing a user command: @@ -123,18 +124,20 @@ Here are the other classes in `Logic` (omitted from the class diagram above) tha How the parsing works: -- When called upon to parse a user command, the `Parser` class creates an `XYZCommandParser` (`XYZ` is a placeholder for the specific command name e.g., `AddMemberCommandParser`) which uses the other classes shown above to parse the user command and create a `XYZCommand` object (e.g., `AddMemberCommand`) which the `Parser` returns back as a `Command` object. -- All `XYZCommandParser` classes (e.g., `AddMemberCommandParser`, `DeleteSessionCommandParser`, ...) inherit from the `Parser` interface so that they can be treated similarly where possible e.g, during testing. +- When called upon to parse a user command, the `HallPointerParser` class creates an `XYZCommandParser` (where `XYZCommandParser` is a placeholder for the specific command name that matches the API call e.g. `AddMemberCommandParser`). This newly created `Parser` then uses the other classes shown above to parse the user command, creating a `XYZCommand` object (e.g. `AddMemberCommand`) which the `Parser` returns back as a `Command` object. +- All `XYZCommandParser` classes (e.g., `AddMemberCommandParser`, `DeleteSessionCommandParser`, ...) inherit from the `Parser` interface so that they can be treated similarly where possible, making adding more commands and further testing easier. ### Model component **API** : [`Model.java`](https://github.com/AY2425S1-CS2103T-W14-3/tp/blob/master/src/main/java/hallpointer/address/model/Model.java) +Here is a partial and representative class diagram of the `Model` component: + -The `Model` component, +The `Model` component has the following responsibilites: -- stores the hall pointer data i.e., all `Member` objects (which are contained in a `UniqueMemberList` object). +- Storing the HallPointer data (i.e. any `Member` and `Session` objects, and application configuration files) in the hard disk. - stores the currently 'selected' `Member` objects (e.g., results of a search query) as a separate _filtered_ list which is exposed to outsiders as an unmodifiable `ObservableList` that can be 'observed' e.g. the UI can be bound to this list so that the UI automatically updates when the data in the list change. - stores a `UserPref` object that represents the user’s preferences. This is exposed to the outside as a `ReadOnlyUserPref` objects. - does not depend on any of the other three components (as the `Model` represents data entities of the domain, they should make sense on their own without depending on other components) @@ -291,13 +294,13 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli | Priority | As a …​ | I want to …​ | So that I can …​ | Remarks/Notes | |----------|-----------------|------------------------------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------| -| `* * *` | First-time user | Explore the app using sample data | I can understand its features without manually entering data | | -| `* * *` | First-time user | See a guide on how to use the app | 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 app | | +| `* * *` | 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 | | | `* * *` | First-time user | See sample data with a predefined structure | I have a format to follow when inputting my own data | | -| `* * *` | First-time user | Delete all data in the app | I can start over when I make a mistake and remove sample data | | -| `* * *` | User | Add new Hall members to the app | I can track points for new Hall members | | -| `* * *` | User | Delete ex-Hall members from the app | I can stop tracking points for ex-Hall members | | +| `* * *` | First-time user | Delete all data in the application | I can start over when I make a mistake and remove sample data | | +| `* * *` | User | Add new Hall members to the application | I can track points for new Hall members | | +| `* * *` | User | Delete ex-Hall members from the application | I can stop tracking points for ex-Hall members | | | `* * *` | User | Customize point allocation criteria | I can reward members based on different participation criteria | E.g., different point weights for different activities | | `* * *` | Frequent user | Add or delete points for each Hall member | I can track the overall participation status in the CCA | | | `* * *` | Frequent user | Adjust attendance records if there are any errors | I can fix mistakes and maintain accurate records | | @@ -310,7 +313,7 @@ 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 | Charts or graphs to visualize data | | `*` | User | Sort members by name | I can locate a member easily | | | `*` | Frequent user | Automatically save changes without manual intervention | 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 app more efficiently without relying on the GUI | | +| `*` | Expert user | Perform all actions using the CLI | I can interact with the application more efficiently without relying on the GUI | | | `*` | Expert user | Automate repetitive tasks, such as attendance updates | I can save time by reducing manual input | | | `*` | 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 | | @@ -496,7 +499,7 @@ None. ## **Appendix: Instructions for manual testing** -Given below are instructions to test the app manually. +Given below are instructions to test the application manually. @@ -517,7 +520,7 @@ testers are expected to do more _exploratory_ testing. 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 app by double-clicking the `.jar` file.
+ 2. Re-launch the application by double-clicking the `.jar` file.
**Expected:** The most recent window size and location is retained. @@ -570,14 +573,14 @@ testers are expected to do more _exploratory_ testing. 1. Dealing with missing/corrupted data files - 1. Open the hallpointer.json file located in the data directory (this file is created after the app 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. 2. Confirming data persistence 1. Add or modify member/session data. - 2. Exit the app and re-launch it.
+ 2. Exit the application and re-launch it.
**Expected:** All previous data should be saved and displayed upon restart. ### Other Features diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 1f57bfa4fe2..b1cefb728df 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -56,7 +56,7 @@ Move the downloaded `.jar` file into the _home folder_ where you want to store y 4. **Run HallPointer:** - Open a command terminal, and use the `cd` command to navigate to the folder where you saved the `.jar` file. - Type the folowing command and press Enter: `java -jar hallpointer.jar` -- A window should appear after a few seconds, showing the HallPointer app’s user interface (UI). Note that the app comes with some sample data to help you get started.
+- A window should appear after a few seconds, showing the HallPointer app’s user interface (UI). Note that the application comes with some sample data to help you get started.
![Ui](images/Ui.png) 5. **Explore the Sample Data:** @@ -359,7 +359,7 @@ HallPointer data is saved automatically as a JSON file at `[JAR file location]/d ## FAQ **Q**: How do I transfer my data to another computer?
-**A**: Install the app on the other computer and overwrite the empty data file it creates with the file that contains the data from your previous HallPointer home folder. +**A**: Install the application on the other computer and overwrite the empty data file it creates with the file that contains the data from your previous HallPointer home folder. --- diff --git a/docs/diagrams/ArchitectureSequenceDiagram.puml b/docs/diagrams/ArchitectureSequenceDiagram.puml index 77c43a4e999..cdadfe70e37 100644 --- a/docs/diagrams/ArchitectureSequenceDiagram.puml +++ b/docs/diagrams/ArchitectureSequenceDiagram.puml @@ -14,7 +14,7 @@ activate ui UI_COLOR ui -[UI_COLOR]> logic : execute("delete_member 1") activate logic LOGIC_COLOR -logic -[LOGIC_COLOR]> model : deleteMember(p) +logic -[LOGIC_COLOR]> model : deleteMember(m) activate model MODEL_COLOR model -[MODEL_COLOR]-> logic