Merge pull request #166 from AY2021S1-CS2103T-T12-1/branch-docs-saad

Do UG and DG for Undo/Redo implementation, and fix a few other smaller issues

Author: Wincenttjoi

docs/DeveloperGuide.md

@@ -141,7 +141,7 @@ Structure of Delivery Object
 
 The `Storage` component,
 * can save `UserPref` objects in json format and read it back.
-* can save the inventory book data and delivery book in json format and read it back.
+* can save the inventoryBook/deliveryBook data in json format and read it back.
 
 ### Common classes
 
@@ -164,6 +164,7 @@ method call to return `commandHistory`'s 2nd last command instead of the last co
 With `addToHistory(String command)`, `previousCommand()`, `nextCommand()` and `currentCommand()` implemented, a simple `setOnKeyPressed` under `CommandBox` class which checks
 for user's input of arrow up (which calls previousCommand()) and arrow down (which calls nextCommand()) would suffice for GUI implementation.
 
+
 ### Finding Items and Delivery
 OneShelf is capable of storing many items and deliveries. Therefore, there is an utmost importance to have the ability to be able to find item and delivery based on different fields. There could also be many similar item and this will definitely benefit the user to find it quickly. <br>
 
@@ -183,41 +184,44 @@ Below is a sequence diagram of the above
 
 ![ItemFindCommandSequenceDiagram](images/ItemFindCommandSequenceDiagram.png)
 
-### \[Proposed\] Undo/redo feature
 
-#### Proposed Implementation
+### Undo/Redo Command
+
+Each `Model` internally stores its undo and redo history as a (for `DeliveryModel`) `deliveryBookStateList` and `deliveryBookStatePointer`. There are corresponding analogs for `InventoryModel`.
+Additionally, the following commands are implemented by `ModelsManager`.
 
-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:
+* `ModelsManager#commit()` — Saves the current book states of all the `Model`s it contains in their history.
+* `ModelsManager#undo()` — Restores the previous book states from each `Model` from their history.
+* `ModelsManager#redo()` — Restores all previously undone book states from every `Model`'s history.
 
-* `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 `Models` interface as `Models#commit()`, `Models#undo()` and `Models#redo()` respectively.
 
-These operations are exposed in the `Model` interface as `Model#commitAddressBook()`, `Model#undoAddressBook()` and `Model#redoAddressBook()` respectively.
+The `ModelsManager` class calls `Model#commit()`, `Model#undo()`, and `Model#redo` on each of the models it contains, which then handle the respective tasks.
 
 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.
+Step 1. The user launches the application for the first time. Each `Model` will be initialized with its initial state, and the pointer pointing to their respective book's state.
 
 ![UndoRedoState0](images/UndoRedoState0.png)
 
-Step 2. The user executes `delete 5` command to delete the 5th item 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.
+Step 2. The user executes `delete-i 5` command to delete the 5th item in the inventory book. The `delete-i` command calls `Models#commit()`, causing the modified state of the inventory and delivery books after the `delete-i 5` command executes to be saved in the `inventoryBookStateList`, `deliveryBookStateList`, 
+and the `inventoryBookStatePointer`, `deliveryBookStatePointer` are shifted to the newly inserted books state.
 
 ![UndoRedoState1](images/UndoRedoState1.png)
 
-Step 3. The user executes `add n/David …​` to add a new item. The `add` command also calls `Model#commitAddressBook()`, causing another modified address book state to be saved into the `addressBookStateList`.
+Step 3. The user executes `add-d n/David p/12345678 …​` to add a new Delivery. The `add-d` command also calls `Models#commit()`, causing another set of modified book states to be saved into the `inventoryBookStateList` and `deliveryBookStateList`.
 
 ![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#commitAddressBook()`, so the address book state will not be saved into the `addressBookStateList`.
+<div markdown="span" class="alert alert-info">:information_source: **Note:** If a command fails its execution, it will not call `Models#commit()`, so the states will not be saved into the `inventoryBookStateList` and `deliveryBookStateList`.
 
 </div>
 
-Step 4. The user now decides that adding the item 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.
+Step 4. The user now decides that adding the delivery was a mistake, and decides to undo that action by executing the `undo` command. The `undo` command will call `Models#undo()`, which will shift the `deliveryBookStatePointer` and `inventoryBookStatePointer` once to the left, pointing it to the previous states, and restores the inventoryBook/deliveryBook to those states.
 
 ![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 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
+<div markdown="span" class="alert alert-info">:information_source: **Note:** If the current state pointers are at index 0, pointing to the initial state, then there are no previous books states to restore. The `undo` command uses `InventoryModel#canUndo()` and `DeliveryModel#canUndo()` 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>
@@ -230,17 +234,17 @@ The following sequence diagram shows how the undo operation works:
 
 </div>
 
-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.
+The `redo` command does the opposite — it calls `Models#redo()`, which shifts the `inventoryBookStatePointer` and `deliveryBookStatePointer` once to the right, pointing to the previously undone state, and restores the inventoryBook and deliveryBook to that state.
 
-<div markdown="span" class="alert alert-info">: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.
+<div markdown="span" class="alert alert-info">:information_source: **Note:** If the current pointers are pointing to the latest state, then there are no undone InventoryBook/DeliveryBook states to restore. The `redo` command uses `InventoryModel#canRedo()` and `DeliveryModel#canRedo()` 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 address book, such as `list`, will usually not call `Model#commitAddressBook()`, `Model#undoAddressBook()` or `Model#redoAddressBook()`. Thus, the `addressBookStateList` remains unchanged.
+Step 5. The user then decides to execute the command `list-i`. Commands that do not modify the inventoryBook and deliveryBook, such as `list-d` and `find-i`, will usually not call `Models#commit()`, `Models#undo()` or `Models#redo()`. Thus, the `inventoryBookStateList` and `deliveryBookStateList` remain 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.
+Step 6. The user executes `clear-d`, which calls `Models#commit()`. Since the state pointers are not pointing at the end of the respective state lists, all states after the current state will be purged. Reason: It no longer makes sense to redo the `add-d n/David p/12345678 …​` command. This is the behavior that most modern desktop applications follow.
 
 ![UndoRedoState5](images/UndoRedoState5.png)
 
@@ -252,7 +256,7 @@ The following activity diagram summarizes what happens when a user executes a ne
 
 ##### Aspect: How undo & redo executes
 
-* **Alternative 1 (current choice):** Saves the entire address book.
+* **Alternative 1 (current choice):** Saves the entire state.
   * Pros: Easy to implement.
   * Cons: May have performance issues in terms of memory usage.
 
@@ -420,18 +424,17 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
 1.  Should work on any _mainstream OS_ as long as it has Java `11` or above installed.
 2.  Should be able to hold up to 1000 items without a noticeable sluggishness in performance for typical usage.
 3.  A user with above average typing speed for regular English text (i.e. not code, not system admin commands) should be able to accomplish most of the tasks faster using commands than using the mouse.
-4.  Project should not cost any money
-5.  Should work on 32-bit and 64-bit environments
-6.  Should not take up more than 50 MB of disk space
-7.  Should not take up more than 250 MB of RAM
-8.  Commands should receive a response within 1 second
-9.  The system is not required to change the physical inventory
-10. The system should operate within a local network
-11. The data should be secured using a password
-12. Users should be able to get fluent with the syntax by their 10th usage
-13. The system should not provide functionality that breaks and local laws within a country it is distributed to
-14. The system should still be able to function without connection to a network
-15. The system should only be used by one user
+4.  Should work on 32-bit and 64-bit environments.
+5.  Should not take up more than 50 MB of disk space.
+6.  Should not take up more than 250 MB of RAM.
+7.  Add, Delete, List, Undo, Redo, Edit, and Remove Commands should receive a response within 1 second regardless of data size.
+8.  All other commands should receive a response withing 5 seconds regardless of data size.
+9.  The data should be secured using a password.
+10. Users should be able to get fluent with the syntax by their 10th usage.
+11. The system should still be able to function without connection to a network.
+12. The system should only be used by one user.
+13. Storing 100 states of the models for the Undo and Redo Commands should not take more than 100 KB.
+14. Storing 100 states of history of commands the user has entered should not take more than 10 KB.
 
 ### Glossary
 

docs/UserGuide.md

@@ -67,14 +67,22 @@ track of multiple items, OneShelf is for you!
 
 
 ### Viewing help : `help`
-Format: `help summary`
-Shows a summary of all the possible commands in OneShelf.
 
 Format: `help start`
 Shows a guide for user to kick-start their journey in OneShelf.
 
-<<Insert Screenshot in the future to show user what is expected, once GUI of help finalized>>
+Alternatives:
+* Press `F1` at any point in the usage of the app
+* GUI navigation menu at the top left
+
+Format: `help summary`
+Shows a summary of all the possible commands in OneShelf.
+
+Alternatives:
+* Press `F2` at any point in the usage of the app
+* GUI navigation menu at the top left
 
+![Help Summary Screenshot](images/HelpSummaryWindow.png)
 
 
 ### Adding an item: `add-i`
@@ -196,6 +204,27 @@ Exits the program.
 Format: `exit`
 
 
+### Undo last command : `undo`
+
+Undoes the previous command by reverting the current data displayed to the state it was in before the last command was executed.
+
+Format: `undo`
+
+* If there is a previous state available, the current state is reverted to that state
+* If the current state is the earliest possible one, it shows a message informing the user that there is nothing more to undo
+
+
+### Redo last command : `redo`
+
+Redoes the last undone command by reverting the current data displayed to the state it was in before the last undo command was executed.
+
+Format: `redo`
+
+* If there is an undone state available, the current state is reverted to that state
+* If the current state is the latest possible one, it shows a message informing the user that there is nothing more to redo
+* After any command that changes the state of data (such as add, clear, delete, edit), the new state becomes the latest state
+(i.e. the previous undo commands are "forgotten" and `redo` will have no effect)
+
 
 ### Saving the data
 
@@ -205,11 +234,6 @@ OneShelf data are saved in the hard disk automatically after any command that ch
 
 OneShelf commands are traversable much like Window's command prompt with the arrow up key traversing into previous commands and arrow down key traversing into next commands.  
 
-### Undo `[Coming Soon]`
-
-Undo previous command
-
-
 
 ### Sorting items`[Coming Soon]`
 
@@ -254,7 +278,14 @@ Notify the user if a certain stock is below threshold
 
 ## Command summary
 
+#### General commands summary
 
+| Action    | Format, Examples                                                                                    |
+|-----------|-----------------------------------------------------------------------------------------------------|
+|**Get help to start off**    | `help start` or press `F1` or use GUI help menu at the top left |
+|**Get help summary**    | `help summary` or press `F2` or use GUI help menu at the top left |                                                                                       |                                                                                             |
+|**Undo last command**   | `undo`  |
+|**Redo last undone command**   | `redo`  |
 
 #### Inventory summary
 
@@ -266,8 +297,7 @@ Notify the user if a certain stock is below threshold
 |**Edit Inventory**   | `edit-i INDEX [n/NAME] [q/QUANTITY] [s/SUPPLIER] [max/MAX_QUANTITY] [t/TAG]…​`<br> e.g.,`edit 1 n/Chicken q/50`                |
 |**Find in Inventory**   | `find-i PREFIX KEYWORD [MORE_KEYWORDS]`<br> e.g., `find-i n/Chicken Steak`                                       |
 |**List Inventory**   | `list-i
-|**Remove from Inventory** | `remove-i INDEX q/QUANTITY`                                                                                              |
-|**Help**   | `help`                                                                                              |
+|**Remove from Inventory** | `remove-i INDEX q/QUANTITY`                                                                                              |                                                                                          |
 
 
 

docs/diagrams/CommitActivityDiagram.puml

@@ -5,10 +5,10 @@ start
 'Since the beta syntax does not support placing the condition outside the
 'diamond we place it as the true branch instead.
 
-if () then ([command commits AddressBook])
-    :Purge redunant states;
-    :Save AddressBook to
-    addressBookStateList;
+if () then ([command commits Models])
+    :Purge redundant states;
+    :Save inventoryBook to inventoryBookStateList
+     and deliveryBook to DeliveryBookStateList;
 else ([else])
 endif
 stop

docs/diagrams/UndoRedoState0.puml

@@ -6,15 +6,24 @@ skinparam ClassBorderColor #000000
 title Initial state
 
 package States {
-    class State1 as "__ab0:AddressBook__"
-    class State2 as "__ab1:AddressBook__"
-    class State3 as "__ab2:AddressBook__"
+    class InventoryState1 as "__ib0:InventoryBook__"
+    class DeliveryState1 as "__db0:DeliveryBook__"
+    class InventoryState2 as "__ib1:InventoryBook__"
+    class DeliveryState2 as "__db1:DeliveryBook__"
+    class InventoryState3 as "__ib2:InventoryBook__"
+    class DeliveryState3 as "__db2:DeliveryBook__"
+    class Pointer as "Current State" #FFFFF
 }
-State1 -[hidden]right-> State2
-State2 -[hidden]right-> State3
-hide State2
-hide State3
+InventoryState1 -[hidden]right-> InventoryState2
+InventoryState2 -[hidden]right-> InventoryState3
+hide InventoryState2
+hide InventoryState3
 
-class Pointer as "Current State" #FFFFF
-Pointer -up-> State1
+DeliveryState1 -[hidden]right-> DeliveryState2
+DeliveryState2 -[hidden]right-> DeliveryState3
+hide DeliveryState2
+hide DeliveryState3
+
+Pointer -up-> InventoryState1
+Pointer -down-> DeliveryState1
 @end

docs/diagrams/UndoRedoState1.puml

@@ -3,20 +3,25 @@
 skinparam ClassFontColor #000000
 skinparam ClassBorderColor #000000
 
-title After command "delete 5"
+title After command "delete-i 5"
 
-package States <<rectangle>> {
-    class State1 as "__ab0:AddressBook__"
-    class State2 as "__ab1:AddressBook__"
-    class State3 as "__ab2:AddressBook__"
+package States {
+    class InventoryState1 as "__ib0:InventoryBook__"
+    class DeliveryState1 as "__db0:DeliveryBook__"
+    class InventoryState2 as "__ib1:InventoryBook__"
+    class DeliveryState2 as "__db1:DeliveryBook__"
+    class InventoryState3 as "__ib2:InventoryBook__"
+    class DeliveryState3 as "__db2:DeliveryBook__"
+    class Pointer as "Current State" #FFFFF
 }
+InventoryState1 -[hidden]right-> InventoryState2
+InventoryState2 -[hidden]right-> InventoryState3
+hide InventoryState3
 
-State1 -[hidden]right-> State2
-State2 -[hidden]right-> State3
+DeliveryState1 -[hidden]right-> DeliveryState2
+DeliveryState2 -[hidden]right-> DeliveryState3
+hide DeliveryState3
 
-hide State3
-
-class Pointer as "Current State" #FFFFF
-
-Pointer -up-> State2
+Pointer -up-> InventoryState2
+Pointer -down-> DeliveryState2
 @end

docs/diagrams/UndoRedoState2.puml

@@ -3,18 +3,24 @@
 skinparam ClassFontColor #000000
 skinparam ClassBorderColor #000000
 
-title After command "add n/David"
+title After command "add-d n/David p/12345678 …​"
 
-package States <<rectangle>> {
-    class State1 as "__ab0:AddressBook__"
-    class State2 as "__ab1:AddressBook__"
-    class State3 as "__ab2:AddressBook__"
+package States {
+    class InventoryState1 as "__ib0:InventoryBook__"
+    class DeliveryState1 as "__db0:DeliveryBook__"
+    class InventoryState2 as "__ib1:InventoryBook__"
+    class DeliveryState2 as "__db1:DeliveryBook__"
+    class InventoryState3 as "__ib2:InventoryBook__"
+    class DeliveryState3 as "__db2:DeliveryBook__"
+    class Pointer as "Current State" #FFFFF
 }
+InventoryState1 -[hidden]right-> InventoryState2
+InventoryState2 -[hidden]right-> InventoryState3
 
-State1 -[hidden]right-> State2
-State2 -[hidden]right-> State3
+DeliveryState1 -[hidden]right-> DeliveryState2
+DeliveryState2 -[hidden]right-> DeliveryState3
 
-class Pointer as "Current State" #FFFFF
+Pointer -up-> InventoryState3
+Pointer -down-> DeliveryState3
 
-Pointer -up-> State3
 @end