From 3582a4b055d86c71e53adabc72f694fe157c7e64 Mon Sep 17 00:00:00 2001 From: Nixon Widjaja <69686938+nixonwidjaja@users.noreply.github.com> Date: Thu, 26 Oct 2023 19:19:32 +0800 Subject: [PATCH 1/3] Update UserGuide.md --- docs/UserGuide.md | 76 +++++++++++++++++++++++++++++++---------------- 1 file changed, 51 insertions(+), 25 deletions(-) diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 292dff1a46a..27d6f66eba8 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -62,17 +62,9 @@ HR Insight is a **desktop app for HR people, optimized for use via a Line Interf - Parameters can be in any order.
e.g. if the command specifies `n/NAME p/PHONE_NUMBER`, `p/PHONE_NUMBER n/NAME` is also acceptable. -- Extraneous parameters for commands that do not take in parameters (such as `help`, `list`, `exit` and `clear`) will be ignored.
- e.g. if the command specifies `help 123`, it will be interpreted as `help`. - - If you are using a PDF version of this document, be careful when copying and pasting commands that span multiple lines as space characters surrounding line-breaks may be omitted when copied over to the application. -### Viewing help : `help` - -Shows a message explaining how to access the help page. - -Format: `help` ### Adding an employee: `add` @@ -96,6 +88,21 @@ Examples: - `list` Lists all employees in the employee list. - `list d/Engineering` Lists all employees in the Engineering department. +### Deleting an employee : `delete` + +Delete an employee in the employee list by the specified index. + +Format: `delete INDEX` + +- Deletes the employee at the specified `INDEX`. +- The index refers to the index number shown in the displayed employee list. +- The index **must be a positive integer** 1, 2, 3, …​ + +Examples: + +- `list` followed by `delete 2` deletes the 2nd person in the employee list. +- `find Betsy` followed by `delete 1` deletes the 1st person in the results of the `find` command. + ### Editing an employee's information : `edit` Edits an existing employee in the employee list by the specified index. @@ -111,9 +118,9 @@ Examples: - `edit 1 p/23423423 e/barry@example.com` Edits the phone number and email address of the 1st person to be `23423423` and `barry@example.com` respectively. -### Locating persons by name: `find` +### Finding employees by name: `find` -Finds persons whose names contain any of the given keywords. +Finds employees whose names contain any of the given keywords. Format: `find KEYWORD [MORE_KEYWORDS]` @@ -129,20 +136,11 @@ Examples: - `find John` returns `john` and `John Doe` - `find alex david` returns `Alex Yeoh`, `David Li`
-### Deleting an employee : `delete` - -Delete an employee in the employee list by the specified index. +### Clearing all entries: `clear` -Format: `delete INDEX` +Clear all entries from the employee list. -- Deletes the employee at the specified `INDEX`. -- The index refers to the index number shown in the displayed employee list. -- The index **must be a positive integer** 1, 2, 3, …​ - -Examples: - -- `list` followed by `delete 2` deletes the 2nd person in the employee list. -- `find Betsy` followed by `delete 1` deletes the 1st person in the results of the `find` command. +Format: `clear` ### Managing Employee's Claims: `claim` @@ -217,6 +215,18 @@ Format: `view [n/INDEX] [a/INDEX] [e/INDEX] [p/INDEX] [s/INDEX] [b/INDEX] [d/IN - Examples: - `view` followed by `s/1,2` displays employees with list's index of 1 and 2 respective salaries. +### Undoing previous command: `undo` + +Undo the most recent command that modified the employee list, i.e., `add`, `edit`, `delete`, `leave`, `clear`, `redo` commands. + +Format: `undo` + +### Redoing previous undone command: `redo` + +Redo the most recent command that was undone. + +Format: `redo` + ### Exporting employee's details: `export` Export employee's details into a csv file format. @@ -230,6 +240,19 @@ Format: `export [file_name]` - Examples: - `list` followed by `export all_data` will download all employees' attributes into a csv file. + +### Viewing help : `help` + +Shows a message explaining how to access the help page. + +Format: `help` + +### Exit the app: `exit` + +Exits the app. + +Format: `exit` + ### Saving the data HR Insight data are saved in the hard disk automatically after any command that changes the data. There is no need to save manually. @@ -264,15 +287,18 @@ If your changes to the data file makes its format invalid, HR Insight will disca | Action | Format, Examples | |---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Add** | `add n/NAME p/PHONE_NUMBER e/EMAIL a/ADDRESS s/SALARY b/CLAIM_BUDGET d/DEPARTMENT dob/BIRTH_DATE (YYYY-MM-DD)​`
e.g., `add n/John Doe p/87654321 e/john.doe@gmail.com a/Tokyo s/5000 b/2000 d/Sales dob/1992-07-21` | -| **Clear** | `clear` | +| **List** | `list [d/DEPARTMENT]` | | **Delete** | `delete INDEX`
e.g., `delete 3` | | **Edit** | `edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [s/SALARY] [b/CLAIM_BUDGET] [d/DEPARTMENT] [dob/BIRTH_DATE (YYYY-MM-DD)]`
e.g., `edit 1 p/23423423 e/barry@example.com` | | **Find** | `find KEYWORD [MORE_KEYWORDS]`
e.g., `find James Jake` | -| **List** | `list [d/DEPARTMENT]` | +| **Clear** | `clear` | | **Claim** | `claim INDEX $/CLAIM_AMOUNT`
e.g., `claim 1 $/-500` | | **Add Leave** | `leave INDEX m/MONTHS`
e.g., `leave 1 m/3,-4` | -| **Help** | `help` | | **View Leave** | `view_leave INDEX m/Month d/DEPARTMENT`
e.g.,`view_leave m/10 d/IT` | | **View Birthdays** | `birthday [m/MONTH]`
e.g., `birthday 10` | | **View Attributes** | `view [n/INDEX] [a/INDEX] [e/INDEX] [p/INDEX] [s/INDEX] [b/INDEX] [d/INDEX] [dob/INDEX]`
e.g., `view s/1,2` | +| **Undo** | `undo` | +| **Redo** | `redo` | | **Export Data** | `export [file_name]`
e.g., `export engineering_dept` | +| **Help** | `help` | +| **Exit** | `exit` | From 5203da8af3f21b33cfa29352e02cd5a6993c0469 Mon Sep 17 00:00:00 2001 From: Nixon Widjaja <69686938+nixonwidjaja@users.noreply.github.com> Date: Thu, 26 Oct 2023 20:17:21 +0800 Subject: [PATCH 2/3] Update DeveloperGuide.md --- docs/DeveloperGuide.md | 91 +++++++++++------------------------------- 1 file changed, 23 insertions(+), 68 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index aedbc05adf9..a3102fc9019 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -154,85 +154,40 @@ Classes used by multiple components are in the `seedu.addressbook.commons` packa This section describes some noteworthy details on how certain features are implemented. -### \[Proposed\] Undo/redo feature +### Undo/redo feature #### Proposed Implementation -The proposed undo/redo mechanism is facilitated by `VersionedAddressBook`. It extends `AddressBook` with an undo/redo history, stored internally as an `addressBookStateList` and `currentStatePointer`. Additionally, it implements the following operations: +The implementation involves creating an `AddressBookList` class which extends from `ArrayList` to store the history of `AddressBook`. +`AddressBookList` also stores an integer `index` as a pointer to the current `AddressBook` and an `ArrayList` of commands input by the user called `pastCommands`. -* `VersionedAddressBook#commit()` — Saves the current address book state in its history. -* `VersionedAddressBook#undo()` — Restores the previous address book state from its history. -* `VersionedAddressBook#redo()` — Restores a previously undone address book state from its history. +Whenever `AddressBook` is changed, it will store its copy and append it to the `AddressBookList`, increment `index` by 1, and append the command +which modifies the `AddressBook` to `pastCommands`. -These operations are exposed in the `Model` interface as `Model#commitAddressBook()`, `Model#undoAddressBook()` and `Model#redoAddressBook()` respectively. +When `AddressBookList#undo()` is called, the current `AddressBook` changes to `AddressBookList.get(index - 1)` and `index` is decremented by 1. +If the current `index` is at 0, `AddressBookList` will throw an error stating there is no command to undo. -Given below is an example usage scenario and how the undo/redo mechanism behaves at each step. +If after undoing some command the user decides to modify the `AddressBook` with new commands, `AddressBookList` will overwrite all `AddressBook` after that particular state. +For example, currently `AddressBookList` has 10 `AddressBook` in it and the current state is at `AddressBookList.get(5)`. Then, the user adds an employee. All `AddressBook` +at index 6 to 9 will be deleted and `AddressBookList.get(6)` will now contain the new `AddressBook` that has the new employee in it. -Step 1. The user launches the application for the first time. The `VersionedAddressBook` will be initialized with the initial address book state, and the `currentStatePointer` pointing to that single address book state. +When `AddressBookList#redo()` is called, the current `AddressBook` changes to `AddressBookList.get(index + 1)` and `index` is incremented by 1. +If the current `index` is at `AddressBookList.size() - 1`, `AddressBookList` will throw an error stating there is no command to redo. -![UndoRedoState0](images/UndoRedoState0.png) +`AddressBookList` sits in `ModelManager` class where it will be modifed whenever `ModelManager#addPerson()`, `ModelManager#deletePerson()`, and `ModelManager#setPerson()` +are called, i.e., whenever `AddressBook` is changed. `ModelManager#undo()` will call `AddressBookList#undo()` and `ModelManager#redo()` will call `AddressBookList#redo()`. -Step 2. The user executes `delete 5` command to delete the 5th person in the address book. The `delete` command calls `Model#commitAddressBook()`, causing the modified state of the address book after the `delete 5` command executes to be saved in the `addressBookStateList`, and the `currentStatePointer` is shifted to the newly inserted address book state. -![UndoRedoState1](images/UndoRedoState1.png) +#### Design Considerations -Step 3. The user executes `add n/David …​` to add a new person. The `add` command also calls `Model#commitAddressBook()`, causing another modified address book state to be saved into the `addressBookStateList`. - -![UndoRedoState2](images/UndoRedoState2.png) - -
:information_source: **Note:** If a command fails its execution, it will not call `Model#commitAddressBook()`, so the address book state will not be saved into the `addressBookStateList`. - -
- -Step 4. The user now decides that adding the person was a mistake, and decides to undo that action by executing the `undo` command. The `undo` command will call `Model#undoAddressBook()`, which will shift the `currentStatePointer` once to the left, pointing it to the previous address book state, and restores the address book to that state. - -![UndoRedoState3](images/UndoRedoState3.png) - -
:information_source: **Note:** If the `currentStatePointer` is at index 0, pointing to the initial AddressBook state, then there are no previous AddressBook states to restore. The `undo` command uses `Model#canUndoAddressBook()` to check if this is the case. If so, it will return an error to the user rather -than attempting to perform the undo. - -
- -The following sequence diagram shows how the undo operation works: - -![UndoSequenceDiagram](images/UndoSequenceDiagram.png) - -
:information_source: **Note:** The lifeline for `UndoCommand` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram. - -
- -The `redo` command does the opposite — it calls `Model#redoAddressBook()`, which shifts the `currentStatePointer` once to the right, pointing to the previously undone state, and restores the address book to that state. - -
:information_source: **Note:** If the `currentStatePointer` is at index `addressBookStateList.size() - 1`, pointing to the latest address book state, then there are no undone AddressBook states to restore. The `redo` command uses `Model#canRedoAddressBook()` to check if this is the case. If so, it will return an error to the user rather than attempting to perform the redo. - -
- -Step 5. The user then decides to execute the command `list`. Commands that do not modify the address book, such as `list`, will usually not call `Model#commitAddressBook()`, `Model#undoAddressBook()` or `Model#redoAddressBook()`. Thus, the `addressBookStateList` remains unchanged. - -![UndoRedoState4](images/UndoRedoState4.png) - -Step 6. The user executes `clear`, which calls `Model#commitAddressBook()`. Since the `currentStatePointer` is not pointing at the end of the `addressBookStateList`, all address book states after the `currentStatePointer` will be purged. Reason: It no longer makes sense to redo the `add n/David …​` command. This is the behavior that most modern desktop applications follow. - -![UndoRedoState5](images/UndoRedoState5.png) - -The following activity diagram summarizes what happens when a user executes a new command: - - - -#### Design considerations: - -**Aspect: How undo & redo executes:** - -* **Alternative 1 (current choice):** Saves the entire address book. +* **Alternative 1 (current choice):** Stores the entire address book. * Pros: Easy to implement. * Cons: May have performance issues in terms of memory usage. -* **Alternative 2:** Individual command knows how to undo/redo by - itself. - * Pros: Will use less memory (e.g. for `delete`, just save the person being deleted). - * Cons: We must ensure that the implementation of each individual command are correct. +* **Alternative 2:** Stores only the changes between address book versions. For example, only store the employee being added when the user adds an employee. + * Pros: Less memory. + * Cons: More complications on the logic side: undoing `add` = `delete`, undoing `clear` = `add` back all employees, etc. -_{more aspects and alternatives to be added}_ ### Export Data Feature @@ -246,7 +201,7 @@ The primary operations that aid in this mechanism are: * `generateFile()` -- Creates a directory for exported CSVs and a File object containing the filename imposed by the user. * `PrintWri -#### Design considerations: +#### Design Considerations **Aspect: How undo & redo executes:** @@ -291,7 +246,7 @@ The following activity diagram summarizes what happens when a user attempts to e -#### Design considerations: +#### Design Considerations **Aspect: How exports executes:** @@ -710,8 +665,8 @@ birthdays by month. * Pros: Allows the user to view birthdays in a broader range. * Cons: User cannot view birthdays that occur across multiple months * **Alternative 2**: Allows the user to view birthdays in multiple months - * Pros: User will be able to view birthdays across multiple months with only one use of the command. - * (e.g. `birthday m/2,3` returns all birthdays in February and March ) + * Pros: User will be able to view birthdays across multiple months with only one use of the command.
+ (e.g. `birthday m/2,3` returns all birthdays in February and March ) * Cons: We must ensure that every month given by the user is valid and mention which months have no birthdays. -------------------------------------------------------------------------------------------------------------------- From 773483e199b364884578432180ef22920cb0b471 Mon Sep 17 00:00:00 2001 From: Sher Yew Date: Thu, 26 Oct 2023 21:38:02 +0800 Subject: [PATCH 3/3] Fixed DG --- docs/DeveloperGuide.md | 106 +++++++++++++++-------------------------- docs/UserGuide.md | 2 +- 2 files changed, 40 insertions(+), 68 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index a3102fc9019..78cc00e5a7e 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -188,34 +188,6 @@ are called, i.e., whenever `AddressBook` is changed. `ModelManager#undo()` will * Pros: Less memory. * Cons: More complications on the logic side: undoing `add` = `delete`, undoing `clear` = `add` back all employees, etc. - -### Export Data Feature - -#### Proposed Implementation - -The proposed export mechanism is facilitated by `AddressBook`. Additionally, the operation is exposed in the Model interface which allows users to perform `filter` operation to discard selected portions of the Model interface before exporting. - -The primary operations that aid in this mechanism are: -* `getFilteredPersonList()` -- Used in conjunction with `filter` operation so that the model will display the latest Persons of interest. -* `generateListPeople()` -- Performs extracting of Person objects from the latest model and obtaining the Person's attributes. -* `generateFile()` -- Creates a directory for exported CSVs and a File object containing the filename imposed by the user. -* `PrintWri - -#### Design Considerations - -**Aspect: How undo & redo executes:** - -* **Alternative 1 (current choice):** Saves the entire address book. - * Pros: Easy to implement. - * Cons: May have performance issues in terms of memory usage. - -* **Alternative 2:** Individual command knows how to undo/redo by - itself. - * Pros: Will use less memory (e.g. for `delete`, just save the person being deleted). - * Cons: We must ensure that the implementation of each individual command are correct. - -_{more aspects and alternatives to be added}_ - ### Export Data Feature #### Proposed Implementation @@ -258,6 +230,45 @@ The following activity diagram summarizes what happens when a user attempts to e * Pros: User can perform better categorisation of data according to organisation's needs. * Cons: Harder to implement since program needs to know which locations are out-of-bounds. Example: src files. +### Birthday Feature + +#### Implementation + +The birthday feature extends HR Insight by allowing the user to view birthdays in a given month. +This operation is exposed in the Command Interface as `Command#BirthdayCommand`. + +Given below is an example usage scenario and how the birthday mechanism behaves at each step. + +Step 1: The user launches the application for the first time. + +Step 2: The user executes `add n/John Doe ... ` to add a new employee. + +Step 3: After adding a few employees into the application, he/she wants to view the birthdays in the month of January +to prepare the birthday celebrations in advance. The `birthday m/1` command will display all employees with birthdays +in the month of January. + +Step 4: The user then realises that today is the first day of a new month and he/she wants to view which employees +have birthdays in the current month. The `birthday` command without providing the month will display all employees with +birthdays in the current month. + +The following sequence diagram shows how the `birthday` command works: + +![SequenceDiagram](images/BirthdayCommand.png) + +### Reasoning +The birthday command is designed to show users birthday by month instead of week/day as month gives the user a broader +range to work with. Furthermore, it is also a common practice for companies to have 1 celebration for all employees' +birthdays in a month rather than having multiple individual celebrations. Hence, this feature is designed to show +birthdays by month. + +### Aspect: How birthday executes: +* **Alternative 1 (current choice)** : Allows the user to view birthday in a month + * Pros: Allows the user to view birthdays in a broader range. + * Cons: User cannot view birthdays that occur across multiple months +* **Alternative 2**: Allows the user to view birthdays in multiple months + * Pros: User will be able to view birthdays across multiple months with only one use of the command.
+ (e.g. `birthday m/2,3` returns all birthdays in February and March ) + * Cons: We must ensure that every month given by the user is valid and mention which months have no birthdays. -------------------------------------------------------------------------------------------------------------------- @@ -629,45 +640,6 @@ The following activity diagram summarizes what happens when a user attempts to e * Pros: User can perform better categorisation of data according to organisation's needs. * Cons: Harder to implement since program needs to know which locations are out-of-bounds. Example: src files. -### \[Implemented\] Birthday Feature - -#### Implementation - -The birthday feature extends HR Insight by allowing the user to view birthdays in a given month. -This operation is exposed in the Command Interface as `Command#BirthdayCommand`. - -Given below is an example usage scenario and how the birthday mechanism behaves at each step. - -Step 1: The user launches the application for the first time. - -Step 2: The user executes `add n/John Doe ... ` to add a new employee. - -Step 3: After adding a few employees into the application, he/she wants to view the birthdays in the month of January -to prepare the birthday celebrations in advance. The `birthday m/1` command will display all employees with birthdays -in the month of January. - -Step 4: The user then realises that today is the first day of a new month and he/she wants to view which employees -have birthdays in the current month. The `birthday` command without providing the month will display all employees with -birthdays in the current month. - -The following sequence diagram shows how the `birthday` command works: - -![SequenceDiagram](/Users/remuslum/Downloads/CS2103_tP/tp/docs/images/BirthdayCommand.png) - -### Reasoning -The birthday command is designed to show users birthday by month instead of week/day as month gives the user a broader -range to work with. Furthermore, it is also a common practice for companies to have 1 celebration for all employees' -birthdays in a month rather than having multiple individual celebrations. Hence, this feature is designed to show -birthdays by month. - -### Aspect: How birthday executes: -* **Alternative 1 (current choice)** : Allows the user to view birthday in a month - * Pros: Allows the user to view birthdays in a broader range. - * Cons: User cannot view birthdays that occur across multiple months -* **Alternative 2**: Allows the user to view birthdays in multiple months - * Pros: User will be able to view birthdays across multiple months with only one use of the command.
- (e.g. `birthday m/2,3` returns all birthdays in February and March ) - * Cons: We must ensure that every month given by the user is valid and mention which months have no birthdays. -------------------------------------------------------------------------------------------------------------------- ## **Documentation, logging, testing, configuration, dev-ops** diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 27d6f66eba8..31f1d7ba06b 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -247,7 +247,7 @@ Shows a message explaining how to access the help page. Format: `help` -### Exit the app: `exit` +### Exiting the app: `exit` Exits the app.