Merge pull request #254 from AY1920S1-CS2103T-W12-3/developer-guide

Developer Guide

Author: dingyuchen

docs/DeveloperGuide.adoc

@@ -24,21 +24,20 @@ This document describes the architecture and system design of _PalPay_.
 It is a living document that evolves throughout the design and implementation for each release.
 Each release will have an edition of the document, and the current edition of the document is for the first public release of the application.
 
-This document is aimed at covering the high-level system architecture and design.
+This document aims to cover the high-level system architecture and design.
 It is segmented into two major parts: software design, including system architecture, and design implementation.
-The software design documents the main software components that operate and support the main system architecture.
-Essential details such as the user stories and use cases, as well as the Non Functional Requirements are included at the back of the document.
+The software design illustrates the main software components that operate and support the main system architecture.
+Essential details such as the user stories, use cases, and the Non Functional Requirements are included at the back of this document.
 
 === Audience
 
-This document is written for software engineers want to gain an insight of the system architecture and design of the application.
-In particular, the intended audience of this document is the students taking the roles of the developers, designers, and software testers of _PalPay_ from CS2103T - Software Engineering.
+This document is written for software engineers who desires a deeper insight of the system architecture and design of this application - PalPay.
+In particular, the intended audience of this document will be the students taking on the roles of the developers, designers, and software testers of _PalPay_ from CS2103T - Software Engineering.
 
 === Description
 
 _PalPay_ is a CLI application targeted for users who have poor financial management skills. The users should also prefer typing over mouse inputs.
-It allows the users to keep track of daily financial transactions, as well as set a budget for a time duration to achieve long-term financial success.
-Not only that, users can keep a ledger of lending and borrowing of money with others so that the users can keep track of the flow of their money.
+It allows the users to keep track of daily financial transactions, as well as set a budget for a time duration to achieve long-term financial success. Additionally, users can keep a ledger of lending and borrowing of money with others so that the users can keep track of the flow of their money.
 
 == Setting up
 
@@ -240,9 +239,9 @@ that deal with `Ledger` implements the `LedgerOperation` interface. +
 ** This allows us to achieve polymorphism by overloading methods in `Model` to handle the different operations correctly.
 ** This reduces code coupling as there are different models to handle different balance amounts.
 
-* A `Transaction` entry can affect a `Budget` which has similar categories.
-** Only `Out` Transactions will affect `Budget`.
-** Activity diagram below shows how and when a `Transaction` object affects `Budget`.
+* A `Transaction` entry can affect a `Budget` which has similar categories and is within the same time period. The activity diagram bellow will further clarify this flow.
+** Only `Out` Transactions can affect `Budget`.
+** The activity diagram below shows how and when a `Transaction` object affects `Budget`.
 
 .Activity diagram for Out Transaction affecting Budget
 image::OutbudgetActivityDiagram.png[]
@@ -267,7 +266,13 @@ Upon setting a new budget, a `BudgetCard` is created and displayed in a list in
 
 A `Budget` stores an *initial amount*, *amount* (the current amount), *deadline*, *categories*.
 There is a need for a `Budget` to store both *initial amount* and *amount* as it allows for percentage of budget remaining to be calculated. +
-Displaying the percentage improves the user experience greatly as our target user is a
+Shown below is the class diagram of `Budget` class:
+
+.Class diagram of Budget class
+image::BudgetClassDiagram.png[]
+
+
+Displaying the percentage remaining improves the user experience greatly as our target user is a
 `visual person who wants to see how much budget he has left in each category so as to cut down on spending as necessary`
 as specified in <<User-Stories, user stories>>. Hence, taking a quick glance at the `Budget card` allows the user to
 determine how much of budget he has left, as well as be alarmed by the red font colour to spend less if he has overspent beyond the budget set. +
@@ -284,18 +289,26 @@ public String displayPercentage() {
 }
 ```
 
-Shown below is an example of an overspent budget. Budget is displayed in red to alert the user that
-he has overspent beyond the set budget:
+Moreover, as our user is a visual person, PalPay makes use of colour to display different messages.
+For instance, budget is displayed in red to alert the user that he has overspent beyond the set budget. +
+
+Shown below is an example of an overspent budget:
 
 .Example of an overspent budget
 image::overspentBudget.png[]
 
+
 When setting a new `Budget`, existence of a duplicate budget is checked through a sequence of checks.
-The activity diagram below shows a simple successful case of setting a new budget:
+The activity diagram below shows the activity diagram of setting a new budget:
 
 .Activity Diagram of successfully setting a new Budget
 image::SetBudgetSimpleActivityDiagram.png[]
 
+As shown, a new budget cannot have the same *initalAmount*, *deadline* and *categories* as any other existing budget in
+budget list. Allowing existence of duplicate budgets will crowd the interface of `Budget` tab,
+which prevents the user from getting a quick overview of his budget status. Hence, a duplicate check is essential
+in providing a pleasing user experience. +
+
 ==== Design Considerations
 
 Currently, `Budget` does not extend from `Transaction` although the two behave in a similar way.
@@ -335,6 +348,7 @@ image::Split.png[]
 
 // end::split[]
 
+//tag::receive[]
 === Settle Up Feature: `receive`
 
 This feature allows another person to send money to the user. +
@@ -371,6 +385,7 @@ public abstract class Payment extends Transaction implements LedgerOperations {
     }
 }
 ```
+//end::receive[]
 
 // tag::project[]
 [[Implementation-Projection]]
@@ -508,20 +523,20 @@ This feature allows the user to delete an existing transaction, budget, ledger o
 
 * The delete feature is facilitated by the Logic and Model components of the application.
 * The delete feature works for `Transaction`, `Budget`, `Ledger` and `Projection` entries.
-* The following activity diagram summarizes what happens when a user executes Delete command:
+* The following activity diagram summarizes what happens when a user executes a `delete` command:
 
-.Activity Diagram of Delete Command
+.Activity Diagram for `delete` command
 image::DeleteActivityDiagram.png[]
 
 ==== Design Consideration
 
-* The `delete` command is followed by a `TYPE+INDEX` parameter.
+* The `delete` keyword is followed by a `TYPE+INDEX` parameter.
 ** `Transaction` entries takes in `t` as its `TYPE` parameter.
 ** `Budget` entries takes in `b` as its `TYPE` parameter.
 ** `Ledger` entries takes in `l` as its `TYPE` parameter.
 ** `Projection` entries takes in `p` as its `TYPE` parameter.
 * The `index` parameter refers to the entry number within the `TYPE` entry's view tab.
-* Example: `delete t5` deletes the 5th transaction from the list of transaction if that particular entry exists.
+* Example: `delete t5` deletes the 5th entry from the list of transactions if that particular entry exists.
 
 ===== Aspect: Delete requires `TYPE+INDEX` as one of its parameter
 
@@ -538,19 +553,19 @@ image::DeleteActivityDiagram.png[]
 // tag::update[]
 === Update Existing Entry Feature: `update`
 
-This feature allows users to update `Transaction`, `Budget` or `Projection` entries. The user is unable to perform this feature on `Ledger` and operations the rationale will be further explained in **Aspect 2**.
+This feature currently allows users to update `Transaction` or `Budget` entries. The user is unable to perform this feature on `Ledger` operations. The rationale for this will be further explained in **Aspect 2**. The user is currently unable to perform this feature on `Projection` operations as it will be further implemented in future updates.
 
 ==== Current Implementation
 
 *  The update feature is facilitated by the Logic and Model components of the application.
 * The parameter requirements differs for the type of entry:
 ** `Transaction` type requires at least one of it's `Amount`, `Description`, `Date` or `Category` fields to be updated.
 ** `Budget` type requires at least one of it's `Amount`, `Date` or `Category` fields to be updated.
-** `Project` type only requires it's `Date` field to be updated.
+** `Project` type requires it's `Date` and `Category` fields to be updated (Future implementation).
 * At least one valid parameter must be changed when executing an `update` command. (i.e. `update b1` will result in an error as no fields are being changed).
 * The following activity diagram summarizes what happens when a user executes an update command:
 
-.Activity Diagram for update
+.Activity Diagram for `update`
 image::UpdateActivityDiagram.png[]
 
 ==== Design Considerations
@@ -573,13 +588,23 @@ More often than not, users do not need to change an entire Transaction or Budget
 
 * **Alternative 1 (current choice):** Update Command only works with `Transaction`, `Budget` and `Projection` Operations.
 ** Pros: Intuitive implementation and execution for the user.
-** Cons: Requires excessive user operations. The user has to first delete the `Ledger` operation that he/she wishes to change, then input the `Ledger` operation with the amended fields.
-** For example, when a new command is executed, we must remember to update both `HistoryManager` and `VersionedAddressBook`.
+** Cons: Requires excessive user operations.
+*** The user has to first delete the `Ledger` operation that he/she wishes to change, followed by inputting the `Ledger` operation with the amended fields back into PalPay.
 * **Alternative 2:** Update Command to also work with `Ledger` operations.
 ** Pros: Requires only one user command to append or change `Ledger` entries.
 ** Cons: Results in convoluted implementation and user experience. This will also hinder future permeability of the `Split` feature.
 *** `Ledger` operations such as `split` includes many repeated fields (i.e. multiple `Persons` and `shares` list).
 *** Will require several conditional user inputs to differentiate between the various repeated entities that the user wishes to amend.
+
+==== Future Enhancements
+
+===== Update feature for Projections
+Currently the update feature has not been implemented for `Projection` operations. In future iterations of PalPay, the update feature should work seamlessly with `Projection` operations, similar to that of `Transaction` and `Budget` operations
+
+The activity diagram below will provide a visual representation of the possible user routes using the `update` command after this enhancement has been implemented.
+
+.Activity Diagram for future `update`
+image::UpdatefutureActivityDiagram.png[]
 // end::update[]
 
 // tag::sort[]
@@ -724,20 +749,20 @@ Given below is an example usage scenario and how the undo/redo mechanism behaves
 The `VersionedUserState` will be initialized with the initial user state, and the `currentStatePointer`
 pointing to that single user state.
 
-image::UndoRedoState0.png[]
+image::UndoRedoState0.png[pdfwidth=50%, align="center"]
 
 **Step 2**. The user executes `delete t5` command to delete the 5th transaction in the transaction list.
 The `delete` command calls `Model#commitUserState()`, causing the modified state of the user state after the
 `delete t5` command executes to be saved in the `userStateList`, and the `currentStatePointer` is shifted
 to the newly inserted user state.
 
-image::UndoRedoState1.png[]
+image::UndoRedoState1.png[pdfwidth=50%, align="center"]
 
 **Step 3**. The user executes `in $/10 n/Allowance d/07112019` to log a new transaction.
 The `in` command also calls `Model#commitUserState()`, causing another modified user state to be saved
 into the `userStateList`.
 
-image::UndoRedoState2.png[]
+image::UndoRedoState2.png[pdfwidth=50%, align="center"]
 
 [NOTE]
 If a command fails its execution, it will not call `Model#commitUserState()`, so the user state will
@@ -748,7 +773,7 @@ executing the `undo` command. The `undo` command will call `Model#undoUserState(
 `currentStatePointer` once to the left, pointing it to the previous user state, and restores the user state
 to that state.
 
-image::UndoRedoState3.png[]
+image::UndoRedoState3.png[pdfwidth=50%, align="center"]
 
 [NOTE]
 If the `currentStatePointer` is at index 0, pointing to the initial user state, then there are no previous
@@ -759,14 +784,14 @@ If so, it will return an error to the user rather than attempting to perform the
 Commands that do not modify the user state, such as `list`, will usually not call `Model#commitUserState()`,
 `Model#undoUserState()` or `Model#redoUserState()`. Thus, the `userStateList` remains unchanged.
 
-image::UndoRedoState4.png[]
+image::UndoRedoState4.png[pdfwidth=50%, align="center"]
 
 **Step 6**. The user executes `clear`, which calls `Model#commitUserState()`.
 Since the `currentStatePointer` is not pointing at the end of the `userStateList`, all user states after
 the `currentStatePointer` will be purged. We designed it this way because it no longer makes sense to redo the
 `in $/10 n/Allowance d/07112019` command. This is the behavior that most modern desktop applications follow.
 
-image::UndoRedoState5.png[]
+image::UndoRedoState5.png[pdfwidth=50%, align="center"]
 
 The following sequence diagram shows how the undo operation works:
 
@@ -985,7 +1010,7 @@ These instructions only provide a starting point for testers to work on; testers
 
 . Initial launch
 
-.. Download the jar file and copy into an empty folder
+.. Download the jar file and copy into an empty folder.
 .. Double-click the jar file +
    Expected: Shows the GUI with a set of sample contacts.
 The window size may not be optimum.
@@ -1017,9 +1042,18 @@ Status bar remains the same.
    Expected: Similar to previous.
 
 
+=== Viewing Help Window
+
+. Requesting help from PalPay
+
+.. Prerequisites: None
+
+.. Test case: `help` +
+Expected: A help window pops up that displays the URL of PalPay's User Guide and a `Copy URL` button.
+
 === Saving Data
 
 . Dealing with missing/corrupted data files
 
-.. _{explain how to simulate a missing/corrupted file and the expected behavior}_
+.. Delete the file at `.\data\bankaccount.json`.