diff --git a/copyright.txt b/copyright.txt index 0f9d9dd247b..93aa2a39ce2 100644 --- a/copyright.txt +++ b/copyright.txt @@ -1,4 +1,9 @@ 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 (renamed to hall_pointer_32.png) +- address_book_32.png +- AddressApp.ico + +Copyright by Jan Jan Kovařík - http://glyphicons.com/ +- calendar.png +- edit.png diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index 7d426e23423..f32ce4636ef 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).\ -This project is based on the AddressBook-Level3 project created by the [SE-EDU initiative](https://se-education.org). +Libraries used: [JavaFX](https://openjfx.io/), [Jackson](https://github.com/FasterXML/jackson), [JUnit5](https://github.com/junit-team/junit5) + --- @@ -32,75 +32,74 @@ Refer to the guide [_Setting up and getting started_](SettingUp.md). -The **_Architecture Diagram_** given above explains the high-level design of the application. +The **_Architecture Diagram_** given above explains the high-level design of the App. -Given below is a quick overview of the main components of the application and how they interact with each other. +Given below is a quick overview of main components 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 application 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 app launch and shut down. -- At application launch, it initializes the other components in the correct sequence, and connects them up with each other. +- At app 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. -[**`Commons`**](#common-classes) represents a collection of classes used by multiple other components. +The bulk of the app's work is done by the following four components: -The bulk of the application's work is done by the following four 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. -- [**`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. +[**`Commons`**](#common-classes) represents a collection of classes used by multiple other components. **How the architecture components interact with each other** -The _Sequence Diagram_ below shows how the components interact with each other when the user issues the command `delete_member 1`. +The _Sequence Diagram_ below shows how the components interact with each other for the scenario where the user issues the command `delete_member 1`. -Each of the four main components (also shown in the diagram above) has these properties: +Each of the four main components (also shown in the diagram above), -- 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). +- 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. -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. +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. - 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 about each component. +The sections below give more details of each component. ### UI component -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 **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) -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 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` component has the following responsibilities: +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) -- 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. +The `UI` component, -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. +- 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`. ### 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 and representative class diagram of the `Logic` component: +Here's a (partial) class diagram of the `Logic` component: -The sequence diagram below illustrates the interactions within the `Logic` component, taking an API call `execute("delete_member 1")` as an example. +The sequence diagram below illustrates the interactions within the `Logic` component, taking `execute("delete_member 1")` API call as an example. @@ -112,11 +111,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, 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).
+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).
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 then returned by `Logic`. +4. The result of the command execution is encapsulated as a `CommandResult` object which is returned back from `Logic`. Here are the other classes in `Logic` (omitted from the class diagram above) that are used for parsing a user command: @@ -124,8 +123,8 @@ 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 `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. +- 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. ### Model component @@ -133,11 +132,11 @@ How the parsing works: -The `Model` component has the following responsibilites: +The `Model` component has the following responsibilities: - Storing the HallPointer data (i.e. any `Member` and `Session` objects) in memory for easy access. - Exposing the currently 'selected' `Member` objects (e.g. the results of a search query) as a separate and unmodifiable `ObservableList` that can be 'observed', allowing the UI to observe this list and automatically update the UI when the data in this list changes. -- Store a `UserPref` object that represents the user’s preferences, and expose it to outside components as a `ReadOnlyUserPref` object. +- Store a `UserPref` object that represents the user’s preferences, and expose it to outside components as a `ReadOnlyUserPref` object. Since `Model` represents the data entities of this application and problem domain, it should make sense on its own without dependencies on other components. And thus this component does not depend on any of the other three components. @@ -285,13 +284,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 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 | 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 | 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 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 | | +| `* * *` | 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 | | | `* * *` | 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 | | @@ -304,7 +303,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 application more efficiently without relying on the GUI | | +| `*` | Expert user | Perform all actions using the CLI | I can interact with the app 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 | | @@ -490,7 +489,7 @@ None. ## **Appendix: Instructions for manual testing** -Given below are instructions to test the application manually. +Given below are instructions to test the app manually. @@ -511,7 +510,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 application by double-clicking the `.jar` file.
+ 2. Re-launch the app by double-clicking the `.jar` file.
**Expected:** The most recent window size and location is retained. @@ -564,14 +563,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 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 app 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 application and re-launch it.
+ 2. Exit the app 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 b1cefb728df..1f57bfa4fe2 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 application 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 app 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 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. +**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. --- diff --git a/docs/diagrams/ArchitectureSequenceDiagram.puml b/docs/diagrams/ArchitectureSequenceDiagram.puml index cdadfe70e37..77c43a4e999 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(m) +logic -[LOGIC_COLOR]> model : deleteMember(p) activate model MODEL_COLOR model -[MODEL_COLOR]-> logic