Skip to content

Commit

Permalink
Merge pull request #298 from yucongkoo/branch-dev-guide
Browse files Browse the repository at this point in the history 
Update DG to include Planned Enhancements for tag and insurance command
  • Loading branch information
@Jweewee
Jweewee authored Nov 9, 2023
2 parents 0d86682 + 561003a commit 4ddf86a
Show file tree
Hide file tree
Showing 7 changed files with 126 additions and 146 deletions.
165 changes: 51 additions & 114 deletions docs/DeveloperGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,16 +155,6 @@ The `Model` component,

<div style="page-break-after: always;"></div>

<box type="info" seamless>

**Note:** An alternative (arguably, a more OOP) model is given below. It has a `Tag` list 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.<br>

<puml src="diagrams/BetterModelClassDiagram.puml" width="450" />

</box>

<div style="page-break-after: always;"></div>

## Storage component

**API** : [`Storage.java`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/storage/Storage.java)
Expand All @@ -191,6 +181,10 @@ This section describes some noteworthy details on how certain features are imple
This feature allows users to assign tags to / remove tags from customers in EzContact, increasing the recognizability
of customers to users.

The activity diagram below shows the action sequence of updating the tags of a customer.

<puml src="diagrams/tag-feature/ExecuteActivityDiagram.puml"/>

### Implementation

###### **Implementing `Tag`**
Expand Down Expand Up @@ -242,6 +236,10 @@ taking `parse(1 at/tall dt/short at/handsome)` call to the `TagCommandParser` as

###### **Implementing `TagCommand`**

The following class diagram illustrates how a `TagCommand` hold information required for its execution.

<puml src= "diagrams/tag-feature/TagCommandClassDiagram.puml" />

`TagCommand` plays the role of executing the tag command on a `Model`, it will update the `Model` accordingly to
reflect the changes after the tag command completes its execution. Note that if there are conflicting tags(i.e. there
is a common tag to add and delete), the command execution will fail.<br/>
Expand Down Expand Up @@ -655,102 +653,6 @@ alternative 1 is preferred due to its user-friendliness.

<div style="page-break-after: always;"></div>

## \[Proposed\] 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:

* `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.

These operations are exposed in the `Model` interface as `Model#commitAddressBook()`, `Model#undoAddressBook()` and `Model#redoAddressBook()` respectively.

Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.

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.

<puml src="diagrams/UndoRedoState0.puml" alt="UndoRedoState0" />

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.

<puml src="diagrams/UndoRedoState1.puml" alt="UndoRedoState1" />

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`.

<puml src="diagrams/UndoRedoState2.puml" alt="UndoRedoState2" />

<box type="info" seamless>

**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`.

</box>

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.

<puml src="diagrams/UndoRedoState3.puml" alt="UndoRedoState3" />


<box type="info" seamless>

**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.

</box>

<div style="page-break-after: always;"></div>

The following sequence diagram shows how the undo operation works:

<puml src="diagrams/UndoSequenceDiagram.puml" alt="UndoSequenceDiagram" />

<box type="info" seamless>

**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.

</box>

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.

<box type="info" seamless>

**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.

</box>

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.

<puml src="diagrams/UndoRedoState4.puml" alt="UndoRedoState4" />

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.

<puml src="diagrams/UndoRedoState5.puml" alt="UndoRedoState5" />

The following activity diagram summarizes what happens when a user executes a new command:

<puml src="diagrams/CommitActivityDiagram.puml" width="250" />

### 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}_

## \[Proposed\] Data archiving

_{Explain here how the data archiving feature will be implemented}_


--------------------------------------------------------------------------------------------------------------------

# **Documentation, logging, testing, configuration, dev-ops**
Expand Down Expand Up @@ -982,7 +884,7 @@ Priorities: High - `* * *`, Medium - `* *`, Low - `*`
**Mss:**<br/>
&emsp;1. User requests to list out the customers.<br/>
&emsp;2. System displays the requested list of customers to the user.<br/>
&emsp;3. User enters index of targeted customer and information of tags to update.<br/>
&emsp;3. User enters index of targeted customer and information of tags to add or delete.<br/>
&emsp;4. System updates the tags of the specified customer accordingly.<br/>
&emsp;5. System displays the details of the updated customer.<br/>
&emsp;Use case ends.<br/>
Expand Down Expand Up @@ -1043,12 +945,44 @@ Priorities: High - `* * *`, Medium - `* *`, Low - `*`

This section covers the enhancements we plan to implement in the future.

#### Enhancement
(details of the enhancement...)
#### Enhancement 1 : Deletion of all tags(and insurances) in a single command

**Feature flaw:** <br/>
As a customer might have many tags, and they could potentially want to remove all the
tags in one command, they would have to type out all the tags separately in order to achieve that.

**Proposed enhancement:**<br/>
We provide a convenient way for users to delete all the tags in one command by adding an optional parameter
to the command. The updated command format would be as follows: <br/>
`tag <index> [at/<tags to add>]... [dt/<tags to add>]... [dat/deleteall]`.

Justifications:
* As deleting all the tags is a destructive action, we require users to specify the `dat/` prefix to indicate
their interest in deleting all tags, and `deleteall` value to the prefix to serve as a confirmation of this
destructive command.

**Feature flaw:** (feature flaw it fixes...)
Updated behaviours (original behaviours of tag still hold):
* When a `dat/` prefix is supplied, there should not be any `at/` or `dt/` prefix supplied in the same command, if there
is, a format error message will be shown to the user.
* If the value provided to parameter `dat/` is not `deleteall`, show an error message to users, indicating that
they should supply the `deleteall` value to `dat/` in order to confirm the deletion.

(explain how enhancement fixes the flaws... )
**Examples:**<br/>
* `tag 1 dat/deleteall`<br/>
Expected: All the tags of customer at index 1 is deleted, a `successfully deleted all tags` message is shown to user.

* `tag 1 at/tall dat/deleteall`<br/>
Expected: Error, an error message showing the usage of tag command is shown to the user.

* `tag 1 dat/delete`<br/>
Expected: Error, an error message informing the user that they should input `deleteall` to confirm the deletion of all tags
is shown to the user.

**Additional notes:**<br/>
As the behaviour of the `insurance` command is nearly identical to `tag` command, this planned enhancement applies to
the `insurance` command too, the proposed enhancements and behaviours will be identical. The following is the updated
command format for `insurance` command:<br/>
`insurance <index> [ai/<insurance to add>]... [di/<insurance to delete>]... [dai/deleteall]`

--------------------------------------------------------------------------------------------------------------------
<div style="page-break-after: always;"></div>
Expand Down Expand Up @@ -1134,13 +1068,16 @@ Prerequisite : -
Expected : The tags assigned to the customer at index 1 will be updated accordingly(adds `tall` and `fat` tag, deletes `short` and `skinny` tag).

1. Test case : `tag 0 at/tall`<br/>
Expected : No customer is updated. Error details shown in the status message(format error since the index is not a positive integer).
Expected : Error, details shown in the status message(format error since the index is not a positive integer).

1. Test case : `tag 1`<br/>
Expected : No customer is updated. Error details shown in the status message(format error since no tag to update is provided).
Expected : Error, details shown in the status message(format error since no tag to update is provided).

1. Test case: `tag 1 at/tall dt/tall`<br/>
Expected : No customer is updated. Error details shown in the status message(conflicting tags).
Expected : Error, details shown in the status message(conflicting tags).

1. Test case: `tag 1 dt/dsajdkl`, the tag to delete does not exist in cutomer 1<br/>
Expected: Error, details shown in the status message(customer not updated).

<br/>

Expand Down
54 changes: 27 additions & 27 deletions docs/UserGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,8 @@ embark on your journey of using EzContact.
2. Download the latest `EzContact.jar` from [here](https://github.com/AY2324S1-CS2103T-W16-2/tp/releases).

3. Copy the file to the folder you want to use as the _home folder_ for your EzContact.
4. Open up command prompt `cmd` and move to the application's directory by using `cd <directory>`.
5. After reaching the directory, execute the command `java -jar EzContact.jar`. The GUI similar to the below should appear in a few seconds.
4. Open a command terminal, `cd` into the folder you put the jar file in
5. After reaching the folder, execute the command `java -jar EzContact.jar`. The GUI similar to the below should appear in a few seconds.
Note how the app contains some sample data.<br><br>![Ui](images/Ui.png)
5. Type the command in the [Command Box](#ui-layout-description) and press Enter to execute it.
6. Refer to the [Features](#features) below for details of each command.
Expand Down Expand Up @@ -96,6 +96,9 @@ click [here](#prefix-to-full-name-prefix-translation-table) to see a full table
* Extraneous parameters for commands that do not take in parameters (such as `help`, `list`, `exit` and `clear`) will be ignored.<br>
e.g. if the command is `help 123`, it will be interpreted as `help`.

* Unless otherwise stated, when specifying restrictions on number of characters, spaces in between words
are included in the count, while leading and trailing spaces are excluded.

* 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.
</div>

Expand Down Expand Up @@ -130,7 +133,8 @@ Adds a new customer with the respective details to EzContact.
**Examples:**

* `add n/Ryan Ong p/64238876 e/[email protected] t/tall t/skinny t/wears spectacles pr/medium i/car insurance`</br>
Adds the following [Customer Card](#ui-layout-description) to the [Customer List Panel](#ui-layout-description)
Adds the following [Customer Card](#ui-layout-description) to the [Customer List Panel](#ui-layout-description). Note how omission of optional parameters
are allowed.

![AddEg2](images/add-command-examples/example2.png)

Expand Down Expand Up @@ -265,9 +269,9 @@ it will match a customer named `Song Guo Xuan` because all the specified keyword
**Description:**

* Updates the tags assigned to the customer at `<index>` in the displayed customer list.
* Tags are not case-sensitive (i.e. `friends` is equivalent to `FriEnds`), the UI will display tags in lower case.
* Contiguous spaces will be treated as 1 single space.
* Duplicate tags to add/delete will be ignored by EzContact.
* Tags are not case-sensitive (i.e. `friends` is equivalent to `FriEnds`), the GUI will display tags in lower case.
* Contiguous spaces in between words will be treated as 1 single space.
* **Duplicate tags** to add/delete will be **ignored** by EzContact.
* **Adding an existing tag** or **deleting a non-existing tag** will be **ignored** by EzContact.

<box type="warning" seamless>
Expand Down Expand Up @@ -447,6 +451,8 @@ After:
* This allows you to keep track of all your customers' appointment dates all within the same app
* If you wish to delete the customer's appointment, use the command `deleteappt`

<box type="warning" seamless>

**Caution:**

* The customer must not have a current appointment
Expand All @@ -456,6 +462,9 @@ After:
* `<time>` format must be in 24h HH:MM format
* `<venue>` cannot be longer than 30 characters


</box>

**Examples:**

* `addappt 1 d/2025-12-12` adds an appointment on 12 Dec 2025 for the first customer in the displayed list
Expand Down Expand Up @@ -484,6 +493,8 @@ After:
* Deletes a customer's appointment at `<index>` in the displayed customer list.\
* Used when the appointment has been cancelled.

<box type="warning" seamless>

**Caution:**

* The customer must have a current appointment
Expand Down Expand Up @@ -516,11 +527,15 @@ After:
* Deletes the current appointment.
* Use to keep track of the number of completed appointments with the customer

<box type="warning" seamless>

**Caution:**
* `<index>` should **only be one of** the indices shown in the displayed list
* The customer at `<index>` must have a current appointment.
* This cannot be undone.
*

</box>

**Example:**
* `markappt 1` increments the appointment counter of the first customer in the displayed list.

Expand All @@ -545,11 +560,15 @@ After:
* Decrements the customer's completed appointments count at `<index>` by 1.
* Use to reduce the appointment count of customers as needed.

<box type="warning" seamless>

**Caution:**
* `<index>` should **only be one of** the indices shown in the displayed list
* This cannot be undone.
* The current appointment count must be greater than 0.

</box>

*Examples:*
* `unmarkappt 1` decrements the appointment counter of the first customer in the displayed list by 1.

Expand All @@ -563,12 +582,11 @@ After:
**Description**
* Shows a list of all customers in EZContact and the size of the list.
* You can return to viewing your full client list after executing a `find` command.

**Caution:**
* No parameter is needed for this command, all parameter provided will be ignored.

**Example**:
* `list` shows a list of all existing customers and the size of the list.
* `list 123` will be interpreted as `list`.

<br/>

Expand All @@ -582,14 +600,8 @@ After:

**Description:**
* Clears the customer list.

<box type="warning" seamless>

**Caution:**
* No parameter is needed for this command, all parameter provided will be ignored.

</box>

**Examples:**

* `clear` clears the customer list in EzContact.
Expand All @@ -604,14 +616,8 @@ After:

**Description:**
* Opens the help window.

<box type="warning" seamless>

**Caution:**
* No parameter is needed for this command, all parameter provided will be ignored.

</box>

**Examples:**

* `help` opens the help window.
Expand All @@ -630,14 +636,8 @@ After:

**Description:**
* Exits the program.

<box type="warning" seamless>

**Caution:**
* No parameter is needed for this command, all parameter provided will be ignored.

</box>

**Examples:**

* `exit` exits EzContact.
Expand Down
Loading

0 comments on commit 4ddf86a

Please sign in to comment.