Skip to content

Commit

Permalink
Merge pull request #168 from ericyjw/master
Browse files Browse the repository at this point in the history 
Update documentations
  • Loading branch information
@ericyjw
ericyjw committed Nov 11, 2018
2 parents 8749c1e + babfaed commit c7faa1e
Show file tree
Hide file tree
Showing 12 changed files with 130 additions and 139 deletions.
67 changes: 34 additions & 33 deletions docs/DeveloperGuide.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -565,14 +565,14 @@ each `Cca` contains the a `Budget` and a set of transaction `Entries`. The budge

It implements the following commands:

* `create_cca` -- Creates a CCA with a given budget.
* `create` -- Creates a CCA with a given budget.
* `delete_cca` -- Deletes a specified CCA.
* `update` -- Updates the details of the CCA.
* `update` -- Updates the details of a specified CCA.
* `add_trans` -- Adds a transaction entry to a specified CCA.
* `delete_trans` -- Deletes a transaction entry to a specified CCA.
* `budget` -- Shows the transaction information of each CCA
* `budget` -- Shows the transaction information of each CCA.

However, only the implementation of `create_cca`, `update`, `add_trans` and `budget` will be discussed.
However, only the implementation of `create`, `update`, `add_trans` and `budget` will be discussed.

===== Create Command
The `create` mechanism is facilitated by `BudgetBook` and `BudgetBookStorage`.
Expand All @@ -591,7 +591,7 @@ These operations are exposed in the `Model` interface as:

Given below is an example usage scenario and how the create cca mechanism behaves at each step.

Step 1. The user create a new CCA by including the `CCA name` and the 'budget` allocated to the CCA.
Step 1. The user creates a new CCA by including the `CCA name` and the `budget` allocated to the CCA.

Step 2. `create` command checks for existing CCA name using `BudgetBook#hasCca(Cca toAdd)`. If a CCA with the same
name exists, the CCA is not created. Otherwise, it is added into the `BudgetBook` in the `Model`.
Expand All @@ -601,25 +601,25 @@ Step 3. `BudgetBook#addCca(Cca cca)` then invokes `ModelManger#indicateBudgetBoo
`BudgetBookChangedEvent`, which is handled by `EventsCenter`.

Step 4. `BudgetBookChangedEvent` is then handled by `StorageManager#handleBudgetBookChangedEvent(BudgetBookChangedEvent
event)`. `StorageManager#saveBudgetBook(ReadOnlyBudgetBook data)` is then called to write the update the existing
event)`. `StorageManager#saveBudgetBook(ReadOnlyBudgetBook data)` is then called to update the existing
`ccabook.xml` file with the new CCA.

The following sequence diagram shows how the create operation works:

.Sequence diagram for create CCA command
image::CreateCcaCommandSequenceDiagram.png[width="1500"]
_Figure 4.4.1.1: Sequence diagram for create command_

===== Update Command
The `update` mechanism is facilitated by `BudgetBook` and `BudgetBookStorage`.
When a CCA is getting updated, it looks up the `BudgetBook` in the `BudgetBookStorage` of the `Model` for the CCA to
update. It then update the `Cca` stored inside the `ccabook.xml` file in the local directory.
update. It then updates the `Cca` stored inside the `ccabook.xml` file in the local directory.
It implements the following commands:

* `BudgetBook#updateCca(Cca targetCca, Cca editedCca)` -- Updates an existing CCA in the `BudgetBook` in `Model`.
* `BudgetBook#commitBudgetBook()` -- Save a current version of the budget book in the `VersionedBudgetBook`.
* `BudgetBook#commitBudgetBook()` -- Saves a current version of the budget book in the `VersionedBudgetBook`.
* `UpdateCommand#createEditedCca(Cca ccaToEdit, EditCcaDescriptor editCcaDescriptor)` -- Creates an updated version
of the target CCA.
* `TransactionMath#updateDetails(Cca cca)` -- Update the `Spent` and `Outstanding` amount of the specified CCA.
* `TransactionMath#updateDetails(Cca cca)` -- Updates the `Spent` and `Outstanding` amount of the specified CCA.

These operations are exposed in the `Model` interface as:

Expand All @@ -630,30 +630,29 @@ These operations are exposed in the `Model` interface as:

Given below is an example usage scenario and how the update cca mechanism behaves at each step:

Step 1. The user specified the CCA to be updated by including the CCA name and the fields to update.
Step 1. The user specifies the CCA to be updated by including the CCA name and the fields to update.

Step 2. The user can update the head's name, vice-head's name, budget allocated, and the details of a transaction entry
such as its date, amount involved and remarks for the transaction. These information is stored in the
`UpdateCommand#EditCcaDescriptor`. Any fields that are not valid will display error message.
Step 2. The user can update the head's name, the vice-head's name, the budget allocated, and the details of a
transaction entry such as its date, amount involved and remarks for the transaction. These information is stored in the
`UpdateCommand#EditCcaDescriptor`. Any fields that are not valid will display an error message.

Step 3. `update` command then checks for existing CCA name using `BudgetBook#hasCca(CcaName ccaName)`. If the cca name
does not exists, an error message will appear. Otherwise, the updated CCA will be created from the
does not exist, an error message will appear. Otherwise, the updated CCA will be created from the
`UpdateCommand#EditCcaDescriptor` using
`UpdateCommand#createEditedCca(Cca ccaToEdit, EditCcaDescriptor editCcaDescriptor)`.

Step 4. `BudgetBook#updateCca(Cca targetCca, Cca editedCca)` then replace the existing CCA with the updated CCA and
then invoke `ModelManger#indicateBudgetBookChange()` to raise a `BudgetBookChangedEvent`, which is handled by
Step 4. `BudgetBook#updateCca(Cca targetCca, Cca editedCca)` then replaces the existing CCA with the updated CCA and
invokes `ModelManger#indicateBudgetBookChange()` to raise a `BudgetBookChangedEvent`, which is handled by
`EventsCenter`.

Step 5. `BudgetBookChangedEvent` is then handled by `StorageManager#handleBudgetBookChangedEvent(BudgetBookChangedEvent
Step 5. `BudgetBookChangedEvent` is handled by `StorageManager#handleBudgetBookChangedEvent(BudgetBookChangedEvent
event)`. `StorageManager#saveBudgetBook(ReadOnlyBudgetBook data)` is then called to replace the specified CCA in the
the existing `ccabook.xml` with the updated CCA and its information.

The following sequence diagram shows how the update operation works:

.Sequence diagram for update command
image::UpdateCommandSequenceDiagram.png[width="1500"]

_Figure 4.4.1.2: Sequence diagram for update command_

===== Add_Transaction Command

Expand All @@ -664,8 +663,8 @@ local directory.
It implements the following commands:

* `BudgetBook#updateCca(Cca targetCca, Cca editedCca)` -- Updates an existing CCA in the `BudgetBook` in `Model`.
* `BudgetBook#commitBudgetBook()` -- Save a current version of the budget book in the `VersionedBudgetBook`.
* `TransactionMath#updateDetails(Cca cca)` -- Update the `Spent` and `Outstanding` amount of the specified CCA.
* `BudgetBook#commitBudgetBook()` -- Saves a current version of the budget book in the `VersionedBudgetBook`.
* `TransactionMath#updateDetails(Cca cca)` -- Updates the `Spent` and `Outstanding` amount of the specified CCA.

These operations are exposed in the `Model` interface as:

Expand All @@ -675,37 +674,38 @@ These operations are exposed in the `Model` interface as:

Given below is an example usage scenario and how the add transaction mechanism behaves at each step:

Step 1. The user specified the CCA to add transaction to by including the CCA name and the transaction fields.
Step 1. The user specifies the CCA to add transaction to by including the CCA name and the transaction fields.

Step 2. The user must include the `Date`, `Amount` and `Remarks` for the transaction entry. Any fields that are not
valid will display error message.
valid will display an error message.

Step 3. `add_trans` command then checks for existing CCA name using `BudgetBook#hasCca(CcaName ccaName)`. If the
cca name does not exists, an error message will appear. Otherwise, the an `Entry` is created and is added to the
cca name does not exist, an error message will appear. Otherwise, the `Entry` is created and is added to the
target `Cca` using `Cca#AddNewTransaction(Entry entry)`.

Step 4. The `Spent` and `Outstanding` is then updated using `TransactionMath#updateDetails(Cca cca)`.

Step 5. `BudgetBook#updateCca(Cca targetCca, Cca editedCca)` then replace the existing CCA with the updated CCA and
then invoke `ModelManger#indicateBudgetBookChange()` to raise a `BudgetBookChangedEvent`, which is handled by
Step 5. `BudgetBook#updateCca(Cca targetCca, Cca editedCca)` then replaces the existing CCA with the updated CCA and
invokes `ModelManger#indicateBudgetBookChange()` to raise a `BudgetBookChangedEvent`, which is handled by
`EventsCenter`.

Step 6. `BudgetBookChangedEvent` is then handled by `StorageManager#handleBudgetBookChangedEvent(BudgetBookChangedEvent
Step 6. `BudgetBookChangedEvent` is handled by `StorageManager#handleBudgetBookChangedEvent(BudgetBookChangedEvent
event)`. `StorageManager#saveBudgetBook(ReadOnlyBudgetBook data)` is then called to replace the specified CCA in the
the existing `ccabook.xml` with the updated CCA and its transaction entry.

The following sequence diagram shows how the add_trans operation works:
The following sequence diagram shows how the add transaction operation works:

.Sequence diagram for update command
image::AddTransCommandSequenceDiagram.png[width="1500"]
__Figure 4.4.1.3: Sequence diagram for add_trans command_

===== Budget Command
The `budget` mechanism is facilitated by `BudgetBook` and `BudgetBookStorage`.
It opens ups a separate window to display the CCA information and its transaction history of the . It implements the
It opens up a separate window to display the CCA information and its transaction history. It implements the
following command:

* `EventsCenter#getInstance() -- Get the instance of the EventsCenter.
* `EventsCenter#post(E event) -- Post an event to the event bus.
* `EventsCenter#getInstance() -- Gets the instance of the EventsCenter.
* `EventsCenter#post(E event) -- Posts an event to the event bus.

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

Expand All @@ -716,7 +716,7 @@ and the `CcaName` is null.

Step 3. If the CCA is specified, the `budget` command checks whether the CCA specified exist.

Step 4. `budget` command then raise a `ShowBudgetViewEvent`, which is handled by `EventsCenter`.
Step 4. `budget` command then raises a `ShowBudgetViewEvent`, which is handled by `EventsCenter`.

Step 5. `ShowBudgetViewEvent` is handled by `MainWindow#handleShowBudgetEvent(ShowBudgetViewEvent event)` and invokes
`MainWindow#handleBudget(CcaName ccaName)`. This opens the budget window through `BudgetWindow#show(CcaName ccaName)`.
Expand All @@ -728,6 +728,7 @@ Step 6. It then checks whether the CCA name is present in `BudgetWindow#fillInne
The following activity diagram summarizes what happens when a user executes a budget command:

image::BudgetCommandActivityDiagram.png[width="650"]
__Figure 4.4.1.4: Activity diagram for budget command_

==== Design Considerations

Expand Down
123 changes: 54 additions & 69 deletions docs/UserGuide.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Hallper is a desktop app for the JCRC that allows *for better and faster managem
== Quick Start

. Ensure you have Java version `9` or later installed in your Computer.
. Download the latest `Hallper.jar` link:{repoURL}/releases[here].
. Download the latest `Hallper.jar` https://github.com/CS2103-AY1819S1-W16-1/main/releases[here].

. Copy the file to the folder you want to use as the home folder for your Hallper.
. Double-click the file to start the app. The GUI should appear in a few seconds.
Expand Down Expand Up @@ -214,27 +214,6 @@ Deletes the 2nd resident in Hallper.
`delete 1` +
Deletes the 1st resident in the results of the `find` command.

==== Deleting a transaction entry : `delete_trans`

Deletes the specified transaction entry from the specified CCA from Hallper. +
Format: `delete_trans c/NAME_OF_CCA trans/ENTRY_NUMBER`

****
* Deletes the specific transaction entry from the CCA with the specified name.
* The transaction entry number must be a *positive interger* (e.g. 1,2,3,4...).
****

[NOTE]
====
* The CCA specifed must exist in the Hallper.
* The transaction entry number must exist for the specified CCA.
====

Examples:

* `delete_cca c/netball trans/1`
* `delete_cca c/Basketball F trans/3`

// tag::import[]
==== Importing residents information : `import`

Expand All @@ -252,17 +231,17 @@ Format: `import f/FILEPATH`
File format examples for importable `.xml` files are as shown below:

image::AddressBookExample.png[width="790"]
_Figure 4.1.10.1: Resident information example. Multiple `persons` can be specified._
_Figure 4.1.9.1: Resident information example. Multiple `persons` can be specified._

image::CCAListExample.png[width="790"]
_Figure 4.1.10.2: CCA list example. Residents are identified by their unique room number. Multiple `room` can be
_Figure 4.1.9.2: CCA list example. Residents are identified by their unique room number. Multiple `room` can be
specified for multiple `cca`._

image::BudgetBookExample.png[width="790"]
_Figure 4.1.10.3: Budget book information example. Multiple `transaction` can be specified for multiple `ccas`._
_Figure 4.1.9.3: Budget book information example. Multiple `transaction` can be specified for multiple `ccas`._

image::TransactionsExample.png[width="790"]
_Figure 4.1.10.4: Transaction information example. Multiple `transaction` can be specified._
_Figure 4.1.9.4: Transaction information example. Multiple `transaction` can be specified._

Example:

Expand All @@ -274,6 +253,30 @@ Imports `data.xml` file to be read and for Hallper to be updated accordingly.
=== Viewing Hallper
This section lists features related to viewing all or specific contacts in Hallper.

==== Listing all persons : `list`

Shows a list of all persons in Hallper. +
Format: `list`

==== Locating persons by name: `find`
Finds persons whose names contain any of the given keywords. +
Format: `find KEYWORD [MORE_KEYWORDS]`

****
* The search is case insensitive. e.g `hans` will match `Hans`
* The order of the keywords does not matter. e.g. `Hans Bo` will match `Bo Hans`
* Only the name is searched.
* Only full words will be matched e.g. `Han` will not match `Hans`
* Persons matching at least one keyword will be returned (i.e. `OR` search). e.g. `Hans Bo` will return `Hans Gruber`, `Bo Yang`
****

Examples:

* `find John` +
Returns `john` and `John Doe`
* `find Betsy Tim John` +
Returns any person having names `Betsy`, `Tim`, or `John`

// tag::search[]
==== Searching all persons under specified tag : `search`

Expand Down Expand Up @@ -305,31 +308,6 @@ Searches Hallper and lists all residents that are staying in room `A123`.
* `search basketball A123 Soc` +
// end::search[]

==== Locating persons by name: `find`
Finds persons whose names contain any of the given keywords. +
Format: `find KEYWORD [MORE_KEYWORDS]`

****
* The search is case insensitive. e.g `hans` will match `Hans`
* The order of the keywords does not matter. e.g. `Hans Bo` will match `Bo Hans`
* Only the name is searched.
* Only full words will be matched e.g. `Han` will not match `Hans`
* Persons matching at least one keyword will be returned (i.e. `OR` search). e.g. `Hans Bo` will return `Hans Gruber`, `Bo Yang`
****

Examples:

* `find John` +
Returns `john` and `John Doe`
* `find Betsy Tim John` +
Returns any person having names `Betsy`, `Tim`, or `John`

==== Listing all persons : `list`

Shows a list of all persons in Hallper. +
Format: `list`
image::list.png[width="790"]

==== Selecting a person: `select`

Selects the person identified by the index number used in the displayed person list.
Expand Down Expand Up @@ -582,7 +560,7 @@ This section lists features related to CCA budget management in Hallper.
==== Adding a cca: `create`

Adds a CCA to Hallper. +
Format: `create n/NAME_OF_CCA budget/500`
Format: `create n/NAME_OF_CCA budget/ALLOCATED_BUDGET`

[TIP]
====
Expand Down Expand Up @@ -613,8 +591,8 @@ Format: `add_trans c/NAME_OF_CCA date/DATE amount/AMOUNT remarks/REMARKS`
Examples:

* `add_trans c/Basketball date/31.01.2018 amount/-200 remarks/Competition Fee` +
Adds a transaction entry to `Basketball`. The date, amount and remarks of the transaction entry are `31.01
.2018`, `-200` and `Competition Fee` respectively.
Adds a transaction entry to `Basketball`. The date, amount and remarks of the transaction entry are `31.01.2018`,
`-200` and `Competition Fee` respectively.

==== Deleting a cca : `delete_cca`

Expand Down Expand Up @@ -666,7 +644,8 @@ Format: `update c/CCA_NAME [n/NEW_CCA_NAME] [h/NAME_OF_HEAD] [vh/NAME_OF_VIC_HEA

****
* At least one of the optional fields must be provided.
* When `trans/` is included, at least one of the fields in the transaction entry must be provided.
* When `trans/` is included, at least one of the fields in the transaction entry must be provided. The transaction
fields are `date`, `amount` and `remarks`.
* Existing values will be updated to the input values.
****

Expand Down Expand Up @@ -694,18 +673,22 @@ respectively.
Opens up a Budget Book in a new window. +
Format: `budget [c/CCA_NAME]`


.Budget Window with a blank screen
image::BudgetWindowEmpty.png[width="500"]
_Figure 4.5.6.1: Budget Window with a blank screen_


.Budget Window showing the transaction history of Softball
image::BudgetWindowCca.png[width=500"]
_Figure 4.5.6.2: Budget Window showing the transaction history of Softball_

****
* `budget` shows the list of CCAs existing in Hallper.
* If `c/` is used, the new window will open up, showing the transaction information of the CCA specified.
* Otherwise, the new window will open up and show a blank screen until a CCA is selected from the CCA panel.
****

image::BudgetWindowCcaPanel.png[width=500"]
_Figure 4.5.6.3: CCA panel of the Budget Window._

[NOTE]
====
The CCA specifed must exist in the Hallper.
Expand Down Expand Up @@ -857,17 +840,19 @@ e.g. `delete_event month/Oct year/2018 sdate/10 edate/10 title/Block Committee A
e.g. `view_calendar month/Oct year/2018`

===== Budget and CCA
* *Add Transaction* : `add_transaction CCA AMOUNT TYPE PERSON-IN-CHARGE` +
e.g. `add_transaction soccer 500 debit James`
* *Budget* : `budget`
* *Create CCA Budget* : `create n/CCA bud/BUDGET` +
e.g. `create Basketball 500`
* *Delete CCA* : `delete_cca CCA` +
e.g. `delete_cca basketball`
* *Modify CCA* : `modify_cca CCA BUDGET` +
e.g. `modify_cca basketball 500`
* *View CCA* : `view_cca CCA` +
e.g. `view_cca basketball`
* *Add CCA* : `create n/CCA bud/BUDGET` +
e.g. `create n/Basketball budget/500`
* *Add Transaction* : `add_trans c/NAME_OF_CCA date/DATE amount/AMOUNT remarks/REMARKS` +
e.g. `add_trans c/Basketball date/31.01.2018 amount/-200 remarks/Competition Fee`
* *Delete CCA* : `delete_cca c/CCA` +
e.g. `delete_cca c/basketball`
* *Delete Transaction* : `delete_trans c/NAME_OF_CCA trans/ENTRY_NUMBER` +
e.g. `delete_trans c/netball trans/1`
* *Update CCA Details* : `update c/CCA_NAME [n/NEW_CCA_NAME] [h/NAME_OF_HEAD] [vh/NAME_OF_VIC_HEAD] [budget/BUDGET]
[trans/ENTRY_NUMBER] [date/DATE] [amount/AMOUNT] [remarks/REMARKS]` +
e.g. `update c/track n/Track F h/Alice vh/June Ong budget/500 trans/1 date/28.02.2018 amount/100 remarks/Fund Raising`
* *View CCAs' budget* : `budget [c/CCA_NAME]` +
e.g. `budget c/basketball`

===== Miscellaneous
* *Exit* : `exit`
Expand Down

0 comments on commit c7faa1e

Please sign in to comment.