+
-[[homepage](http://www.comp.nus.edu.sg/~damithch)]
-[[github](https://github.com/johndoe)]
-[[portfolio](team/johndoe.md)]
+[[github](https://github.com/Neethesh26)]
+[[portfolio](team/neethesh26.md)]
-* Role: Project Advisor
+* Role: Developer
+* Responsibilities:
+ * Feature (EditLoan, Loan History)
+ * English Proofreading
+ * Meeting coordinator
-### Jane Doe
+### Chen Ruihan
-
-[[github](http://github.com/johndoe)]
-[[portfolio](team/johndoe.md)]
+[[github](http://github.com/rui-han-crh)]
+[[portfolio](team/rui-han-crh.md)]
-* Role: Team Lead
-* Responsibilities: UI
+* Role: Developer
+* Responsibilities:
+ * User Interface
+ * Feature (Loans)
+ * English Proofreading
+ * Project Embellishments
-### Johnny Doe
+### Ryan Chua
-
-[[github](http://github.com/johndoe)] [[portfolio](team/johndoe.md)]
+[[github](http://github.com/ryanczx)]
+[[portfolio](team/ryanczx.md)]
* Role: Developer
-* Responsibilities: Data
+* Responsibilities: Tags
-### Jean Doe
+### Chee Zhong Wei
-
-[[github](http://github.com/johndoe)]
-[[portfolio](team/johndoe.md)]
+[[github](http://github.com/czhongwei)]
+[[portfolio](team/czhongwei.md)]
* Role: Developer
-* Responsibilities: Dev Ops + Threading
+* Responsibilities: Find, Birthday, Documentation
-### James Doe
+### Jiang Pinran
-
-[[github](http://github.com/johndoe)]
-[[portfolio](team/johndoe.md)]
+[[github](http://github.com/Pinran-J)]
+[[portfolio](team/pinran-j.md)]
* Role: Developer
-* Responsibilities: UI
+* Responsibilities:
+ * Feature (All notes related)
+ * English Proofreading
+ * Team meeting management
+
diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md
index 46eae8ee565..a73328fbb8a 100644
--- a/docs/DeveloperGuide.md
+++ b/docs/DeveloperGuide.md
@@ -2,14 +2,68 @@
layout: page
title: Developer Guide
---
-* Table of Contents
-{:toc}
+
+## Table of Contents
+* [Acknowledgements](#acknowledgements)
+* [Overview](#overview)
+* [Setting up, getting started](#setting-up-getting-started)
+* [Design](#design)
+ * [Architecture](#architecture)
+ * [UI Component](#ui-component)
+ * [Logic Component](#logic-component)
+ * [Model Component](#model-component)
+ * [Storage Component](#storage-component)
+* [Properties Objects](#properties-objects)
+ * [Properties of Person Objects](#properties-of-person-objects)
+ * [Properties of Note Objects](#properties-of-note-objects)
+* [Implementation](#implementation)
+ * [Person Features](#person-features)
+ * [Edit Person](#edit-person)
+ * [Delete Person](#delete-person)
+ * [Find Person](#find-person)
+ * [Edit Loan](#edit-loan-value-and-history-of-person-by-editloan-feature)
+ * [Find by Tag](#find-persons-and-notes-by-tag)
+ * [Notes Features](#notes-features)
+ * [Add Note](#add-note)
+ * [Delete Note](#delete-note)
+ * [Edit Note](#edit-note)
+ * [UI Features](#ui-features)
+ * [General UI Design and Mechanism](#general-ui-design-and-mechanism)
+ * [Inspect Feature](#inspect-feature)
+ * [Showing and Hiding Panel Feature](#showing-and-hiding-the-notes-panel-feature)
+ * [[Proposed] Undo redo feature](#proposed-undoredo-feature)
+* [Documentation, logging, testing, configuration, dev-ops](#documentation-logging-testing-configuration-dev-ops)
+* [Appendix](#appendix-requirements)
+ * [Requirements](#appendix-requirements)
+ * [Product scope](#product-scope)
+ * [User stories](#user-stories)
+ * [Use Cases](#use-cases)
+ * [Non-Functional Requirements](#non-functional-requirements)
+ * [Glossary](#glossary)
+ * [Instructions for manual testing](#appendix-instructions-for-manual-testing)
+
--------------------------------------------------------------------------------------------------------------------
## **Acknowledgements**
-* {list here sources of all reused/adapted ideas, code, documentation, and third-party libraries -- include links to the original source as well}
+The background of the program is a large-scale city, attributed to [GiulioDesign94](https://www.deviantart.com/giuliodesign94)'s [Big City](https://www.deviantart.com/giuliodesign94/art/Big-City-198672166).
+
+The icon of this program is an edited image from DepositPhotos, found [here](https://depositphotos.com/471137460/stock-illustration-book-yellow-glowing-neon-icon.html).
+
+This team recognises the rights to the images go to their respective owners.
+
+--------------------------------------------------------------------------------------------------------------------
+
+## **Overview**
+
+SectresBook helps secretaries to maintain all the information of the members of their club by collating a list of identifiable information, past loan records and future tasks.
+
+Our main target audience is secretaries, but this may be expanded to any person in need of loan tracking and task tracking features provided by our software.
+
+This Developer Guide is written for maintainers of SectresBook.
+
+Designers and developers who wish to extend or morph this product may also use this documentation to gain a better understanding of the design of this software.
--------------------------------------------------------------------------------------------------------------------
@@ -18,6 +72,7 @@ title: Developer Guide
Refer to the guide [_Setting up and getting started_](SettingUp.md).
--------------------------------------------------------------------------------------------------------------------
+
## **Design**
@@ -73,16 +128,32 @@ The **API** of this component is specified in [`Ui.java`](https://github.com/se-
-The UI consists of a `MainWindow` that is made up of parts e.g.`CommandBox`, `ResultDisplay`, `PersonListPanel`, `StatusBarFooter` etc. All these, including the `MainWindow`, inherit from the abstract `UiPart` class which captures the commonalities between classes that represent parts of the visible GUI.
+The UI consists of a `MainWindow` that is made up of parts e.g.`CommandBox`, `ResultDisplay`, `PersonListPanel`, `NoteListPanel`, `PersonInspectPanel` `StatusBarFooter` etc. All these, including the `MainWindow`, inherit from the abstract `UiPart` class which captures the commonalities between classes that represent parts of the visible GUI.
The `UI` component uses the JavaFx UI framework. The layout of these UI parts are defined in matching `.fxml` files that are in the `src/main/resources/view` folder. For example, the layout of the [`MainWindow`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/ui/MainWindow.java) is specified in [`MainWindow.fxml`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/resources/view/MainWindow.fxml)
+The `UI` component is separate from the state of the `Model` and changes to the `UI` will not affect the `Model`, but changes to the `Model`'s state will affect the information displayed by the `UI` elements.
+
+Similarly, changes to the visual aspects of `UI`, such as current person viewed, or the filtered state of the lists, will not be saved to file as they do not affect the `Model`'s data.
+
The `UI` component,
* executes user commands using the `Logic` component.
* listens for changes to `Model` data so that the UI can be updated with the modified data.
* keeps a reference to the `Logic` component, because the `UI` relies on the `Logic` to execute commands.
-* depends on some classes in the `Model` component, as it displays `Person` object residing in the `Model`.
+* depends on some classes in the `Model` component, as it displays `Person` and `Notes` object residing in the `Model`.
+
+This component may be controlled by commands through the `CommandResult` class, which specifies an optional `UiState` that the program should be in at the end of the command execution. This is parsed finally in the `MainWindow::executeCommand` which invokes necessary changes to the UI.
+
+For more information related to the implementation of the UI, please review the section [UI Features](#ui-features).
+
+#### UI Elements
+
+1. **Command Box**: A text box that allows users to enter in commands for later execution.
+2. **ResultDisplay**: A readonly text box that serves as a console to give feedback from the `Logic` component to the user, such as error messages or logs.
+3. **Person List**: A horizontal sliding list that displays all persons in the SectresBook. This list can be filtered to display only relevant people according to some predicate.
+4. **Note List**: A vertical sliding list that displays all notes in the SectresBook. This list can be filtered to display only relevant notes according to some predicate.
+5. **Person Inspect Panel**: This Panel displays data of a person, using the UI command `inspect`.
### Logic component
@@ -102,9 +173,13 @@ The Sequence Diagram below illustrates the interactions within the `Logic` compo
-:information_source: **Note:** The lifeline for `DeleteCommandParser` should end at the destroy-marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.
+Commands such as Edit and Delete feature the ability to delete by name, which utilises the Find feature. Illustrated here is how `execute("edit Lynette")` interacts with the Logic component, using a sequence diagram
+
+
+
Here are the other classes in `Logic` (omitted from the class diagram above) that are used for parsing a user command:
@@ -121,17 +196,11 @@ How the parsing works:
The `Model` component,
-* stores the address book data i.e., all `Person` objects (which are contained in a `UniquePersonList` object).
+* stores the address book data i.e., all `Person` objects (which are contained in a `UniquePersonList` object) and all `Note` objects (contained in a `NoteBook` object)
* stores the currently 'selected' `Person` objects (e.g., results of a search query) as a separate _filtered_ list which is exposed to outsiders as an unmodifiable `ObservableList:information_source: **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.
- -
-
-
-
+
### Storage component
@@ -149,14 +218,483 @@ The `Storage` component,
Classes used by multiple components are in the `seedu.addressbook.commons` package.
--------------------------------------------------------------------------------------------------------------------
+
+
+## Properties Objects
+
+### Properties of Person Objects
+
+This section explains the components of a person object and how they can be used to track information.
+
+- -
-
-
+
+A person object contains editable properties:
+1. Name
+ - Describes the full name of the person
+2. Phone
+ - Records the mobile phone contact number of the person
+3. Email
+ - Records the email address of the person
+4. Address
+ - Records the home address of the person
+5. Birthday
+ - Records the birthday of the person
+6. Tag
+ - Optionally tags the person with a variable number of tags for easy reference within the SectresBook.
+
+And a non-editable properties:
+1. Loan
+ - Tracks the current loan amount of the person. A positive number means that the person currently owes money to the club, a negative number means that money is due to be paid to the person.
+2. List of Loan Histories
+ - Tracks the transactional history of incoming and outgoing loans. Each Loan History comprises a Loan and a Record.
+
+During instantiation, a person object can be declared with all fields, but during editing, Loan must use a specialised command `editLoan` to transform its data.
+
+
+### Properties of Note Objects
+
+This section explains the components of a note object and how they can be used to track information.
+
+
-## **Implementation**
+A note object contains editable properties:
+1. Title
+ - The title of the note, which can be searched by.
+2. Content
+ - The description of the note.
+3. Tags
+ - Optional tags that can be assigned to the notes, after-which every person with that tag will be associated with the notes.
+
+During instantiation, a note object can be declared with any of these properties.
+
+-------------------
+
+## Implementation
This section describes some noteworthy details on how certain features are implemented.
+### Person Features
+
+#### Edit Person
+
+The Edit Person feature is facilitated by the `EditCommand` which utilises the `FindCommand`. It allows users to edit any editable field of a person given the index of the person, or the name of the person.
+
+If given a name that does not correspond to any person in the SectresBook, the edit features performs the same operations as the `Find` command.
+
+Given below is an example usage scenario and how the edit mechanism behaves at each step.
+
+Step 1. The user enters the edit command, with either the index or the person's name.
+
+Step 2a If an index is entered, the `EditCommandParser` carries this index to the `EditCommand`, which retrieves the `Person` to edit by getting the `Model`'s current `FilteredList
+
+:information_source: **Note:** The lifeline for `DeleteCommandParser` should end at the destroy marker (X)
+but due to a limitation of PlantUML, the lifeline reaches the end of diagram.
+
+##### Design Considerations:
+
+**Aspect: How delete executes:**
+
+* **Alternative 1 (Currect choice):** Deletes person based on complete first/last name from input.
+ * Pros: Less strictness of input from the user to delete a person.
+ * Cons: User may accidentally delete a person not meant to be deleted.
+* **Alternative 2:** Delete a person based on complete name i.e. first and last name required in input.
+ * Pros: Stricter input requirement, ensuring that persons are not accidentally deleted.
+ * Cons: Longer input required for the same output.
+
+
+#### Find Person
+
+The Find Person feature is facilitated by 'FindCommand'. It allows users to find all Persons with names that are matching or phone number starting with any of the keywords.
+
+Given below is an example usage scenario and how the find feature behaves at each step.
+
+Step 1. The user executes 'find David' command to find all Persons in the address book that includes the name `David`.
+
+Step 2. A `FindCommand` is constructed with a `NameContainsKeywordPredicate` which checks through the list of persons in the address book and only shows those with their first/last name matching `David`.
+
+Step 3. The `FindCommand` is executed and the `NameContainsKeywordsPredicate` is used to update the filtered person list.
+
+The following sequence diagram shows how the find command works:
+
+
+
+:information_source: **Note:** The lifeline for `FindCommandParser` and `FindCommand` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.
+
+
+
+##### Design considerations:
+
+**Aspect: How find executes:**
+
+* **Alternative 1 (current choice):** Chooses person based on the whole first/last name matching the keyword.
+ * Pros: More specific Persons list after the find command.
+ * Cons: User needs to know the first/last name of the person they are trying to find.
+
+* **Alternative 2:** Chooses person if name contains the keyword.
+ * Pros: Easier to find person.
+ * Cons: Persons list may show other persons that are not desired by the user.
+
+#### Edit loan value and history of Person by EditLoan feature
+
+The Edit Loan feature is facilitated by the `EditLoanCommand` which utilises the `FindCommand`. It allows users to edit the loan value and update the loan history of a person given the index of the person, or the name of the person.
+
+If given a name that does not correspond to any person in the SectresBook, the edit feature performs the same operations as the `Find` command.
+
+Given below is an example usage scenario and how the editLoan mechanism behaves at each step.
+
+Step 1. The user enters the editLoan command, with either the index or the person's name.
+
+Step 2a If an index is entered, the `EditLoanCommandParser` carries this index to the `EditCommand`, which retrieves the `Person` to edit by getting the `Model`'s current `FilteredList
+
+
+#### Find Persons and Notes by Tag
+
+The find Persons and Notes by Tag feature (called `findTag`) is facilitated by `FindTagCommand`. It allows users to find all Persons and Notes with the given Tags.
+
+Given below is an example usage scenario and how the findTag feature behaves at each step.
+
+Step 1. The user executes `findTag Finance` command to find all Persons and Notes in the SectresBook with the tag `Finance`.
+
+Step 2. A `FindTagCommand` is constructed with a `PersonTagsContainsKeywordsPredicate` and `NoteTagsContainsKeywordsPredicate` which will check through the list of Persons and Notes in the SectresBook and only show those with the tag `Finance`.
+
+Step 3. The `FindTagCommand` is executed and the `PersonTagsContainsKeywordsPredicate` and `NoteTagsContainsKeywordsPredicate` is passed to model to update the Person List and Note List to only show Persons and Notes with the tag `Finance`.
+
+The following sequence diagram shows how the findTag command works:
+
+
+
+:information_source: **Note:** The lifeline for `FindTagCommandParser` and `FindTagCommand` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.
+
+
+
+##### Design considerations:
+
+**Aspect: How findTag executes:**
+
+* **Alternative 1 (current choice):** Goes through all Persons and Notes to check for Tag.
+ * Pros: Easy to implement (Similar to current find command).
+ * Cons: May have performance issues in terms of having to do many more steps.
+
+* **Alternative 2:** Goto searched Tags and get the Persons and Notes that each Tag points to.
+ * Pros: Will use fewer steps (Go directly to the Tags rather than looking through all Persons and Notes).
+ * Cons: Implementation would be more complicated.
+
+
+### Notes Features
+
+#### Add Note
+
+The addNote mechanism is facilitated by `AddNoteCommand`. It extends `Command` and overrides `Command#execute()` to implement the following operation:
+- `AddNoteCommand#execute()` : adds the specified note with its associated title and content into the list of notes to be kept track of.
+
+Given below is an example usage scenario and how the addNote mechanism behaves at each step.
+
+Step 1. The user launches the application and wishes to keep track of a note with the following attributes :
+1. Title : Club meeting
+2. Content : 3rd October 9pm, brief everybody on upcoming events.
+
+Step 2. The user executes `addNote title/Meeting content/3rd October 9pm`, which calls `LogicManager#execute()`. Subsequently, `AddressBookParser#parseCommand()` is called
+which will create a `AddNoteCommandParser` object and call `AddNoteCommandParser#parse()`. This method will take the user's input and make sense of it to create a `Note` object.
+
+Step 3. An `AddNoteCommand` will be created and `AddNoteCommand#execute()` will be called by `LogicManager#execute()`.
+
+Step 4. `AddNoteCommand#execute()` will call the following method from `Model` :
+- `addNote(toAdd)`
+
+Step 5. `AddNoteCommand#execute()` will return a `CommandResult` object which will display the following message back to the user:
+> New note added: Title: Meeting, Content: 3rd October 9pm
+
+The following sequence diagram shows how the addNote operation works:
+
+
+
+##### Design considerations
+
+**Aspect: How Title and Content are represented:**
+
+* **Alternative 1 (current choice):** Title and Content as separate objects.
+ * Pros: Easy to validate Title/Content. (In the respective classes)
+ * Cons: May have performance issues in terms of memory usage(Many objects might be created).
+
+* **Alternative 2:** Title and Content as fields of Note
+ * Pros: Will use less memory (Fewer objects created).
+ * Cons: Harder to validate Title/Content. Better OOP(Object-oriented programming) design.
+
+#### Delete Note
+
+The deleteNote mechanism is facilitated by `DeleteNoteCommand`. It extends `Command` and overrides `Command#execute()` to implement the following operation:
+- `DeleteNoteCommand#execute()` : deletes the note at the specified index from the note list.
+
+Given below is an example usage scenario and how the addNote mechanism behaves at each step.
+
+Step 1. The user launches the application and wishes to delete a note that no longer needs to be kept track of. The user lists the current notes:
+1. Title: Meeting, Content: 3rd October 9pm
+2. Title: Event, Content: Remind club members to attend.
+
+The user has decided to delete note 1.
+
+Step 2. The user executes `deleteNote 1`, which calls `LogicManager#execute()`. Subsequently, `AddressBookParser#parseCommand()` is called
+which will create a `DeleteNoteCommandParser` object and call `DeleteNoteCommandParser#parse()`. This method will take the user's input and make sense of it to get the index of note to be deleted.
+
+Step 3. A `DeleteNoteCommand` object will be created and `DeleteNoteCommand#execute()` will be called by `LogicManager#execute()`.
+
+Step 4. `DeleteNoteCommand#execute()` will call the following method from `Model` :
+- `getAddressBook()`
+- `deleteNote(noteToDelete)`
+
+Step 5. `DeleteNoteCommand#execute()` will return a `CommandResult` object which will display the following message back to the user:
+> Deleted Note: Title: Meeting, Content: 3rd October 9pm
+
+The following sequence diagram shows how the addNote operation works:
+
+
+
+##### Design considerations
+
+**Aspect: How the note to be deleted is specified:**
+
+* **Alternative 1 (current choice):** Note is specified by index.
+ * Pros: Easy to implement.
+ * Cons: Would need to use listNotes command or gui to allow easy identification of index of note.
+
+* **Alternative 2:** Note is specified by Title.
+ * Pros: Would be more precise (Title of notes are unique).
+ * Cons: Long command would be needed to delete a note with a long Title.
+
+#### Edit Note
+
+The editNote mechanism is facilitated by `EditNoteCommand` and utilises the `FindNoteCommand`. It extends `Command` and overrides `Command#execute()` to implement the following operation:
+- `EditNoteCommand#execute()` : edits the note at the specified index (or with matching title) from the note list.
+
+Given below is an example usage scenario and how the editNote mechanism behaves at each step.
+
+Step 1. The user launches the application and wishes to edit a note's title with a new title. The user lists the current notes:
+1. Title: Meeting, Content: 3rd October 9pm
+2. Title: Event, Content: Remind club members to attend.
+
+The user has decided to edit the first note titled `Meeting` with a new title, `Club Meeting`.
+
+Step 2a. If an index is entered (user executes `editNote 1 title/Club Meeting`), the `EditNoteCommandParser` carries this index to the `EditNoteCommand`, which retrieves the `Note` to edit by getting the `Model`'s current `FilteredList
+
+:information_source: **Note:** The lifeline for `InspectCommandSequence` and `InspectCommand` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.
+
+
+
+##### Design considerations:
+
+**Aspect: How to design a UI command**
+
+Unlike other command, this command does not mutate any underlying data. One challenge is that the execution flow is different from other commands which mutate data, making the implementation less direct.
+
+We had to find a good insertion point where the information carried from the user input could be used in the program without the need for major refactoring. We realised that the user's input is first taken in through the `MainWindow` class, and through following the function calls, would be used in `MainWindow::executeCommand`. So the inspection operation is effectively added at the end of the executeCommand just before it terminates.
+
+Inspiration was taken from the execution flow of `handleExit` and `handleHelp` prior to the construction of the new UI.
+
+The procedures for `handleExit` and `handleHelp` were changed by refactoring `CommandResult` to carry an ideal state that the UI is expected to be in by the end of the execution. A switch statement was added to the bottom of the `executeCommand` function, much like how the normal commands are parsed, to deal with UI-Centric commands like `help`, `exit` and `inspect`.
+
+#### Showing and Hiding the Notes Panel Feature
+
+Here are the anchor points of the three major panes within the `WindowAnchorPane`:
+
+- The `PersonListPanel` has a left anchor of `0`, top anchor of `0`, right anchor of `0.6` with respect to window width (starting from left) and bottom anchor of `0.45` with respect to window height (starting from top).
+- The `InspectionPanel` has a left anchor of `0`, top anchor of `0.45`, right anchor of `0.6` with respect to window width (starting from left) and bottom anchor of `0` with respect to window height (starting from top).
+- The `NotesListPanel` has a left anchor of `0.6`, top anchor of `0`, right anchor of `0` with respect to window width (starting from left) and bottom anchor of `0` with respect to window height (starting from top).
+
+Notice that the `PersonListPanel` and `InspectionPanel` share a boundary of the ratio `0.45` with respect to the window height and the both of them share a boundary of `0.6` with respect to screen width with the `NotesListPanel`.
+
+The command `hideNotes` is effectively accomplished by interpolating the ratios smoothly over time to create a sliding effect. To maintain the aspect ratio of the notes panel and prevent deformities, the right anchor interpolates from 0 to `0.6 - 1 = -0.4`, as the left anchor interpolates from `0.6` to `1`.
+
+This maintains the constant size of `x0.4` with respect to window size during the transition.
+
+A fading transition is applied across the same time to smoothly reduce the opacity of the panel.
+
+The time interval set for this transition is `0.3` seconds.
+
+The `showNotes` implementation is exactly the inverse of the `hideNotes` implementation across time.
+
+
+##### Design considerations:
+
+**Aspect: Challenges related to resizing**
+
+Because hiding the notes panel will also pull the inspection panel longer, and that the inspection panel is divided into two parts itself, the `InspectionPanel` is also further another anchor pane that maintains the ratio of the width between the basic information display and the loans history property.
+
+This concept was only implemented after the implementation of hideNotes, where visual inconsistencoes will start appearing due to disobeying the original ratio.
+
+The padding of the `InspectionPanel` also causes an issue if the right anchor of the pane is not manipulated with the left anchor, as the padding will snap the left anchor to the right of the right anchor. This causes the `InspectionPanel` to be pulled through the entire width of the `NotesListPanel` cause the entire `WindowAnchorPane` to overflow its allocated width. The consideration to slide the right anchor at a constant difference with respect to the left anchor was introduced to combat this issue.
+
### \[Proposed\] Undo/redo feature
-#### Proposed Implementation
+##### 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:
@@ -176,7 +714,7 @@ Step 2. The user executes `delete 5` command to delete the 5th person in the add
-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`.
+Step 3. The user executes `add name/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`.
@@ -211,7 +749,7 @@ Step 5. The user then decides to execute the command `list`. Commands that do no
-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`, 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 name/David …` command. This is the behavior that most modern desktop applications follow.
@@ -219,26 +757,21 @@ The following activity diagram summarizes what happens when a user executes a ne
-#### Design considerations:
+##### 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.
+ * 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.
+ * 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**
@@ -257,42 +790,101 @@ _{Explain here how the data archiving feature will be implemented}_
**Target user profile**:
+* is acting as a secretary or a treasurer of a club with a lot of people
+* has a need for a convenient way to organise paperwork and general information about the club
* has a need to manage a significant number of contacts
+* has a requirement to keep notes and tabs on people and projects
* prefer desktop apps over other types
* can type fast
* prefers typing to mouse interactions
* is reasonably comfortable using CLI apps
-**Value proposition**: manage contacts faster than a typical mouse/GUI driven app
+**Value proposition**: manage club members and track notes faster than a typical mouse/GUI driven app or by pen and paper
### User stories
Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unlikely to have) - `*`
-| Priority | As a … | I want to … | So that I can… |
-| -------- | ------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------- |
-| `* * *` | new user | see usage instructions | refer to instructions when I forget how to use the App |
-| `* * *` | user | add a new person | |
-| `* * *` | user | delete a person | remove entries that I no longer need |
-| `* * *` | user | find a person by name | locate details of persons without having to go through the entire list |
-| `* *` | user | hide private contact details | minimize chance of someone else seeing them by accident |
-| `*` | user with many persons in the address book | sort persons by name | locate a person easily |
+| Priority | As a … | I want to … | So that I can… |
+|----------|----------------------------------|---------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
+| `* * *` | secretary | add club members’ information into the address book | keep track of their contact information. |
+| `* * *` | secretary | edit a club member’s information | stay updated with them if their contact information changes. |
+| `* * *` | secretary | delete a club member’s information from the address book | stop keeping track of them when they leave the club. |
+| `* * *` | user | search for a person by their name or contact number | locate details of persons without having to go through the entire list. |
+| `* *` | secretary | search contacts according to a specific tag | easily contact people in a whole group. |
+| `*` | user | maintain a set of tasks to be done | keep track of things to be done. |
+| `* * *` | treasurer | see the amount each person owes me | keep track of my finances. |
+| `*` | person that keeps track of tasks | see who in my contacts lies under which tasks and which tasks lies under each contact | keep track of my deadlines. |
+| `*` | treasurer | keep track of my club's fund and the budget assigned to every project | better organise and plan the club's finances. |
+| `*` | secretary | archive the contact information of a club member that has left the club | contact old club members by looking at archived contacts. |
+| `* *` | expert user | quickly use the CLI commands to speed up operations | enhance the productivity of meetings and task recording. |
+| `* *` | secretary | pinpoint all the addresses of members and find the nearest amongst all members | organise club activities and events that minimise travel time. |
+| `* * *` | treasurer | identify which member owes the club money | |
+| `* *` | secretary | password protect the software | protect member's personal data. |
+| `* *` | busy treasurer | get reminded of upcoming payments | ask for payments before they are due. |
+| `*` | user | use the GUI elements to autofill the CLI | recognise and learn the commands for future typing. |
+| `* *` | user | configure the GUI elements' size and colours | customise the application to my needs. |
+| `* *` | secretary | set priorities on tasks | focus on tasks that are more important first. |
+| `*` | secretary | get statistics on the number of tasks done | ensure that the club is on track with finishing tasks. |
+| `*` | new user | learn how to use the commands using in-app guidance | easily pick up the commands and perform my duties |
+| `* *` | new user | have sample data that I can test out commands with | familiarize myself with how the application works. |
+| `* * *` | outgoing secretary | transfer the data to an incoming secretary | hand over my job without hassle. |
-*{More to be added}*
### Use cases
-(For all use cases below, the **System** is the `AddressBook` and the **Actor** is the `user`, unless specified otherwise)
+(For all use cases below, the **System** is the `SectresBook` and the **Actor** is the `user`, unless specified otherwise)
+
+#### Use case: UC1 - Add a person
+
+**MSS**
+1. User requests to add a person.
+2. SectresBook adds the person to the list of persons.
+
+ Use case ends.
+
+**Extensions**
+* 1a. The given person already exists.
+ * 1a1. SectresBook shows an error message.
+
+ Use case ends.
+* 1b. Necessary fields are incomplete/empty.
+ * 1b1. Sectresbook shows an error message.
+
+ Use case ends.
+
+#### Use case: UC2 - Update a person
+
+**MSS**
+1. User requests to list persons.
+2. SectresBook shows a list of persons.
+3. User requests to update a specific person in the list.
+4. SectresBook updates information of the person.
+
+ Use case ends.
+
+**Extensions**
+* 2a. The list is empty.
+
+ Use case ends.
+* 3a. The given index is invalid.
+ * 3a1. SectresBook shows an error message.
+
+ Use case resumes at step 2.
+* 3b. The command line arguments are invalid.
+ * 3b1. SectresBook shows an error message.
+
+ Use case resumes at step 2.
-**Use case: Delete a person**
+#### Use case: UC3 - Delete a person
**MSS**
-1. User requests to list persons
-2. AddressBook shows a list of persons
-3. User requests to delete a specific person in the list
-4. AddressBook deletes the person
+1. User requests to list persons.
+2. SectresBook shows a list of persons.
+3. User requests to delete a specific person in the list.
+4. SectresBook deletes the person.
Use case ends.
@@ -304,24 +896,197 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
* 3a. The given index is invalid.
- * 3a1. AddressBook shows an error message.
+ * 3a1. SectresBook shows an error message.
Use case resumes at step 2.
-*{More to be added}*
+#### Use case: UC4 - Find a person
-### Non-Functional Requirements
+**MSS**
+1. User request to find using keyword.
+2. SectresBook shows a list of persons matching keyword.
+
+ Use case ends.
+
+#### Use case: UC5 - Display list of persons
+
+**MSS**
+1. User requests to list persons.
+2. SectresBook displays the list of persons stored.
-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 persons 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.
+ Use case ends.
-*{More to be added}*
+#### Use case: UC6 - Edit Loan of person
+
+**MSS**
+1. User requests to list persons.
+2. SectresBook shows a list of persons.
+3. User requests to update the loan of a specific person in the list.
+4. SectresBook updates loan and loan history of the person.
+
+**Extensions**
+* 2a. The list is empty.
+
+ Use case ends.
+* 3a. The given index is invalid.
+ * 3a1. SectresBook shows an error message.
+
+ Use case resumes at step 2.
+* 3b. The command line arguments are invalid.
+ * 3b1. SectresBook shows an error message.
+
+ Use case resumes at step 2.
+
+
+#### Use case: UC7 - Find Person by their tag
+
+**MSS**
+1. User requests to find using a tag keyword.
+2. SectresBook shows a list of persons matching the tag keyword.
+
+ Use case ends.
+
+#### Use case: UC8 - Add a Note
+
+**MSS**
+1. User requests to add a note.
+2. SectresBook adds the note to the list of notes.
+
+ Use case ends.
+
+**Extensions**
+* 1a. The given note title already exists.
+ * 1a1. SectresBook shows an error message.
+
+ Use case ends.
+* 1b. Necessary fields are incomplete/empty.
+ * 1b1. Sectresbook shows an error message.
+
+ Use case ends.
+
+#### Use case: UC9 - Update a Note
+
+**MSS**
+1. User requests to list notes.
+2. SectresBook shows a list of notes.
+3. User requests to update a specific note in the list.
+4. SectresBook updates information of the note.
+
+ Use case ends.
+
+**Extensions**
+* 2a. The list is empty.
+
+ Use case ends.
+* 3a. The given index is invalid.
+ * 3a1. SectresBook shows an error message.
+
+ Use case resumes at step 2.
+* 3b. The command line arguments are invalid.
+ * 3b1. SectresBook shows an error message.
+
+ Use case resumes at step 2.
+
+#### Use case: UC10 - Delete a Note
+
+**MSS**
+1. User requests to list notes.
+2. SectresBook shows a list of notes.
+3. User requests to delete a specific note in the list.
+4. SectresBook deletes the person.
+
+ Use case ends.
+
+**Extensions**
+
+* 2a. The list is empty.
+
+ Use case ends.
+
+* 3a. The given index is invalid.
+
+ * 3a1. SectresBook shows an error message.
+
+ Use case resumes at step 2.
+
+#### Use case: UC11 - Find a Note
+
+**MSS**
+1. User request to find using keyword.
+2. SectresBook shows a list of notes matching keyword.
+
+ Use case ends.
+
+#### Use case: UC12 - Display list of notes
+
+**MSS**
+1. User has completed [UC11](#use-case-uc11---display-list-of-notes)
+2. User requests to list notes.
+3. SectresBook displays the list of all notes stored.
+
+ Use case ends.
+
+#### Use case: UC13 - Hide Note section
+
+**MSS**
+1. User requests to hide the notes section of the Sectresbook.
+2. Sectresbook hides the note section, extending the addressbook section.
+
+ Use case ends.
+
+**Extensions**
+* 1a. Already hiding the notes section.
+
+ Use case ends.
+
+#### Use case: UC14 - Show note section
+
+**MSS**
+1. User requests to show the notes section.
+2. Sectresbook shows the notes section on the right side of the interface.
+
+ Use case ends.
+
+**Extensions**
+
+* 1a. Already showing the notes section.
+
+ Use case ends.
+
+#### Use case: UC15 - Exit program
+
+**MSS**
+1. User requests to exit program.
+2. Sectresbook closes the program.
+
+ Use case ends.
+
+### Non-Functional Requirements
+
+1. Should run independently of remote servers.
+2. Should not use a relational database management system to store data.
+3. Should work on any _mainstream OS_ as long as it has Java `11` or above installed.
+4. Should not require internet connection, all operations are performed locally.
+5. Should not consume a lot of battery to keep it running in the background.
+6. Should be able to hold up to 1000 persons without a noticeable sluggishness in performance for typical usage.
+7. Should be able to hold up to 1000 notes without a noticeable sluggishness in performance for typical usage.
+8. Should be able to respond to any commands within 2 seconds as long as there are under 1000 entries stored in the application.
+9. 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.
+10. Should automatically save any changes to the data in the storage directly.
+11. The product is intended only for a single user (i.e. not a multi-user product)
### Glossary
* **Mainstream OS**: Windows, Linux, Unix, OS-X
+* **Java 11**: Eleventh version of the Java Platform, Standard Edition Development Kit (JDK). SectresBook requires this to be installed to run.
* **Private contact detail**: A contact detail that is not meant to be shared with others
+* **Note**: A segment of text that describes a task to be done, coupled with tags that reference people in the SectresBook who are associated with the given task.
+* **Secretary**: A person acting as overseers for the administrative functions of a club.
+* **Treasurer**: A club member that manages and accounts for all the funds of a club.
+* **Tag**: A label that groups related people or notes together, such that they can be referred to as a single encapsulated entity specified by the tag.
+* **Graphical User Interface (GUI)**: An image-based interface that is more visually appealing than a command-line interface and encapsulates information through the use of icons and images.
+* **Command Line Interface (CLI)**: A text-based interface that receives typed commands as input and returns textual feedback as output.
+
--------------------------------------------------------------------------------------------------------------------
@@ -338,40 +1103,249 @@ testers are expected to do more *exploratory* testing.
1. Initial launch
- 1. Download the jar file and copy into an empty folder
+ 1. Download the jar file and copy into an empty folder
- 1. Double-click the jar file Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.
+ 1. Double-click the jar file Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.
1. Saving window preferences
- 1. Resize the window to an optimum size. Move the window to a different location. Close the window.
+ 1. Resize the window to an optimum size. Move the window to a different location. Close the window.
- 1. Re-launch the app by double-clicking the jar file.+ 1. Re-launch the app by double-clicking the jar file.
Expected: The most recent window size and location is retained. -1. _{ more test cases … }_ - ### Deleting a person 1. Deleting a person while all persons are being shown - 1. Prerequisites: List all persons using the `list` command. Multiple persons in the list. - - 1. Test case: `delete 1`
- Expected: First contact is deleted from the list. Details of the deleted contact shown in the status message. Timestamp in the status bar is updated. - - 1. Test case: `delete 0`
- Expected: No person is deleted. Error details shown in the status message. Status bar remains the same. - - 1. Other incorrect delete commands to try: `delete`, `delete x`, `...` (where x is larger than the list size)
- Expected: Similar to previous. - -1. _{ more test cases … }_ - -### Saving data - -1. Dealing with missing/corrupted data files - - 1. _{explain how to simulate a missing/corrupted file, and the expected behavior}_ - -1. _{ more test cases … }_ + 1. Prerequisites: List all persons using the `list` command. Multiple persons in the list. + + 2. Test case: `delete 1`
+ Expected: First contact is deleted from the list. Result display shows details of the deleted contact. + + 3. Test case: `delete 0`
+ Expected: No person is deleted. Result display shows error message stating non-positive indices not allowed. + + 4. Test case: `delete Charlotte`, assuming there is only 1 person with the name `Charlotte` in the Sectresbook.
+ Expected: Person with name `Charlotte` is deleted from the list. Result display shows details of the deleted contact. + + 5. Other incorrect delete commands to try: `delete`, `delete x`, `...` (where x is larger than the list size)
+ Expected: Similar to previous. + +2. Deleting a person, but not all persons are shown + + 1. Prerequisites: List a subset of persons using the `find` command. At least 1 person in the list. + + 2. Test case: `delete 1`, assuming there is more than or equal to 1 person in the Sectresbook.
+ Expected: First contact is deleted from the list. Result display shows details of the deleted contact. + + 3. Test case: `delete -1`
+ Expected: No person is deleted from the list. Result display shows error message stating non-positive indices not allowed. + + 4. Test case: `delete Charlotte`, assuming there is only 1 person with the name `Charlotte` in the Sectresbook.
+ Expected: Person with name `Charlotte` is deleted from the list. Result display shows details of the deleted contact shown. + + 5. Test case: `delete Sean`, assuming there is more than 1 person with the name `Sean` in the Sectresbook.
+ Expected: No person is deleted from the list. Sectresbook lists the contacts with `Sean` in their name. Result display shows error message stating more than one person with that name. + + 6. Other incorrect delete commands to try: `delete`, `delete phone/PHONE_NUMBER`, `...` (where `PHONE_NUMBER` is a phone number of a person).
+ Expected: No person is deleted from the list. Result display shows error message stating invalid command format. + +### Editing a person + +1. Editing a person after listing all persons or after finding a list of persons (list should contain more than 0 people). + + 1. Test case: `edit 1 phone/98112233`, assuming there is more than or equal to 1 person in the Sectresbook.
+ Expected: Phone number of the first contact in the list is edited. Result display shows details of the edited contact. + + 2. Test case: `edit 5 tag/Friend`, assuming there is less than 5 people currently displayed in the Sectresbook.
+ Expected: No person is edited. Result display shows error message stating invalid index. + + 3. Test case: `edit Charlotte tag/Friend`, assuming there is only 1 person with the name `Charlotte` in the Sectresbook.
+ Expected: The tag of the Person with the name `Charlotte` is edited. Result display shows details of the edited contact. + + 4. Test case: `edit Sean tag/Colleague`, assuming there is more than 1 person with the name `Sean` in the Sectresbook.
+ Expected: No person is edited from the list. Sectresbook shows the list of persons with `Sean` in their name. Result display shows error message stating more than one person with that name. + + 5. Other incorrect edit commands to try: `edit`, `edit 2 phone/TEXT`, `...` (where `TEXT` is an input with only alphabets).
+ Expected: No person is edited in the list. Result display shows error message stating phone number should be only contain numbers and at least 3 digits. + +### Editing a loan of a person + +1. Editing a loan of a person after listing all persons or after finding a list of persons (list should contain more than 0 people). + + 1. Test case: `editLoan 1 amt/10 reason/Logistics`, assuming there is more than or equal to 1 person in the Sectresbook.
+ Expected: Loan amount and history of the first contact is updated. Result display shows details of the edited contact. + + 2. Test case: `editLoan 5 amt/100 reason/Logistics`, assuming there is less than 5 people currently displayed in the Sectresbook.
+ Expected: No person is edited. Result display shows error message stating invalid index provided. + + 3. Test case: `editLoan Charlotte amt/10 reason/Test`, assuming there is only 1 person with the name `Charlotte` in the Sectresbook.
+ Expected: Loan amount and history of the Person with the name `Charlotte` is edited. Result display shows details of the edited contact. + + 4. Test case: `editLoan Sean amt/10 reason/Test`, assuming there is more than 1 person with the name `Sean` in the Sectresbook.
+ Expected: No person is edited from the list. Sectresbook shows the list of persons with `Sean` in their name. Result display shows error message stating more than one person with that name. + + 5. Other incorrect editLoan commands to try: `editLoan`, `editLoan amt/`,`editLoan 1 amt/TEXT reason/TEXT`, `...` (where `TEXT` is an input with only alphabets).
+ Expected: No person is edited in the list. Result display shows error message stating invalid command format. + +### Finding a person + +1. Finding a person with the given keyword. + + 1. Test case: `find Ryan`, assuming there is at least 1 person with the substring `Ryan` in the Sectresbook.
+ Expected: Person list is updated with contacts that contain the substring `Ryan`. Result display shows the number of persons listed. + + 2. Test case: `find Jack`, assuming there is no one with the substring `Jack`.
+ Expected: Person list is updated, showing nobody in the list. Result display shows the number of persons listed. + + 3. Test case: `find 8445`, assuming there is at least 1 person with phone number starting with `8445` in the Sectresbook.
+ Expected: Person list is updated with contacts with phone number starting with `8445`. Result display shows the number of persons listed. + + 4. Test case: `find 8445 Ryan`, assuming there is at least 1 person with phone number starting with `8445` and substring `Ryan` in their name in the Sectresbook.
+ Expected: Person list is updated with contacts that contain the substring `Ryan` and phone number starting with `8445`. Result display shows the number of persons listed. + + 5. Incorrect editLoan command to try: `editLoan`.
+ Expected: No change in the list shown. Result display shows message stating invalid command format. + +### Listing a person + +1. Listing all persons in the Sectresbook. + + 1. Test case: `list`
+ Expected: Person list is updated to show all persons in the Sectresbook. Result display shows success message. + + 2. Test case: `list TEXT`, where `TEXT` is any string input.
+ Expected: Person list is updated to show all persons in the Sectresbook. Result display shows success message. + +### Inspecting a person + +1. Inspecting a person while all persons are shown. + + 1. Test case: `inspect 1`, assuming there is at least 1 person shown in the person list.
+ Expected: Displays the information of the contact with index 1 in the person list. Result display shows success message. + + 2. Test case: `inspect Charlotte`, assuming there is only 1 person with the name `Charlotte` in the Sectresbook.
+ Expected: Displays the information of the contact with name `Charlotte` in the person list. Result display shows success message. + + 3. Test case: `inspect -1`
+ Expected: No change in the person being inspected. Result display shows error message stating inspection failed, name should be alphanumeric characters only. + + 4. Test case: `inspect Jack`, assuming there is more than 1 person with the name `Jack` in the person list.
+ Expected: No change in the person currently being inspected. Result display shows error message stating more than one person with that name. + + 5. Other incorrect inspect commands to try: `inspect`.
+ Expected: No change in the person currently being inspected. Result display shows error message stating nothing to inspect. + + +### Adding a note + +1. Adding a note with title that is yet to exist + 1. Test case: `addNote title/event content/november 3rd 4pm`
+ Expected: Note with title `event` and content `november 3rd 4pm` added into notes list. Result display shows message stating new note is added. Notes display panel shows new note. + + 2. Test case: `addNote title/event content/november 3rd 4pm tag/progs`
+ Expected: Result display shows message stating new note is added. Notes display panel shows new note. + + 3. Test case: incorrect `addNote` commands (e.g. `addNote`, `addNote title/event`, `addNote content/groceries`)
+ Expected: No new note is added to notes list. Result display shows error message stating invalid command format. + +2. Adding a note with a duplicate title + 1. Test case: `addNote title/event content/november 3rd 4pm`
+ Expected: No new note is added to notes list. Result display shows message stating that note already exists in the notes list. No change to the notes display panel. + +### Editing a note + +1. Editing a note + 1. Test case: `editNote 1 content/meeting at mpsh`, assuming there exists at least 1 note in the current notes list.
+ Expected: Note at index 1 in the current notes list have its content changed to `meeting at mpsh`. Result display shows message stating note was edited. + + 2. Test case: `editNote progs content/meeting at mpsh`, assuming there exists a note with title `progs`.
+ Expected: Note with title `progs` in the current notes list have its content changed to `meeting at mpsh`. Result display shows message stating note was edited. + + 3. Test case: `editNote 5 content/meeting at mpsh`, assuming there are less than 5 notes in the current notes list.
+ Expected: No note was edited. Result display shows error message stating index provided to be invalid. + + 4. Test case: `editNote content/meeting at mpsh`
+ Expected: No note was edited. Status bar display error message stating at least one field to be edited has to be provided. + + 5. Test case: incorrect `editNote` commands (e.g. `editNote`, `editNote content/abc`)
+ Expected: No note was edited. Result display shows error message stating invalid command format. + +### Deleting a note + +1. Deleting a note + 1. Test case: `deleteNote 1`, assuming there exists at least 1 note in the current notes list.
+ Expected: Note at index 1 is removed from the current notes list. Result display shows message stating note was deleted. + + 2. Test case: `deleteNote`
+ Expected: No note was deleted. Result display shows error message stating invalid command format. + +### Finding a note + +1. Finding a note + 1. Test case: `findNote progs`
+ Expected: Notes with title containing the keyword `progs` are shown on the notes display panel. Result display shows message stating number of notes listed. + If there are no notes with `progs` in the title, notes display panel will be empty. + + 2. Test case: `findNote`
+ Expected: No change to the notes display panel. Status bar display error message stating invalid command format. + +### List all notes + +1. List notes + 1. Test case: `listNote`
+ Expected: Notes display panel is populated with all existing notes. Result display shows message stating listed all notes. + +### Hide notes + +1. Hide notes + 1. Test case: `hideNotes`, assuming notes display panel is on shown on the GUI.
+ Expected: Notes display panel is hidden from the GUI. Persons list and Inspect section is extended horizontally to fill the GUI. Result display shows message stating notes panel hidden. + + 2. Test case: `hideNotes`, assuming notes display panel is already hidden. Result display shows message stating notes panel hidden.
+ Expected: No change to the GUI. Result display shows message stating notes panel hidden. + + 3. Other `hideNotes` commands with additional arguments (e.g. `hideNotes 1`, `hideNotes abc`)
+ Expected: Additional arguments are ignored, behaviour is same as `hideNotes`. + +### Show notes + +1. Show notes + 1. Test case: `showNotes`, assuming notes display panel is hidden from GUI.
+ Expected: Notes display panel appears on the right side of the GUI. Persons list and Inspect section becomes horizontally narrower. Result display shows message stating notes panel shown. + + 2. Test case: `showNotes`, assuming notes display panel is already shown on the GUI.
+ Expected: No change to the GUI. Result display shows message stating notes panel shown. + + 3. Other `showNotes` commands with additional arguments (e.g. `showNotes 1`, `showNotes abc`)
+ Expected: Additional arguments are ignored, behaviour is same as `showNotes`. + +### Finding person/notes based on tag + +1. Find using tag + 1. Test case: `findTag cs2103`
+ Expected: Persons list display persons tagged with `cs2103`. Notes display panel displays notes tagged with `cs2103`. Result display shows message stating number of people listed in the persons list.
+ If there is no person tagged with `cs2103`, the persons list will be empty.
+ If there is no note tagged with `cs2103`, the notes display panel will be empty. + +### Viewing Help + +1. Viewing help bar. + + 1. Test case: `help`
+ Expected: The help popup screen is shown. + +### Clearing all data + +1. Clearing all data + + 1. Test case: `clear`
+ Expected: Clears all data from the Sectresbook. + +### Exiting program + +1. Exiting the Sectresbook + + 1. Test case: `exit`
+ Expected: The program closes. diff --git a/docs/SettingUp.md b/docs/SettingUp.md index 275445bd551..1de01ecf4d1 100644 --- a/docs/SettingUp.md +++ b/docs/SettingUp.md @@ -45,7 +45,7 @@ If you plan to use Intellij IDEA (highly recommended): 1. **Learn the design** - When you are ready to start coding, we recommend that you get some sense of the overall design by reading about [AddressBook’s architecture](DeveloperGuide.md#architecture). + When you are ready to start coding, we recommend that you get some sense of the overall design by reading about [SectresBook’s architecture](DeveloperGuide.md#architecture). 1. **Do the tutorials** These tutorials will help you get acquainted with the codebase. diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 3716f3ca8a4..cf57b6f6e2f 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -3,38 +3,469 @@ layout: page title: User Guide --- -AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized for use via a Command Line Interface** (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, AB3 can get your contact management tasks done faster than traditional GUI apps. +# SectresBook -* Table of Contents -{:toc} +
+
+
+SectresBook is already a convenient way to keep track of information you need to manage a club. However, if you can type fast, using SectresBook will be quicker and more efficient.
+
+
+[Back to Table of Contents](#table-of-contents)
+
+---
+
+## Using this guide
+
+This user guide contains all the information that you will need to use and learn **SectresBook**.
+
+If you are a **new user**, the necessary knowledge for you to get started can be found [here](#quick-start).
+
+If you are an **experienced user**, a [Summary](#summary) is also provided, so you can quickly refer to the command formats.
+
+Before you delve into the guide, do take note of the following highlighted information panels.
+
+:information_source: **Note:** Used to highlight and display information you should
+pay attention to.
+
+:bulb: **Tip:** used to highlight tips which you might find useful
+
+:exclamation: **Caution:** used to highlight dangers and things to look out for.
+
+In addition, for better readability, icons in this guide have been colored black. In the actual application, colors may be inverted, but their shape will remain the same.
+
+:bulb: **Tip:** This User Guide contains many clickable links. Use the keyboard shortcuts
+
+[Back to Table of Contents](#table-of-contents)
+
+---
## Quick start
-1. Ensure you have Java `11` or above installed in your Computer.
+1. Ensure you have Java `11`[7](#glossary) or above installed in your Computer.
+
+1. Download the latest `SectresBook.jar` from [here](https://github.com/AY2223S1-CS2103T-W12-2/tp/releases).
+
+1. Copy the file to the folder you want to use as the _home folder_[5](#glossary) for your SectresBook.
+
+1. Double-click the file to start the app. A GUI[4](#glossary) similar to the one below should appear in a few seconds. Note how the app contains some sample data. (Don't worry about the layout of the GUI[4](#glossary) yet! It will be explained in the next section.)
+ 
+
+1. We **strongly recommend** you to use this app at a resolution of 1024x640 or greater to experience the greatest level of comfort. You may also click the fullscreen icon at the top right hand corner of the window next to the close icon to maximise the window.
+
+1. Press your spacebar (recommended), or bring your cursor to the [command box](#command-box) area and click onto it, to access the typing space. The results display will come into view below the command box.
+
+1. Type commands in the [command box](#command-box) and press Enter to execute them. For example, typing **`help`** into the command box and pressing Enter will open the [help window](#viewing-help--help).
+ - Some example commands you can try:
+ - **`list`** : Lists all contacts.
+ - Alt + Left arrow and Alt + Right arrow to navigate back and forth between links quickly. (Command + Left arrow and Command + Right arrow for Mac)add name/John Doe phone/98765432 email/johnd@example.com home/John street, block 123, #01-01 bday/01/01/2000 : Adds a contact named `John Doe` to the SectresBook.
+ - **`delete 3`** : Deletes the 3rd contact shown in the current list.
+ - **`help`** : Opens a [help window](#viewing-help--help).
+ - **`clear`** : Deletes all contacts.
+ - **`exit`** : Exits the app.
+
+1. Once you are done executing commands and want to see the GUI, press the `ESC` key (recommended), or click on anywhere that is not the command box, to leave the typing space and hide the results display.
+
+Refer to [Features](#features) below for details of each command.
+
+[Back to Table of Contents](#table-of-contents)
+
+---
+
+## User Interface
+
+Here is an overview of the User Interface (UI) components.
+
+The UI comprises four sections:
+
+
+
+### Command Box
+
+The Command Box is where you type in your command inputs. For more information on command inputs, refer to [Features](#features) below.
+
+Once the command box is selected, a results display will appear to report the status of the program to you. Error messages and success messages will be shown in this box. Click anywhere else on the screen, or press the `ESC` key to exit the command box and hide the results display.
+
+
+ 
+
+ +
:bulb: **Tip:**
+You may activate the command box by simply pressing the spacebar on your keyboard. There is no need to use your mouse to click on the bar.
+
+
+:bulb: **Tip:**
+Similarly, you may press the `ESC` key on your keyboard to exit out of the command box and hide the results display.
+
+
+[Back to Table of Contents](#table-of-contents)
+
+### People Panel
+
+The People Panel contains all the club and organisation members you have registered in this book. They are laid out horizontally. You can scroll the list by hovering your mouse over the People Panel and scrolling the mouse-wheel, or by clicking on and dragging the horizontal scroll bar to scroll.
+
+Each card represents a person and displays their name, phone number and total present loan amount. The loan amount may be positive to indicate an amount owed by the person, or negative to indicate an amount due to be paid to the person.
+
+
+ 
+
+ 
+
+
+
+
+- Identified by the prefix `name`.
+- This is a valid property[12](#glossary) to find a person by using the [`find` command](#locating-persons-by-name-or-contact-number--find).
-1. Download the latest `addressbook.jar` from [here](https://github.com/se-edu/addressbook-level3/releases).
+| Valid Examples | +
+ Samuel West+ Jonathan Lee Wen Xin+ Jack Robert the 3rd+ 3Lite M1k0ch1+ Elizabeth Wong n11
+ |
+
|---|---|
| Invalid Examples | +
+ @*)^% (Non-alphanumeric characters are not accepted)+ Jack Robert the 3 (Number may not exist as a standalone word)+ Elizabeth Wong 11 (Number may not exist as a standalone word)+ Jonathan 25 Chin (Number may not exist as a standalone word)+ (25) Jonathan Chin (Non-alphanumeric characters cannot be used adjacent to numbers)+ |
+
:bulb: **Tip:**
+It is recommended to include the full name of the person instead of aliases for easier searching.
+
+
+[Back to Table of Contents](#table-of-contents)
+
+#### Phone
+
+This is the phone number of the person to be recorded in the SectresBook. It is compulsory to declare this during initialisation[6](#glossary).
+
+This property[12](#glossary) can be identified in the GUI[4](#glossary) by the icon of a mobile phone.
+
+
+
+- Identified by the prefix `phone`.
+- A phone number should contain only numbers and be at least 3 digits long.
+- This is a valid property[12](#glossary) to find a person by using the [`find` command](#locating-persons-by-name-or-contact-number--find).
+
+Please record the phone number by which the member is most easily contacted. You are not allowed to enter multiple phone numbers in this field.
+
+:exclamation: **Caution:**
+Ensure that no two persons have the same phone number! This is allowed in the program, but you may have difficulties contacting the person you want in the future.
+
+
+[Back to Table of Contents](#table-of-contents)
+
+#### Email
+
+This is the email address of the person to be recorded in the SectresBook. It serves mainly as a point of information regarding the person, and has no additional features tied to it. This property[12](#glossary) is compulsory to declare during initialisation[6](#glossary).
+
+This property[12](#glossary) can be identified in the GUI[4](#glossary) by the icon of an envelope.
+
+
+
+- Identified by the prefix `email`.
+- Emails should be of the format `local-part@domain` and adhere to the following constraints:
+
+| Part | Constraint |
+|------|-------------|
+| Local part | The local-part should only contain alphanumeric characters[1](#glossary) and these special characters `_`, `.`, `+` and `-`. The local-part may not start or end with any special characters and special characters may not be adjacent to each other. + Domain name | The domain name is made up of domain labels separated by periods. The domain name must:
- end with a domain label at least 2 characters long
- have each domain label start and end with alphanumeric characters[1](#glossary)
- have each domain label consist of alphanumeric characters[1](#glossary), separated only by hyphens, if any. + +The local part and domain part **must** be connected by an `@` symbol. + +[Back to Table of Contents](#table-of-contents) + +#### Address +This is the residing address of the person. It serves mainly as a point of information regarding the person, and has no additional features tied to it. This property[12](#glossary) is compulsory to declare during initialisation[6](#glossary). + +This property[12](#glossary) can be identified in the GUI[4](#glossary) by the icon of a house. + +
+
+- Identified by the prefix `home`.
+- There is no constraint on how the home address of a person should be written, as long as it is sufficiently understandable.
+
+:information_source: **Note:**
+Please ensure that your SectresBook window can accommodate the length of the text. If you find the text being cut off and see ellipses `...` showing, please resize the SectresBook window to fit the text.
+
+
+[Back to Table of Contents](#table-of-contents)
+
+#### Loan
+This is amount of money that is owed by a person, or is to be paid to that person. This is a property[12](#glossary) that cannot be manipulated directly, but can only be edited with the [`editLoan` command](#editing-loan-of-a-person--editloan).
+
+This property[12](#glossary) can be identified in the GUI[4](#glossary) by the icon of the hand holding two stacks of coins.
+
+
+
+- A loan amount can be either negative, positive or zero.
+ + A positive value indicates an amount that the person has yet to pay to the organisation.
+ + A zero value indicates no outstanding loan.
+ + A negative value indicates an amount that should be paid back to the person.
+- Loans can only take up numerical values.
+- The maximum value this property[12](#glossary) can take is `$1,000,000,000,000.00` (1 trillion dollars ). Similarly, the minimum value is `-$1,000,000,000,000.00` (negative 1 trillion dollars). This should be more than sufficient for general purpose use.
+
+[Back to Table of Contents](#table-of-contents)
+
+#### Loan History
+A loan history is linked to the loans properties and describes the changes to the numeric values of the loans in detail. There is no way to declare this during initialisation[6](#glossary), but it can be modified by the [`editLoan` command](#editing-loan-of-a-person--editloan).
+
+This property[12](#glossary) is represented as a descending list on the right side of the inspection panel.
+
+
+
+The most recent transaction is recorded at the top, on the row next to the loans icon.
+
+The upward pointing red arrow signifies an amount loaned to this member in a transaction.
+
+
+
+The downward pointing green arrow signifies an amount that this member has paid back in a transaction.
+
+
+
+- Consists of the following sub-properties:
+ - Current loan value
+ - Change in amount from last value
+ - Reason for change
+
+:bulb: **Tip:**
+Including a reason for every change to a person's loan value reduces the risk of accidentally adding an incorrect amount to someone. It keeps a detailed tab of every increment and decrement in value.
+
-1. Double-click the file to start the app. The GUI similar to the below should appear in a few seconds. Note how the app contains some sample data.-  +[Back to Table of Contents](#table-of-contents) -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.
- Some example commands you can try: +#### Birthday +The birthday date of a person. This property[12](#glossary) is compulsory to declare during initialisation[6](#glossary). - * **`list`** : Lists all contacts. +This property[12](#glossary) can be identified in the GUI[4](#glossary) by the icon of a birthday cake. - * **`add`**`n/John Doe p/98765432 e/johnd@example.com a/John street, block 123, #01-01` : Adds a contact named `John Doe` to the Address Book. +
- * **`delete`**`3` : Deletes the 3rd contact shown in the current list.
+- Identified by the prefix `bday`.
+- Serves as a point of information for a person.
+- This must be a valid date in the form `dd/MM/yyyy`.
- * **`clear`** : Deletes all contacts.
+[Back to Table of Contents](#table-of-contents)
- * **`exit`** : Exits the app.
+#### Tags
+Persons can be linked to tag objects, which serve as markers that draw connections between different people as well as associated notes. This property[12](#glossary) is completely optional.
-1. Refer to the [Features](#features) below for details of each command.
+This property[12](#glossary) can be identified in the GUI[4](#glossary) by tag shaped labels with text inside them. They are usually located at the bottom right of each person card. If there is no such label, then it means this person has no associated tags.
+
+
+
+:bulb: **Tip:**
+Choose short, identifiable tag names.
+
+
+:exclamation: **Caution:**
+There is no limit to how many tags you can apply to an individual person, but applying too many tags increases confusion and decreases user experience. Please choose the most relevant tags to apply only.
+
+
+:bulb: **Tip:**
+Please refer to the [`Tag Properties`](#tag-properties) below for more information regarding tags.
+
+
+[Back to Table of Contents](#table-of-contents)
+
+### Notes Properties
+
+
+
+
:bulb: **Tip:**
+Choose short, identifiable tag names.
+
+
+:bulb: **Tip:**
+Please refer to the [`Tag Properties`](#tag-properties) section below for more information regarding tags.
+
+
+[Back to Table of Contents](#table-of-contents)
+
+### Tag Properties
+A tag is used to group together specific People and Notes.
+
+This way, searching for a tag brings up all the People and Notes that have the tag for easier classification of related information.
+
+- Identified by the prefix `tag`.
+- Tags can only consist of alphanumeric characters[1](#glossary).
+- Persons and Notes can hold tags.
+
+[Back to Table of Contents](#table-of-contents)
--------------------------------------------------------------------------------------------------------------------
@@ -45,148 +476,676 @@ AddressBook Level 3 (AB3) is a **desktop app for managing contacts, optimized fo
**:information_source: Notes about the command format:*** Words in `UPPER_CASE` are the parameters to be supplied by the user.
- e.g. in `add n/NAME`, `NAME` is a parameter which can be used as `add n/John Doe`. + e.g. in `add name/NAME`, `NAME` is a parameter which can be used as `add name/John Doe`. * Items in square brackets are optional.
- e.g `n/NAME [t/TAG]` can be used as `n/John Doe t/friend` or as `n/John Doe`. + e.g `name/NAME [tag/TAG]` can be used as `name/John Doe tag/friend` or as `name/John Doe`. + +* `
+ e.g `INDEX
- e.g. `[t/TAG]…` can be used as ` ` (i.e. 0 times), `t/friend`, `t/friend t/family` etc. + e.g. `[tag/TAG]…` can be used as ` ` (i.e. 0 times), `tag/friend`, `tag/friend tag/family` etc. * Parameters can be in any order.
- e.g. if the command specifies `n/NAME p/PHONE_NUMBER`, `p/PHONE_NUMBER n/NAME` is also acceptable. + e.g. if the command specifies `name/NAME phone/PHONE_NUMBER`, `phone/PHONE_NUMBER name/NAME` is also acceptable. * If a parameter is expected only once in the command but you specified it multiple times, only the last occurrence of the parameter will be taken.
- e.g. if you specify `p/12341234 p/56785678`, only `p/56785678` will be taken. + e.g. if you specify `phone/12341234 phone/56785678`, only `phone/56785678` will be taken. * Extraneous parameters for commands that do not take in parameters (such as `help`, `list`, `exit` and `clear`) will be ignored.
e.g. if the command specifies `help 123`, it will be interpreted as `help`.
Format: `find KEYWORD [MORE_KEYWORDS]`
-* The search is case-insensitive. e.g `hans` will match `Hans`
+* The search is not case-sensitive. 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`
+* Phone numbers starting with any of the given keywords (in digits), of at least 2 digits, will be returned.
Examples:
-* `find John` returns `john` and `John Doe`
+
* `find alex david` returns `Alex Yeoh`, `David Li`
-### Deleting a person : `delete`
-Deletes the specified person from the address book.
+* `find 86` returns `Theodore`
+
-Format: `delete INDEX`
+* `find 8` will not be accepted as a command, as searching by phone numbers must be of at least 2 digits.
-* Deletes the person at the specified `INDEX`.
-* The index refers to the index number shown in the displayed person list.
+[Back to Table of Contents](#table-of-contents)
+
+#### Listing all persons : `list`
+
+List of all persons in the SectresBook.
+
+
+
+The search is not case-sensitive. For example, `meeting` will match any notes containing the word `Meeting`. As in find for persons, the order of the keywords also does not matter, and `Meeting Club` will also match a note called `Club Meeting`.
+
+Please be informed that only the title will be search. Contents will not be searched through this command.
+
+Although the title may contain special characters such as `,`, `.`, `?` or `!`, these special characters are not accepted as part of a keyword. This is because punctuation are not normally associated as part of a word. During the parsing of the [title](#title), special characters are treated as spaces, so adjacent segments of the word containing it are treated as separate words.
+ * The keywords `?!` and `t-shirt` will not be allowed, as they contain special characters.
+ * `2` will match `shirt 2` but will not match `shirt2`, as `shirt2` is an entire word by itself.
+ * To search for `Upcoming club meeting!`, `meeting!` is not allowed as a keyword as it contains a special character, but `meeting` is allowed.
+ * `tshirt` will not match `t–shirt` as `t-shirt` is now treated as two words, `t` and `shirt` with the special character `-` being treated as a spacing.
+
+Format: `findNote KEYWORD [MORE_KEYWORDS]`
+
+Examples:
+* `findNote Meeting` returns `Club Meeting`, `Meeting!` and `Meeting 2`
+* `findNote Soon` returns `Payment (soon)`
+
+[Back to Table of Contents](#table-of-contents)
+
+#### Listing Notes : `listNote`
+
+Shows a list of all notes in the SectresBook.
+
+