From 9a3321f027da19a812484d8a648c13e5eb357c07 Mon Sep 17 00:00:00 2001 From: Rachel Tai Ke Jia Date: Thu, 7 Nov 2024 11:53:30 +0800 Subject: [PATCH 1/8] Update acknowledgements and architecture --- docs/DeveloperGuide.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index 3cd29561511..286f7ecd32a 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -20,11 +20,11 @@ ## **Acknowledgements** - Initial project template (code and documentation): - - [AB3](https://github.com/se-edu/addressbook-level3) + - [AB3](https://github.com/se-edu/addressbook-level3) - Adapted the overall structure and some core functionalities of AB3 for DocTrack. - Third-party libraries: - - [JUnit](https://junit.org/junit5/) - - [JavaFX](https://openjfx.io/) - - [Jackson](https://github.com/FasterXML/jackson) + - [JUnit](https://junit.org/junit5/) - Used for testing. + - [JavaFX](https://openjfx.io/) - Used for the graphical user interface. + - [Jackson](https://github.com/FasterXML/jackson) - Used for JSON parsing and serialization.
@@ -46,13 +46,17 @@ Refer to the guide [_Setting up and getting started_](SettingUp.md). ### Architecture +The ***Architecture Diagram*** below explains the high-level design of the DocTrack application. + -The ***Architecture Diagram*** given above explains the high-level design of the App. +

Given below is a quick overview of main components and how they interact with each other. -**Main components of the architecture** +
+ +#### Main components of the architecture **`Main`** (consisting of classes [`Main`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/Main.java) and [`MainApp`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/MainApp.java)) is in charge of the app launch and shut down. * At app launch, it initializes the other components in the correct sequence, and connects them up with each other. @@ -60,16 +64,16 @@ Given below is a quick overview of main components and how they interact with ea The bulk of the app's work is done by the following four components: -* [**`UI`**](#ui-component): The UI of the App. +* [**`UI`**](#ui-component): The UI of DocTrack. * [**`Logic`**](#logic-component): The command executor. -* [**`Model`**](#model-component): Holds the data of the App in memory. +* [**`Model`**](#model-component): Holds the data of DocTrack 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** +#### 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 person 1`. +The *Sequence Diagram* below shows how the components interact with each other for the scenario where the user enters the command `delete person 1`. From 3bc26b15c770fc117fce4cc9f8e6394fed732de2 Mon Sep 17 00:00:00 2001 From: Rachel Tai Ke Jia Date: Thu, 7 Nov 2024 13:48:35 +0800 Subject: [PATCH 2/8] Update class diagrams --- docs/diagrams/BetterModelClassDiagram.puml | 7 +++++++ docs/diagrams/ModelClassDiagram.puml | 12 +++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/diagrams/BetterModelClassDiagram.puml b/docs/diagrams/BetterModelClassDiagram.puml index 99c2328177c..2dd75a635c8 100644 --- a/docs/diagrams/BetterModelClassDiagram.puml +++ b/docs/diagrams/BetterModelClassDiagram.puml @@ -8,6 +8,7 @@ AppointmentBook *-left-> "1" UniqueAppointmentList UniqueAppointmentList *-down-> "1" Appointment Appointment *-left-> "1" Person + AddressBook *-right-> "1" UniquePersonList AddressBook *-right-> "1" UniqueTagList UniqueTagList -[hidden]down- UniquePersonList @@ -22,4 +23,10 @@ Person *--> Name Person *--> Phone Person *--> Email Person *--> Address +Person *--> Status + +Appointment *--> AppointmentType +Appointment *--> DateTime +Appointment *--> Sickness +Appointment *--> Medicine @enduml diff --git a/docs/diagrams/ModelClassDiagram.puml b/docs/diagrams/ModelClassDiagram.puml index 0ea8ced614a..74e4397c857 100644 --- a/docs/diagrams/ModelClassDiagram.puml +++ b/docs/diagrams/ModelClassDiagram.puml @@ -21,11 +21,16 @@ Class Address Class Email Class Name Class Phone +Class Status Class Tag Class UniqueAppointmentList Class Appointment Class AppointmentDescriptor +Class AppointmentType +Class DateTime +Class Sickness +Class Medicine Class I #FFFFFF } @@ -51,12 +56,17 @@ PersonDescriptor *--> Name PersonDescriptor *--> Phone PersonDescriptor *--> Email PersonDescriptor *--> Address +PersonDescriptor *--> Status PersonDescriptor *--> "*" Tag AppointmentBook *--> "1" UniqueAppointmentList UniqueAppointmentList --> "~* all" Appointment Appointment *--> "1" AppointmentDescriptor -AppointmentDescriptor *--> Person +Appointment *--> Person +AppointmentDescriptor *--> AppointmentType +AppointmentDescriptor *--> DateTime +AppointmentDescriptor *-->"0..1" Sickness +AppointmentDescriptor *-->"0..1" Medicine Appointment -[hidden]down--> I PersonDescriptor -[hidden]up--> I From 75428867a16959b4d53b9a4233e0160196e1634d Mon Sep 17 00:00:00 2001 From: Rachel Tai Ke Jia Date: Thu, 7 Nov 2024 16:26:58 +0800 Subject: [PATCH 3/8] Update diagrams and design considerations --- docs/DeveloperGuide.md | 137 +++++++++++------- docs/diagrams/BetterModelClassDiagram.puml | 7 +- .../EntityCommandSequenceDiagram.puml | 6 +- .../appointment/UniqueAppointmentList.java | 2 +- 4 files changed, 91 insertions(+), 61 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index 286f7ecd32a..6a048ed3d31 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -58,10 +58,12 @@ Given below is a quick overview of main components and how they interact with ea #### Main components of the architecture -**`Main`** (consisting of classes [`Main`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/Main.java) and [`MainApp`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/MainApp.java)) is in charge of the app launch and shut down. +**`Main`** (consisting of classes [`Main`](https://github.com/AY2425S1-CS2103T-W10-2/tp/blob/master/src/main/java/seedu/address/Main.java) and [`MainApp`](https://github.com/AY2425S1-CS2103T-W10-2/tp/blob/master/src/main/java/seedu/address/MainApp.java)) is in charge of the app launch and shut down. * 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. +
+ The bulk of the app's work is done by the following four components: * [**`UI`**](#ui-component): The UI of DocTrack. @@ -71,9 +73,11 @@ 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. +
+ #### 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 enters the command `delete person 1`. +The *Sequence Diagram* below shows how the components interact with each other, for the scenario where the user enters the command `delete person 1`. @@ -83,17 +87,19 @@ Each of the four main components (also shown in the diagram above), * 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 (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 _(reason: to prevent outside component's being coupled to the implementation of a component)_, as illustrated in the (partial) class diagram below. +

+ The sections below give more details of each component.
### UI component -The **API** of this component is specified in [`Ui.java`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/ui/Ui.java) +The **API** of this component is specified in [`Ui.java`](https://github.com/AY2425S1-CS2103T-W10-2/tp/tree/master/src/main/java/seedu/address/ui) @@ -112,7 +118,7 @@ The `UI` component, ### Logic component -**API** : [`Logic.java`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/logic/Logic.java) +**API** : [`Logic.java`](https://github.com/AY2425S1-CS2103T-W10-2/tp/tree/master/src/main/java/seedu/address/logic) Here's a (partial) class diagram of the `Logic` component: @@ -146,9 +152,9 @@ How the parsing works:
### Model component -**API** : [`Model.java`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/model/Model.java) +**API** : [`Model.java`](https://github.com/AY2425S1-CS2103T-W10-2/tp/tree/master/src/main/java/seedu/address/model) - + The `Model` component, @@ -158,8 +164,8 @@ The `Model` component, * stores the address book data i.e., all `Person` objects (which are contained in a `UniquePersonList` object). * stores the currently 'selected' `Person` 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. * with regards to `Appointment` objects: - * stores the details of an appointment in a `AppointmentDescriptor` object - * stores the `AppointmentDescriptor` object with a `appointmentId` in the `Appointment` class. + * stores the details of an appointment in an `AppointmentDescriptor` object + * stores the `AppointmentDescriptor` object with a `Person` and `appointmentId` in the `Appointment` class. * stores the address book data i.e., all `Appointment` objects (which are contained in a `UniqueAppointmentList` object). * stores the currently 'selected' `Appointment` 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. @@ -167,9 +173,10 @@ The `Model` component, -**Note:** An alternative (arguably, a more OOP) model is given below. It has a `Tag` list (the `UniqueTagList`) in the `AddressBook`, which `Person` references. This allows `AddressBook` to only require one `Tag` object per unique tag, instead of each `Person` needing their own `Tag` objects. Similarly, the `Appointment` objects are shown as such as well.
+**Note:** An alternative (arguably, a more OOP) model is given below. It has a `Tag` list (the +`UniqueTagList`) in the `AddressBook`, which `Person` references. This allows `AddressBook` to only require one `Tag` object per unique tag, instead of each `Person` needing their own `Tag` objects. Similarly, the `Appointment` objects are shown as such too.
- + @@ -177,22 +184,23 @@ The `Model` component, ### Storage component -**API** : [`Storage.java`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/storage/Storage.java) +**API** : [`Storage.java`](https://github.com/AY2425S1-CS2103T-W10-2/tp/tree/master/src/main/java/seedu/address/storage) - + -The `Storage` component, -* can save patient data, appointment data, and user preference data in JSON format, and read them back into corresponding objects. -* Storage interface inherits from `AddressBookStorage`, `AppointmentBookStorage` and `UserPrefStorage`, which means it can be treated as either one (if only the functionality of only one is needed). -* Patient data : - * data is saved in `JsonAddressBookStorage` which inherits from interface `AddressBookStorage`. - * data is saved as `JsonSerializableAddressBook` which consists of `JsonAdaptedPerson` and `JsonAdaptedTag` which embodies the actual data of the individual patient and their data +* The `Storage` component can save patient data, appointment data, and user preference data in JSON format, and read them back into corresponding objects. +* The `Storage` interface inherits from `AddressBookStorage`, `AppointmentBookStorage` and `UserPrefStorage`, which means it can be treated as either one (if only the functionality of only one is needed). +* Patient data: + * Data is saved in `JsonAddressBookStorage` which inherits from interface `AddressBookStorage`. + * Data is saved as `JsonSerializableAddressBook` which consists of `JsonAdaptedPerson` and + `JsonAdaptedTag` which embodies the actual data of the individual patient and their data * Appointment data: - * data is saved in `JsonAppointmentBookStorage` which inherits from interface `AppointmentBookStorage`. - * data is saved as `JsonSerializableAppointmentBook` which consists of `JsonAdaptedAppointment` which embodies the actual data of appointments and appointment details + * Data is saved in `JsonAppointmentBookStorage` which inherits from interface `AppointmentBookStorage`. + * Data is saved as `JsonSerializableAppointmentBook` which consists of `JsonAdaptedAppointment` which + embodies the actual data of appointments and appointment details * User Preference data: - * data is saved in `UserPrefsStorage` interface and saves as `JsonUserPrefsStorage` -* depends on some classes in the `Model` component (because the `Storage` component's job is to save/retrieve objects that belong to the `Model`) + * Data is saved in `UserPrefsStorage` interface and saved as `JsonUserPrefsStorage` +* The `Storage` component depends on some classes in the `Model` component (because the `Storage` component's job is to save/retrieve objects that belong to the `Model`)
@@ -227,74 +235,97 @@ The activity diagram shows the general sequence of steps when a user interacts w ## **Implementation of entity command features** -Entity commands include `add`, `delete`, `find`, `clear`, `edit`, and `list` commands. Hence, `xyzCommand` can be `addPersonCommand`, `addCommandParser` and so on. +Entity commands include `add`, `delete`, `find`, `clear`, `edit`, and `list` commands. +* Hence, `xyzCommand` can be `addCommand`, `deleteCommand`, `findCommand`, `clearCommand`, `editCommand`, or `listCommand`. The sequence diagram shows how an entity command is executed: -- The entity referred in `FindEntityCommand` etc, refers to `FindPersonCommand` and `FindAppointmentCommand`. There are two entities, **person** and **appointment**, on which operations can be performed. -**Step 1**. The user types an `xyz` command in the `CommandBox`, followed by the type of entity, `person` or `appt`. This is followed by appropriate arguments and prefixes. + + +**Note:** There are two entities, `Person` and `Appointment`. +- The entity referred in `FindEntityCommand` refers to `FindPersonCommand` and `FindAppointmentCommand`. +- Similarly, the entity referred in `AddEntityCommand` refers to `AddPersonCommand` and `AddAppointmentCommand`. +- This applies for the other commands as well. + + +**Step 1**. The user types an `xyz` command input in the `CommandBox`, followed by the type of entity, +`person` or `appt`. This is followed by appropriate arguments and prefixes. + + +**Step 2**. The input is passed to the `LogicManager`. `LogicManager` then calls the +`AddressBookParser::parseCommand` method to parse the input. + + +**Step 3**. The `AddressBookParser` parses the input and creates an `xyzCommandParser` object, which is +returned to the `AddressBookParser`. -**Step 2**. The command is passed to the `LogicManager`. `LogicManager` then calls the `AddressBookParser::parseCommand` method to parse the command. +**Step 4**. The `AddressBookParser` calls the +`xyzCommandParser::parse` method to parse the arguments. -**Step 3**. The `AddressBookParser` creates a `xyzEntityCommand` object, and call the `xyzCommandParser::parse` method, which is returned to the `LogicManager`. This may be different based on the entity type as commands like `addPersonCommand` and `addApptCommand` have a different set of arguments the user can provide. +**Step 5**. The `xyzCommandParser` creates an `xyzCommand` object, which is returned to the `LogicManager`. -**Step 4**. The `LogicManager` calls the `xyzCommand : execute` method which creates a `CommandResult` Object. +**Step 6**. The `LogicManager` calls the `xyzCommand : execute` method, which creates a `CommandResult` +Object. -**Step 5**. The `CommandResult` object is returned to the `LogicManager`. +**Step 7**. The `CommandResult` object is returned to the `LogicManager`.
### General Design Considerations **Aspect: Whether to implement entity commands as separate commands or through an abstract base command** -- **Alternative 1 (Current choice):** Implement an abstract EntityCommand class that specific entity commands (e.g., AddPersonCommand, AddAppointmentCommand, DeletePersonCommand, DeleteAppointmentCommand) inherit from. - - Pros: Allows for reuse of code logic between entity commands - - Cons: Requires additonal parsing logic since entity in command must be distinguished (person or appointment), which can add complexity +- **Alternative 1 (Current choice):** Implement an abstract EntityCommand class that specific entity + commands (e.g. `AddPersonCommand`, `AddAppointmentCommand`, `DeletePersonCommand`, + `DeleteAppointmentCommand`) + inherit from. + - **Pros**: Allows for reuse of code logic between entity commands. + - **Cons**: Requires additional parsing logic since entity in command must be distinguished (person or appointment), which can add complexity. - **Alternative 2:** Implement each entity command as entirely separate classes. - - Pros: Creates a separate command, so the implementations of each command are separated and less coupled - - Cons: Results in significant code duplication + - **Pros**: Creates a separate command, so the implementations of each command are separated and less coupled. + - **Cons**: Results in significant code duplication.
-**Aspect: What constitutes duplicate person that should not be added or edited into the address book** -- **Alternative 1 (Current choice):** Duplicate person is one that has same name (case-insensitive) and same phone number as an existing person - - Pros: Name and phone numbers are identifiers that are commonly recognized by users - - Cons: Extra logic required to determine equality of different people -- **Alternative 2:** A duplicate person is defined more loosely or strictly (e.g., by name only) - - Pros: Less logic required to determine equality of different people - - Cons: Different people could have the same name, but cannot be added into the address book +**Aspect: What constitutes duplicate person that should not be added or edited into the AddressBook** +- **Alternative 1 (Current choice):** Duplicate person is one that has the same name (case-insensitive) and same phone number as an existing person + - **Pros**: Name and phone numbers are identifiers that are commonly recognized by users. + - **Cons**: Extra logic required to determine equality of different people. +- **Alternative 2:** A duplicate person is defined more loosely or strictly (e.g. by name only) + - **Pros**: Less logic required to determine equality of different people. + - **Cons**: Different people could have the same name, but cannot be added into the AddressBook.
-**Aspect: What constitutes duplicate appointment that should not be added or edited into the appointment book** -- **Alternative 1 (Current choice):** Duplicate appointment is one that has same person, date and time of an existing appointment - - Pros: Provides a rule to avoid scheduling conflicts of same person - - Cons: Extra logic required to determine equality of different appointments +**Aspect: What constitutes duplicate appointment that should not be added or edited into the AppointmentBook** +- **Alternative 1 (Current choice):** Duplicate appointment is one that has same person, date and time, and appointment type as an existing appointment + - **Pros**: Provides a rule to avoid scheduling conflicts of same person. + - **Cons**: Extra logic required to determine equality of different appointments. - **Alternative 2:** Define duplicates with only the date and time - - Pros: Less logic required to determine equality of different appointments - - Cons: Different appointments with different persons could have the same date time, but cannot be added into the appointment book + - **Pros**: Less logic required to determine equality of different appointments. + - **Cons**: Different appointments with different persons could have the same date time, but cannot be added + into the AppointmentBook.
### Command-Specific Design Considerations -### Add Appointment feature +#### Add Appointment feature **Aspect: Whether appointment fields should be optional** -- **Alternative 1 (Current choice):** Sickness and medicine fields are optional. +- **Alternative 1 (Current choice):** `Sickness` and `Medicine` fields are optional. - **Pros**: This allows users to create an appointment without specifying all fields initially, which is more realistic and practical as some details may not be available at the time of creation. - **Alternative 2**: Make all fields mandatory. - **Pros**: Ensures complete data at the time of appointment creation, which may simplify data handling and reduce the need for future edits. - - **Cons**: Can be inconvenient for users who don’t have all details available immediately, possibly leading to frustration or delays in creating appointments. + - **Cons**: Can be inconvenient for users who do not have all details available immediately, possibly leading to frustration or delays in creating appointments.
@@ -312,9 +343,9 @@ The sequence diagram shows how an entity command is executed: **Aspect: Deleting person and clearing person list should:** - **Alternative 1 (Current choice):** remove appointments with the `personId` of that person. - - Pros: This prevents the case where appointments are linked to personIds that are non-existent. + - **Pros**: This prevents the case where appointments are linked to personIds that are non-existent. - **Alternative 2:** not remove any appointments with the `personId` of that person. - - Cons: This assumes the user would delete the appointments linked to the deleted person's `personId`. However, the user might forget to do so. + - **Cons**: This assumes the user would delete the appointments linked to the deleted person's `personId`. However, the user might forget to do so.
diff --git a/docs/diagrams/BetterModelClassDiagram.puml b/docs/diagrams/BetterModelClassDiagram.puml index 2dd75a635c8..80c594e49fc 100644 --- a/docs/diagrams/BetterModelClassDiagram.puml +++ b/docs/diagrams/BetterModelClassDiagram.puml @@ -4,11 +4,10 @@ skinparam arrowThickness 1.1 skinparam arrowColor MODEL_COLOR skinparam classBackgroundColor MODEL_COLOR -AppointmentBook *-left-> "1" UniqueAppointmentList +AppointmentBook *--> "1" UniqueAppointmentList UniqueAppointmentList *-down-> "1" Appointment Appointment *-left-> "1" Person - AddressBook *-right-> "1" UniquePersonList AddressBook *-right-> "1" UniqueTagList UniqueTagList -[hidden]down- UniquePersonList @@ -27,6 +26,6 @@ Person *--> Status Appointment *--> AppointmentType Appointment *--> DateTime -Appointment *--> Sickness -Appointment *--> Medicine +Appointment *--> "0..1"Sickness +Appointment *--> "0..1"Medicine @enduml diff --git a/docs/diagrams/EntityCommandSequenceDiagram.puml b/docs/diagrams/EntityCommandSequenceDiagram.puml index 94b15ad07c3..18b8fa2a027 100644 --- a/docs/diagrams/EntityCommandSequenceDiagram.puml +++ b/docs/diagrams/EntityCommandSequenceDiagram.puml @@ -18,16 +18,16 @@ LogicManager -> AddressBookParser : parseCommand("xyz") create CommandParser activate AddressBookParser AddressBookParser -> CommandParser + +note right of CommandParser: xyzCommandParser = \nFindCommandParser, \nAddCommandParser, \nDeleteCommandParser, \nEditCommandParser, \nClearCommandParser, \nListCommandParser + activate CommandParser AddressBookParser <-- CommandParser deactivate CommandParser - - AddressBookParser -> CommandParser : parse("xyz") activate CommandParser - create XYZCommand CommandParser -> XYZCommand activate XYZCommand diff --git a/src/main/java/seedu/address/model/appointment/UniqueAppointmentList.java b/src/main/java/seedu/address/model/appointment/UniqueAppointmentList.java index a752b43d21a..5ef02a397a3 100644 --- a/src/main/java/seedu/address/model/appointment/UniqueAppointmentList.java +++ b/src/main/java/seedu/address/model/appointment/UniqueAppointmentList.java @@ -72,7 +72,7 @@ public void addAppointment(Appointment appointmentToAdd) { /** * Replaces the appointment {@code target} in the list with {@code editedAppointment}. * {@code target} must exist in the list. - * The appointmnet identity of {@code editedAppointment} must not be the same as another + * The appointment identity of {@code editedAppointment} must not be the same as another * existing appointment in the list. */ public void setAppointment(Appointment target, Appointment editedAppointment) { From 5a7ebaf60deac26447d39252fbaa6344fb87bb35 Mon Sep 17 00:00:00 2001 From: Rachel Tai Ke Jia Date: Thu, 7 Nov 2024 18:54:19 +0800 Subject: [PATCH 4/8] Update design considerations --- docs/DeveloperGuide.md | 218 ++++++++++++++++------------------------- 1 file changed, 86 insertions(+), 132 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index 6a048ed3d31..fba884ec5a3 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -319,96 +319,95 @@ Object. #### Add Appointment feature **Aspect: Whether appointment fields should be optional** - - **Alternative 1 (Current choice):** `Sickness` and `Medicine` fields are optional. - - **Pros**: This allows users to create an appointment without specifying all fields initially, which is more realistic and practical as some details may not be available at the time of creation. - + - **Pros**: This allows users to create an appointment without specifying all fields initially, which is + more realistic and practical as some details may not be available at the time of creation. - **Alternative 2**: Make all fields mandatory. - - **Pros**: Ensures complete data at the time of appointment creation, which may simplify data handling and reduce the need for future edits. - - **Cons**: Can be inconvenient for users who do not have all details available immediately, possibly leading to frustration or delays in creating appointments. + - **Pros**: Ensures complete data at the time of appointment creation, which may simplify data handling and reduce the need for future edits. + - **Cons**: Can be inconvenient for users who do not have all details available immediately, possibly leading to frustration or delays in creating appointments.
-**Aspect: What Input Should Be Valid for Fields Sickness and Medicine** - -- **Alternative 1 (Current choice):** Require input with at least one alphanumeric character. - - **Pros**: Ensures these fields contain meaningful data, reducing the likelihood of accidental or erroneous inputs. - +**Aspect: What input should be valid for fields `Sickness` and `Medicine`** +- **Alternative 1 (Current choice):** Require input with at least one alphabet. + - **Pros**: Ensures these fields contain meaningful data, reducing the likelihood of accidental or erroneous inputs. - **Alternative 2:** Allow any value as valid input. - - **Cons**: Increases the risk of erroneous inputs, such as empty fields, accidental symbols, or irrelevant characters, potentially reducing data quality. + - **Cons**: Increases the risk of erroneous inputs, such as empty fields, accidental symbols, or + irrelevant characters, potentially reducing data quality. +
-#### Delete/Clear Person feature +#### Delete / Clear Person feature -**Aspect: Deleting person and clearing person list should:** +**Aspect: Whether `delete person` and `clear person` should remove appointments too** -- **Alternative 1 (Current choice):** remove appointments with the `personId` of that person. +- **Alternative 1 (Current choice):** Deleting person and clearing the person list also removes appointments with the `personId` of the deleted person(s). - **Pros**: This prevents the case where appointments are linked to personIds that are non-existent. -- **Alternative 2:** not remove any appointments with the `personId` of that person. +- **Alternative 2:** Deleting person and clearing the person list will not remove any appointments with the `personId` of that person. - **Cons**: This assumes the user would delete the appointments linked to the deleted person's `personId`. However, the user might forget to do so.
-#### Edit Person/Appointment feature +#### Edit Person / Appointment feature **Aspect: What value to use for indicating entity** -- **Alternative 1 (Current choice):** Use the index of the person/appointment in the list. - - **Pros**: Enables efficient retrieval directly from the list using `List#get`, simplifying implementation. - - **Cons**: Entity indexes may shift after deletions, which could lead to unintended edits if the user isn’t aware of changes in ordering. +- **Alternative 1 (Current choice):** Use the index of the person / appointment in the list. + - **Pros**: Enables efficient retrieval directly from the list, simplifying implementation. + - **Cons**: Entity indexes may shift after deletions, which could lead to unintended edits if the user is not aware of changes in ordering. - **Alternative 2:** Use a unique ID for each entity. - - **Pros**: IDs remain consistent regardless of list modifications, ensuring stable reference to the entity. - - **Cons**: Implementing ID-based retrieval requires additional logic and may be slower, especially for larger lists. + - **Pros**: IDs remain consistent regardless of list modifications, ensuring stable reference to the entity. + - **Cons**: Implementing ID-based retrieval requires additional logic and may be slower, especially for larger lists.
-**Aspect: During Edit Appointment, check if new person ID associated with edited appointment corresponds to an existing person in the address book** -- This is to ensure no unwanted errors occur while editing the appointment and helps to maintain data integrity. +**Aspect: Whether to check if the `personId` associated with edited appointment corresponds to an existing person in the AddressBook** +- **Alternative 1 (Current choice):** When executing the `edit appt` command, check if the new `personId` + exists in the AddressBook. + - **Pros:** Ensures data integrity by preventing appointments from being linked to non-existent persons. + - **Cons:** Requires additional validation logic during the edit process. +- **Alternative 2:** Execution of the `edit appt` command does not check if the new `personId` exists in the AddressBook. + - **Pros:** Simplifies the edit process by removing the need for additional validation. + - **Cons:** Increases the risk of data inconsistency, as appointments may be linked to non-existent persons.
-#### Find Person/Appointment feature - -**Aspect: How to show find person/appointment based on different criteria** +#### Find Person / Appointment feature +**Aspect: How to implement the `find person` and `find appt` commands that allow finding by multiple criteria** - **Alternative 1 (Current choice)**: Create one find command that supports filtering by multiple criteria (name, date) using prefixes. - - Pros: Fast and easy to find by date and name - - Cons: Confusing syntax from user's perspective - + - Pros: Fast and easy to find by date and name. + - Cons: Confusing syntax from user's perspective. - **Alternative 2**: Create different find commands, find by date, find by name etc. - - Pros: Much easy in terms of user experience - - Cons: More repeated code for each command + - Pros: Much easy in terms of user experience. + - Cons: More repeated code for each command.
-**Aspect: How to combine multiple prefixes when finding results** - +**Aspect: How to combine multiple prefixes when executing the `find` commands** - **Alternative 1 (Current choice)**: Prefixes should be combined using an AND condition. - - Pros: Ensures more specific search results, as all conditions must be met - - Cons: May be too restrictive - + - **Pros**: Ensures more specific search results, as all conditions must be met. + - **Cons**: May be too restrictive. - **Alternative 2**: Prefixes should be combined using an OR condition - - Pros: Allows for more flexible and broader search results, as any one of the conditions can yield matches. - - Cons: May return too many results + - **Pros**: Allows for more flexible and broader search results, as any one of the conditions can yield matches. + - **Cons**: May return too many results.
-**Aspect: Whether to implement case sensitivity in matching** - +**Aspect: Whether to implement case sensitivity in matching for search terms** - **Alternative 1 (Current choice)**: Implement case-insensitive matching for search terms. - - **Pros**: Enhances user experience by allowing searches to ignore case differences - - **Cons**: Slightly more processing required to normalize case during search - + - **Pros**: Enhances user experience by allowing searches to ignore case differences. + - **Cons**: Slightly more processing required to normalize case .during search - **Alternative 2**: Implement case-sensitive matching for search terms. - - **Pros**: Potentially faster searches, as no additional case normalization is required - - **Cons**: Reduces user-friendliness + - **Pros**: Potentially faster searches, as no additional case normalization is required. + - **Cons**: Reduces user-friendliness.
**Tip:** -To add a new predicate, navigate the corresponding entity folder in the model package. There, you can create a new class that implements `Predicate`. Ensure that this method has a test method which defines the specific condition for a predicate. +To add a new predicate, navigate the corresponding entity folder in the `model` package. There, you can create a new class that implements `Predicate`. Ensure that this method has a test method which defines the specific condition for a predicate. @@ -437,14 +436,11 @@ object.
### Exit feature -#### Implementation When a user types an `exit` command, the DocTrack application will exit.
### Help feature -#### Implementation - When a user types a `help` command, the DocTrack application will display a `HelpWindow`. #### Design considerations @@ -452,11 +448,11 @@ When a user types a `help` command, the DocTrack application will display a `Hel **Aspect: How to display help information:** * **Alternative 1 (current choice):** Display help information in a new window. - * Pros: Keeps the main application window uncluttered. - * Cons: Requires managing an additional window. + * **Pros**: Keeps the main application window uncluttered. + * **Cons**: Requires managing an additional window. * **Alternative 2:** Display help information in a modal dialog. - * Pros: Simpler to implement. - * Cons: Can clutter the main application window and interrupt the user's workflow. + * **Pros**: Simpler to implement. + * **Cons**: Can clutter the main application window and interrupt the user's workflow.
@@ -485,16 +481,11 @@ When a user types a `help` command, the DocTrack application will display a `Hel **Aspect: Save patient and appointment data in:**
* **Alternative 1 (current choice):** two different files, patient data in `data/addressbook.json` and appointment data in `data/appointmentbook.json`. - * Pros: - * More organised file management - * Quicker read and write times for each file - * Cons: - * Higher chance of inconsistencies between patient and appointment data + * **Pros**: More organised file management, with a quicker read and write times for each file. + * **Cons**: Higher chance of inconsistencies between patient and appointment data. * **Alternative 2:** one single file named `data/addressbook.json` - * Pros: - * Simplicity and convenience of one file for all information - * Cons: - * Slower read and write times for file, especially if the user is only accessing one of patient or appointment data. + * **Pros**: Simplicity and convenience of one file for all information. + * **Cons**: Slower read and write times for file, especially if the user is only accessing one of patient or appointment data. @@ -508,11 +499,11 @@ is not specified, it would be represented as `"null"`, in the `appointmentbook.j **Aspect: When the data is updated in the `.json` file:**
* **Alternative 1 (current choice):** Automatically save all changes after any command that changes the data. - * Pros: Simplifies the process for the user, without needing to save manually. - * Cons: May be slow if there are many changes to save. + * **Pros**: Simplifies the process for the user, without needing to save manually. + * **Cons**: May be slow if there are many changes to save. * **Alternative 2:** Prompt the user to save changes before exiting. - * Pros: Gives the user more control over the saving process. - * Cons: May be annoying for users who do not want an additional step to save changes. + * **Pros**: Gives the user more control over the saving process. + * **Cons**: May be annoying for users who do not want an additional step to save changes.
@@ -523,58 +514,32 @@ is not specified, it would be represented as `"null"`, in the `appointmentbook.j Context: The commands (other than the general) have the command format: `COMMAND ENTITY_TYPE ENTITY_ARGS`
* **Alternative 1 (current choice):** Parse `ENTITY_TYPE` and `ENTITY_ARGS` separately. - * Pros: - * Easier to parse - * Easier to debug, as the parsing is separated into different portions - * Cons: - * More verbose, and less centralised. + * **Pros**: Easier to parse and debug, as the parsing is separated into different portions. + * **Cons**: More verbose, and less centralised. * **Alternative 2**: Parse them together. - * Pros: - * Everything is parsed together, centralising the parsing logic. - * Cons: - * Harder to parse and debug + * **Pros**: Everything is parsed together, centralising the parsing logic. + * **Cons**: Harder to parse and debug.
**Aspect: Command format (with or without prefixes):**
-* **Alternative 1 (current choice):** Use prefixes - * Pros: - * Easier to identify markers for each parameter - * Prefixes allow for free positioning of arguments - * Cons: - * Less intuitive for the user at start - * Need to create prefixes -* **Alternative 2:** Use no prefixes - * Parsing the arguments based on position. - * Pros: - * More intuitive at start - * No need to create prefixes - * Cons: - * Harder to identify markers - may result in issues with arguments that have spaces in between - * No free positioning - * Might be harder to implement variable amount of arguments +* **Alternative 1 (current choice):** Use prefixes. + * **Pros**: Easier to identify markers for each parameter, and prefixes allow for free positioning of arguments. + * **Cons**: Less intuitive for the user at start, and need to create the prefixes. +* **Alternative 2:** Use no prefixes, parse the arguments based on position. + * **Pros**: More intuitive at start, no need to create prefixes. + * **Cons**: Harder to identify markers - may result in issues with arguments that have spaces in between, no free positioning, and might be harder to implement variable amount of arguments.
-**Aspect: `ArgumentMultimap` use across different entities:** -
-Context: The `ArgumentMultimap` is used across different entities. -
+**Aspect: The use of `ArgumentMultimap` across different entities:** * **Alternative 1 (current choice):** Use the same `ArgumentMultimap` for all entities. - * Pros: - * Prefixes are shared universally, making it more consistent across entities. - * Less code duplication - * Cons: - * Might be more cluttered, as all the prefixes are together - * Inability to use same prefixes for different arguments across entities + * **Pros**: Prefixes are shared universally, making it more consistent across entities. There is also less code duplication. + * **Cons**: Might be more cluttered, as all the prefixes are together, and inability to use same prefixes for different arguments across entities. * **Alternative 2**: Use different `ArgumentMultimap` for each entity. - * Pros: - * Less cluttered, only prefixes for that entity will be addressed - * Can use prefixes used in different entities for different arguments - * Cons: - * More code duplication, as there are shared prefixes - * Might be harder to track shared prefixes, causing confusion to users + * **Pros**: Less cluttered, only prefixes for that entity will be addressed. Prefixes used in different entities can also be used for different arguments. + * **Cons**: More code duplication, as there are shared prefixes. Might be harder to track shared prefixes, causing confusion to users.
@@ -582,37 +547,26 @@ Context: The `ArgumentMultimap` is used across different entities. **Aspect: How to show appointment and person lists**
-Context: There are two entity types (appointment and person) being managed in DocTrack +Context: There are two entity types (appointment and person) being managed in DocTrack.
-* **Alternative 1 (current choice):** Show lists as two separate panels side by side - * Pros: - * Easier to see all information at once - * Easier to cross reference when doing `add appt` or `edit appt` commands, which may need information about person ID - * Cons: - * More verbose and could result in information overload -* **Alternative 2**: Show only one list at a time, but toggle between the two using a `list appt` or `list person` command - * Pros: - * Information is simpler to digest - * Cons: - * More overhead of handling switching between lists - * Difficult to cross reference when typing certain commands +* **Alternative 1 (current choice):** Show lists as two separate panels side by side. + * **Pros**: Easier to see all information at once, and easier to cross-reference when doing `add appt` + or `edit appt` commands, which may need information about `personId`. + * **Cons**: More verbose and could result in information overload. +* **Alternative 2**: Show only one list at a time, but toggle between the two using a `list appt` or `list person` command. + * **Pros**: Information is simpler to digest. + * **Cons**: More overhead of handling switching between lists, and difficult to cross-reference when typing certain commands.
**Aspect: Color Scheme**
-* **Alternative 1 (current choice):** Create new red, white and gray color scheme - * Pros: - * Creates brand identity - * Makes the GUI more appealling to the target audience - * Cons: - * Constant oversight needed to maintain color scheme in future feature enhancements -* **Alternative 2:** Use the original AB3 gray color schee - * Pros: - * No extra effort needed - * Cons: - * Colors are not appealing - * Colors are not professional and do not suit target audience +* **Alternative 1 (current choice):** Create new red, white and gray color scheme. + * **Pros**: Creates brand identity, makes the GUI more appealing to the target audience. + * **Cons**: Constant oversight needed to maintain color scheme in future feature enhancements. +* **Alternative 2:** Use the original AB3 gray color scheme + * **Pros**: No extra needed to maintain color scheme. + * **Cons**: Colors are not appealing and not professional, they might not suit the target audience.
From 55fde94488f6cdccbbdaa5730c370ea93c95e5e7 Mon Sep 17 00:00:00 2001 From: Rachel Tai Ke Jia Date: Thu, 7 Nov 2024 19:14:22 +0800 Subject: [PATCH 5/8] Specify files --- docs/UserGuide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 0b1eeb0842e..f327654f08f 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -834,12 +834,12 @@ For advanced users, feel free to update patient and appointment data directly by ## **FAQ** **Q**: How is my data stored?
-**A**: Your data is stored in [.json](https://www.json.org/json-en.html) files, located in the `data` folder. The details of patients are stored in the `addressbook.json` file, -while the appointments are stored in the `appointmentbook.json` file. +**A**: Your data is stored in [.json](https://www.json.org/json-en.html) files, located in the `data` +folder. The details of the persons are stored in the `addressbook.json` file, while the appointments are stored in the `appointmentbook.json` file. Examples: -An example of how the persons are stored: +An example of how the persons are stored in the `addressbook.json` file: ```json { @@ -871,7 +871,7 @@ An example of how the persons are stored: } ``` -An example of how the appointments are stored: +An example of how the appointments are stored in the `appointmentbook.json` file: ```json { From 27ab801a20cc38a70be1b666fb7d8f21cbce528f Mon Sep 17 00:00:00 2001 From: Rachel Tai Ke Jia Date: Thu, 7 Nov 2024 19:57:08 +0800 Subject: [PATCH 6/8] Standardise formatting --- docs/DeveloperGuide.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index fba884ec5a3..d76708974c0 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -377,11 +377,11 @@ Object. **Aspect: How to implement the `find person` and `find appt` commands that allow finding by multiple criteria** - **Alternative 1 (Current choice)**: Create one find command that supports filtering by multiple criteria (name, date) using prefixes. - - Pros: Fast and easy to find by date and name. - - Cons: Confusing syntax from user's perspective. + - **Pros**: Fast and easy to find by date and name. + - **Cons**: Confusing syntax from user's perspective. - **Alternative 2**: Create different find commands, find by date, find by name etc. - - Pros: Much easy in terms of user experience. - - Cons: More repeated code for each command. + - **Pros**: Much easy in terms of user experience. + - **Cons**: More repeated code for each command.
@@ -398,7 +398,7 @@ Object. **Aspect: Whether to implement case sensitivity in matching for search terms** - **Alternative 1 (Current choice)**: Implement case-insensitive matching for search terms. - **Pros**: Enhances user experience by allowing searches to ignore case differences. - - **Cons**: Slightly more processing required to normalize case .during search + - **Cons**: Slightly more processing required to normalise the case during searches. - **Alternative 2**: Implement case-sensitive matching for search terms. - **Pros**: Potentially faster searches, as no additional case normalization is required. - **Cons**: Reduces user-friendliness. @@ -478,11 +478,11 @@ When a user types a `help` command, the DocTrack application will display a `Hel ### Data storage and files -**Aspect: Save patient and appointment data in:** +**Aspect: Save patient and appointment data in**
* **Alternative 1 (current choice):** two different files, patient data in `data/addressbook.json` and appointment data in `data/appointmentbook.json`. * **Pros**: More organised file management, with a quicker read and write times for each file. - * **Cons**: Higher chance of inconsistencies between patient and appointment data. + * **Cons**: Higher chance of inconsistencies between patient and appointment data. * **Alternative 2:** one single file named `data/addressbook.json` * **Pros**: Simplicity and convenience of one file for all information. * **Cons**: Slower read and write times for file, especially if the user is only accessing one of patient or appointment data. @@ -496,7 +496,7 @@ is not specified, it would be represented as `"null"`, in the `appointmentbook.j
-**Aspect: When the data is updated in the `.json` file:** +**Aspect: When the data is updated in the `.json` file**
* **Alternative 1 (current choice):** Automatically save all changes after any command that changes the data. * **Pros**: Simplifies the process for the user, without needing to save manually. @@ -509,7 +509,7 @@ is not specified, it would be represented as `"null"`, in the `appointmentbook.j ### Parsing -**Aspect: How to parse the commands:** +**Aspect: How to parse the commands**
Context: The commands (other than the general) have the command format: `COMMAND ENTITY_TYPE ENTITY_ARGS`
@@ -522,7 +522,7 @@ Context: The commands (other than the general) have the command format: `COMMAND
-**Aspect: Command format (with or without prefixes):** +**Aspect: Command format (with or without prefixes)**
* **Alternative 1 (current choice):** Use prefixes. * **Pros**: Easier to identify markers for each parameter, and prefixes allow for free positioning of arguments. @@ -533,7 +533,7 @@ Context: The commands (other than the general) have the command format: `COMMAND
-**Aspect: The use of `ArgumentMultimap` across different entities:** +**Aspect: The use of `ArgumentMultimap` across different entities** * **Alternative 1 (current choice):** Use the same `ArgumentMultimap` for all entities. * **Pros**: Prefixes are shared universally, making it more consistent across entities. There is also less code duplication. * **Cons**: Might be more cluttered, as all the prefixes are together, and inability to use same prefixes for different arguments across entities. From 02883c68d6b474e0ff983871c695e29fed358e14 Mon Sep 17 00:00:00 2001 From: Rachel Tai Ke Jia Date: Thu, 7 Nov 2024 19:57:36 +0800 Subject: [PATCH 7/8] Fix typo --- docs/DeveloperGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index d76708974c0..e9dae2438bc 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -1115,7 +1115,7 @@ Our project presented a higher level of complexity compared to AB3. Our project Our project involved substantial effort in several key areas: - **Design and Refactoring**: Extending the AB3 framework to handle two separate entity types required refactoring and designing new classes. - **Command Implementation**: In creating patient- and appointment-specific commands, we implemented additional parser classes and commands. -- **Testing and Debugging**: To ensure robust funtionality, we implemented comprehensive test cases. This was necessary to ensure +- **Testing and Debugging**: To ensure robust functionality, we implemented comprehensive test cases. This was necessary to ensure that each command and feature worked as expected for both entity types. #### Achievements From 2a00e5929f13ad9067a4f25442373f7c275817ea Mon Sep 17 00:00:00 2001 From: Rachel Tai Ke Jia Date: Thu, 7 Nov 2024 20:01:45 +0800 Subject: [PATCH 8/8] Fix formatting --- docs/DeveloperGuide.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index e9dae2438bc..e255f9c0172 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -281,9 +281,7 @@ Object. **Aspect: Whether to implement entity commands as separate commands or through an abstract base command** - **Alternative 1 (Current choice):** Implement an abstract EntityCommand class that specific entity - commands (e.g. `AddPersonCommand`, `AddAppointmentCommand`, `DeletePersonCommand`, - `DeleteAppointmentCommand`) - inherit from. + commands (e.g. `AddPersonCommand`, `AddAppointmentCommand`, `DeletePersonCommand`,`DeleteAppointmentCommand`) inherit from. - **Pros**: Allows for reuse of code logic between entity commands. - **Cons**: Requires additional parsing logic since entity in command must be distinguished (person or appointment), which can add complexity. - **Alternative 2:** Implement each entity command as entirely separate classes. @@ -294,17 +292,19 @@ Object.
**Aspect: What constitutes duplicate person that should not be added or edited into the AddressBook** -- **Alternative 1 (Current choice):** Duplicate person is one that has the same name (case-insensitive) and same phone number as an existing person +- **Alternative 1 (Current choice):** Duplicate person is one that has the same name (case-insensitive) + and same phone number as an existing person. - **Pros**: Name and phone numbers are identifiers that are commonly recognized by users. - **Cons**: Extra logic required to determine equality of different people. -- **Alternative 2:** A duplicate person is defined more loosely or strictly (e.g. by name only) +- **Alternative 2:** A duplicate person is defined more loosely or strictly (e.g. by name only). - **Pros**: Less logic required to determine equality of different people. - **Cons**: Different people could have the same name, but cannot be added into the AddressBook.
**Aspect: What constitutes duplicate appointment that should not be added or edited into the AppointmentBook** -- **Alternative 1 (Current choice):** Duplicate appointment is one that has same person, date and time, and appointment type as an existing appointment +- **Alternative 1 (Current choice):** Duplicate appointment is one that has same person, date and time, + and appointment type as an existing appointment. - **Pros**: Provides a rule to avoid scheduling conflicts of same person. - **Cons**: Extra logic required to determine equality of different appointments. - **Alternative 2:** Define duplicates with only the date and time @@ -355,7 +355,6 @@ Object. - **Alternative 1 (Current choice):** Use the index of the person / appointment in the list. - **Pros**: Enables efficient retrieval directly from the list, simplifying implementation. - **Cons**: Entity indexes may shift after deletions, which could lead to unintended edits if the user is not aware of changes in ordering. - - **Alternative 2:** Use a unique ID for each entity. - **Pros**: IDs remain consistent regardless of list modifications, ensuring stable reference to the entity. - **Cons**: Implementing ID-based retrieval requires additional logic and may be slower, especially for larger lists.