Skip to content

Commit

Permalink
Merge pull request AY2324S2-CS2103T-T15-1#230 from alfaloo/documentation
Browse files Browse the repository at this point in the history 
Add more info/tip bands
  • Loading branch information
@ararchch
ararchch authored Apr 13, 2024
2 parents 3ccd5ca + d77cd9c commit 405a225
Show file tree
Hide file tree
Showing 2 changed files with 100 additions and 90 deletions.
174 changes: 87 additions & 87 deletions docs/DeveloperGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -529,140 +529,140 @@ Why is this implemented this way?
2. The rationale behind excluding substring searches for `appointment`(s) is that if a hospital clerk is searching for a specific `patient`'s scheduled `appointment`(s), the hospital clerk already has the `patient`'s unique `Nric` and hence including substring querying is irrelevant.


[//]: # (### \[Proposed\] Undo/redo feature)
### \[Proposed\] Undo/redo feature

[//]: # ()
[//]: # (#### Proposed Implementation)

[//]: # ()
[//]: # (The proposed undo/redo mechanism is facilitated by `VersionedMediCLI`. It extends `MediCLI` with an undo/redo history, stored internally as an `mediCLIStateList` and `currentStatePointer`. Additionally, it implements the following operations:)
#### Proposed Implementation

[//]: # ()
[//]: # (* `VersionedMediCLI#commit()` — Saves the current MediCLI state in its history.)

[//]: # (* `VersionedMediCLI#undo()` — Restores the previous MediCLI state from its history.)
The proposed undo/redo mechanism is facilitated by `VersionedMediCLI`. It extends `MediCLI` with an undo/redo history, stored internally as an `mediCLIStateList` and `currentStatePointer`. Additionally, it implements the following operations:

[//]: # (* `VersionedMediCLI#redo()` — Restores a previously undone MediCLI state from its history.)

[//]: # ()
[//]: # (These operations are exposed in the `Model` interface as `Model#commitMediCLI()`, `Model#undoMediCLI()` and `Model#redoMediCLI()` respectively.)
* `VersionedMediCLI#commit()` — Saves the current MediCLI state in its history.

[//]: # ()
[//]: # (Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.)
* `VersionedMediCLI#undo()` — Restores the previous MediCLI state from its history.

[//]: # ()
[//]: # (Step 1. The user launches the application for the first time. The `VersionedMediCLI` will be initialized with the initial MediCLI state, and the `currentStatePointer` pointing to that single MediCLI state.)
* `VersionedMediCLI#redo()` — Restores a previously undone MediCLI state from its history.

[//]: # ()
[//]: # (![UndoRedoState0](images/UndoRedoState0.png))

[//]: # ()
[//]: # (Step 2. The user executes `delete 5` command to delete the 5th person in the MediCLI. The `delete` command calls `Model#commitMediCLI()`, causing the modified state of the MediCLI after the `delete 5` command executes to be saved in the `mediCLIStateList`, and the `currentStatePointer` is shifted to the newly inserted address book state.)
These operations are exposed in the `Model` interface as `Model#commitMediCLI()`, `Model#undoMediCLI()` and `Model#redoMediCLI()` respectively.

[//]: # ()
[//]: # (![UndoRedoState1](images/UndoRedoState1.png))

[//]: # ()
[//]: # (Step 3. The user executes `addpatient i/S1234567A n/John Doe d/2003-01-30 p/98765432` to add a new person. The `add` command also calls `Model#commitMediCLI()`, causing another modified MediCLI state to be saved into the `mediCLIStateList`.)
Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.

[//]: # ()
[//]: # (![UndoRedoState2](images/UndoRedoState2.png))

[//]: # ()
[//]: # (<div markdown="span" class="alert alert-info">:information_source: **Note:** If a command fails its execution, it will not call `Model#commitMediCLI&#40;&#41;`, so the MediCLI state will not be saved into the `mediCLIStateList`.)
Step 1. The user launches the application for the first time. The `VersionedMediCLI` will be initialized with the initial MediCLI state, and the `currentStatePointer` pointing to that single MediCLI state.

[//]: # ()
[//]: # (</div>)

[//]: # ()
[//]: # (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#undoMediCLI&#40;&#41;`, which will shift the `currentStatePointer` once to the left, pointing it to the previous MediCLI state, and restores the MediCLI to that state.)
![UndoRedoState0](images/UndoRedoState0.png)

[//]: # ()
[//]: # (![UndoRedoState3]&#40;images/UndoRedoState3.png&#41;)

[//]: # ()
[//]: # (<div markdown="span" class="alert alert-info">:information_source: **Note:** If the `currentStatePointer` is at index 0, pointing to the initial MediCLI state, then there are no previous MediCLI states to restore. The `undo` command uses `Model#canUndoMediCLI&#40;&#41;` to check if this is the case. If so, it will return an error to the user rather)
Step 2. The user executes `delete 5` command to delete the 5th person in the MediCLI. The `delete` command calls `Model#commitMediCLI()`, causing the modified state of the MediCLI after the `delete 5` command executes to be saved in the `mediCLIStateList`, and the `currentStatePointer` is shifted to the newly inserted address book state.

[//]: # (than attempting to perform the undo.)

[//]: # ()
[//]: # (</div>)
![UndoRedoState1](images/UndoRedoState1.png)

[//]: # ()
[//]: # (The following sequence diagram shows how an undo operation goes through the `Logic` component:)

[//]: # ()
[//]: # (![UndoSequenceDiagram]&#40;images/UndoSequenceDiagram-Logic.png&#41;)
Step 3. The user executes `addpatient i/S1234567A n/John Doe d/2003-01-30 p/98765432` to add a new person. The `add` command also calls `Model#commitMediCLI()`, causing another modified MediCLI state to be saved into the `mediCLIStateList`.

[//]: # ()
[//]: # (<div markdown="span" class="alert alert-info">:information_source: **Note:** The lifeline for `UndoCommand` should end at the destroy marker &#40;X&#41; but due to a limitation of PlantUML, the lifeline reaches the end of diagram.)

[//]: # ()
[//]: # (</div>)
![UndoRedoState2](images/UndoRedoState2.png)

[//]: # ()
[//]: # (Similarly, how an undo operation goes through the `Model` component is shown below:)

[//]: # ()
[//]: # (![UndoSequenceDiagram]&#40;images/UndoSequenceDiagram-Model.png&#41;)
<div markdown="span" class="alert alert-info">:information_source: **Note:** If a command fails its execution, it will not call `Model#commitMediCLI()`, so the MediCLI state will not be saved into the `mediCLIStateList`.

[//]: # ()
[//]: # (The `redo` command does the opposite — it calls `Model#redoMediCLI&#40;&#41;`, which shifts the `currentStatePointer` once to the right, pointing to the previously undone state, and restores the MediCLI to that state.)

[//]: # ()
[//]: # (<div markdown="span" class="alert alert-info">:information_source: **Note:** If the `currentStatePointer` is at index `mediCLIStateList.size&#40;&#41; - 1`, pointing to the latest MediCLI state, then there are no undone MediCLI states to restore. The `redo` command uses `Model#canRedoMediCLI&#40;&#41;` to check if this is the case. If so, it will return an error to the user rather than attempting to perform the redo.)
</div>


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#undoMediCLI()`, which will shift the `currentStatePointer` once to the left, pointing it to the previous MediCLI state, and restores the MediCLI to that state.


![UndoRedoState3](images/UndoRedoState3.png)


<div markdown="span" class="alert alert-info">:information_source: **Note:** If the `currentStatePointer` is at index 0, pointing to the initial MediCLI state, then there are no previous MediCLI states to restore. The `undo` command uses `Model#canUndoMediCLI()` to check if this is the case. If so, it will return an error to the user rather

than attempting to perform the undo.


</div>


The following sequence diagram shows how an undo operation goes through the `Logic` component:


![UndoSequenceDiagram](images/UndoSequenceDiagram-Logic.png)


<div markdown="span" class="alert alert-info">: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.


</div>


Similarly, how an undo operation goes through the `Model` component is shown below:

[//]: # ()
[//]: # (</div>)

[//]: # ()
[//]: # (Step 5. The user then decides to execute the command `list`. Commands that do not modify the MediCLI, such as `list`, will usually not call `Model#commitMediCLI&#40;&#41;`, `Model#undoMediCLI&#40;&#41;` or `Model#redoMediCLI&#40;&#41;`. Thus, the `mediCLIStateList` remains unchanged.)
![UndoSequenceDiagram](images/UndoSequenceDiagram-Model.png)


The `redo` command does the opposite — it calls `Model#redoMediCLI()`, which shifts the `currentStatePointer` once to the right, pointing to the previously undone state, and restores the MediCLI to that state.


<div markdown="span" class="alert alert-info">:information_source: **Note:** If the `currentStatePointer` is at index `mediCLIStateList.size() - 1`, pointing to the latest MediCLI state, then there are no undone MediCLI states to restore. The `redo` command uses `Model#canRedoMediCLI()` to check if this is the case. If so, it will return an error to the user rather than attempting to perform the redo.


</div>


Step 5. The user then decides to execute the command `list`. Commands that do not modify the MediCLI, such as `list`, will usually not call `Model#commitMediCLI()`, `Model#undoMediCLI()` or `Model#redoMediCLI()`. Thus, the `mediCLIStateList` remains unchanged.


![UndoRedoState4](images/UndoRedoState4.png)


Step 6. The user executes `clear`, which calls `Model#commitMediCLI()`. Since the `currentStatePointer` is not pointing at the end of the `mediCLIStateList`, all MediCLI states after the `currentStatePointer` will be purged. Reason: It no longer makes sense to redo the `addpatient i/S1234567A n/John Doe d/2003-01-30 p/98765432` 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:


<img src="images/CommitActivityDiagram.png" width="250" />


#### Design considerations:

[//]: # ()
[//]: # (![UndoRedoState4]&#40;images/UndoRedoState4.png&#41;)

[//]: # ()
[//]: # (Step 6. The user executes `clear`, which calls `Model#commitMediCLI&#40;&#41;`. Since the `currentStatePointer` is not pointing at the end of the `mediCLIStateList`, all MediCLI states after the `currentStatePointer` will be purged. Reason: It no longer makes sense to redo the `addpatient i/S1234567A n/John Doe d/2003-01-30 p/98765432` command. This is the behavior that most modern desktop applications follow.)
**Aspect: How undo & redo executes:**

[//]: # ()
[//]: # (![UndoRedoState5]&#40;images/UndoRedoState5.png&#41;)

[//]: # ()
[//]: # (The following activity diagram summarizes what happens when a user executes a new command:)
* **Alternative 1 (current choice):** Saves the entire MediCLI.

[//]: # ()
[//]: # (<img src="images/CommitActivityDiagram.png" width="250" />)
* Pros: Easy to implement.

[//]: # ()
[//]: # (#### Design considerations:)
* Cons: May have performance issues in terms of memory usage.

[//]: # ()
[//]: # (**Aspect: How undo & redo executes:**)

[//]: # ()
[//]: # (* **Alternative 1 &#40;current choice&#41;:** Saves the entire MediCLI.)
* **Alternative 2:** Individual command knows how to undo/redo by

[//]: # ( * Pros: Easy to implement.)
itself.

[//]: # ( * Cons: May have performance issues in terms of memory usage.)
* Pros: Will use less memory (e.g. for `delete`, just save the person being deleted).

[//]: # ()
[//]: # (* **Alternative 2:** Individual command knows how to undo/redo by)
* Cons: We must ensure that the implementation of each individual command are correct.

[//]: # ( itself.)

[//]: # ( * Pros: Will use less memory &#40;e.g. for `delete`, just save the person being deleted&#41;.)
_{more aspects and alternatives to be added}_

[//]: # ( * Cons: We must ensure that the implementation of each individual command are correct.)

[//]: # ()
[//]: # (_{more aspects and alternatives to be added}_)
### \[Proposed\] Data archiving

[//]: # ()
[//]: # (### \[Proposed\] Data archiving)

[//]: # ()
[//]: # (_{Explain here how the data archiving feature will be implemented}_)
_{Explain here how the data archiving feature will be implemented}_

## Planned Enhancements

Expand Down
16 changes: 13 additions & 3 deletions docs/UserGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,9 @@ MediCLI has 4 primary components in its main window. Detailed descriptions of ea

<b>Results Display</b> - MediCLI will respond to you here with either a success message or a detailed description of what went wrong.

<div markdown="span" class="alert alert-success">:bulb: **TIP**: The results display may be too narrow to show the entire message. You can scroll in the results display to see the whole message.
All error messages due to invalid formatting will end with an example usage.</div>

<b>Persons Panel</b> - This is where you will see a list of the filtered patients and patients.

<b>Appointments Panel</b> - This is where you will see a list of the filtered patients and patients.
Expand All @@ -167,16 +170,20 @@ MediCLI is operated using typed commands to the command line interface (CLI). Do

### Quick Tutorial on a Sample Use Case

1. Type the command in the command box and press Enter to execute it. e.g. typing **`help`** and pressing Enter will open the help window.<br>
1. Type the command in the command box and press Enter to execute it. e.g. typing **`help`** and pressing Enter will open the help window.<br>'

<div markdown="span" class="alert alert-danger">:exclamation: **DANGER**: 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>

Some example commands you can try (Assuming MediCLI is opened for the first time and is in its initial state with the default sample data):
Some example commands you can try (Assuming MediCLI is opened for the first time and is in its initial state with the default sample data):

* `list` : Lists all contacts.

* `adddoctor i/S1234567B n/Amy Smith d/2003-01-30 p/98765432` : Adds a doctor named `Amy Smith` to the MediCLI system.

* `addappt ad/2024-06-09 10:15 dn/S1234567B pn/S1234567A` : Schedules an appointment between the doctor `Amy Smith` and the patient `John Doe`.

<div markdown="span" class="alert alert-info">:information_source: **INFO**: MediCLI cannot schedule an appointment in the past, so change the date-time field if necessary.</div>

* `delete 2` : Deletes the 2nd person currently listed in the MediCLI system (patient named David Li).

* `exit` : Exits the app.
Expand All @@ -201,7 +208,6 @@ MediCLI is operated using typed commands to the command line interface (CLI). Do
* 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 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.
</div>

## Person Related Commands
Expand Down Expand Up @@ -301,6 +307,8 @@ Examples:

![result for 'find John David'](images/findPerson.png)

<div markdown="span" class="alert alert-success">:bulb: **TIP**: You can use the <code>find</code> command to filter people for commands that require a person's `INDEX`.</div>

### Querying patients by name : `patient`

Finds `Patient`(s) whose details contain any of the given keywords.
Expand Down Expand Up @@ -372,6 +380,8 @@ Note that while you cannot create a new appointment with the date and time in th

Format: `addappt ad/DATETIME dn/DOCTOR_NRIC pn/PATIENT_NRIC`

<div markdown="span" class="alert alert-success">:bulb: **TIP**: You can use the <code>patient</code> and <code>doctor</code> commands to retrieve their NRIC number if you only remember their name.</div>

Field Constraints:
- **DATETIME**: Input must be in the format `yyyy-MM-dd HH:MM`. Specified date and time must be later than the current date and time. i.e. appointment cannot be scheduled in the past.
- **DOCTOR_NRIC**: Follows the correct Singapore NRIC format. Begin with one of S, T, G, F, or M, followed by 7 numerical digits, then ended by an alphabetical letter. This field is non-case-sensitive.
Expand Down

0 comments on commit 405a225

Please sign in to comment.