Skip to content

Commit

Permalink
Update on user guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@SHni99
SHni99 committed Mar 24, 2023
1 parent 3b22782 commit 841cd7e
Show file tree
Hide file tree
Showing 2 changed files with 90 additions and 64 deletions.
112 changes: 64 additions & 48 deletions docs/DeveloperGuide.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
**Target user profile**:

Students from the National University of Singapore (NUS) who need to keep track of their contacts from different classes/ccas/clubs etc.
Students from the National University of Singapore (NUS) who need to keep track of their contacts from different
classes/ccas/clubs etc.

**Value proposition**:

Expand All @@ -9,14 +10,15 @@ contacts list for an easier way to set up proper communication channels. This ma
connections with their peers during their time in University.

**User stories**:

1. As a student, I can find all relevant university contacts/POCs for various purposes
2. As a student, I can delete the image for a person on my contact list
3. As a forgetful student, I can see who a person on my contact list looks like
4. As a user, I can add a contact so that I can keep track of my contacts.
5. As a user, I can view all contacts so that I can have an accessible list of contacts.
6. As a user, I can delete a contact so that I can remove unneeded and/or incorrect contacts.
7. As a student, I can to find other students in my classes that have been added as a contact so that I can ask them for help

7. As a student, I can to find other students in my classes that have been added as a contact so that I can ask them for
help

**Use cases**:

Expand Down Expand Up @@ -172,13 +174,16 @@ System repeats Step 1-2 until valid details are entered.
```

**Glossary** :

* Student: A user who belongs to a faculty and attends one or more classes with other students
* Tutor: A user who tutors students in one or more classes
* Faculty: a group of university departments concerned with a major division of knowledge
* Contact: A person of interest, either student or tutor, who's details have been recorded by the user

# Implementation

## Add Image Feature

### Add Image Implementation

The add-image mechanism is facilitated by `AddImageCommand`, `AddImageCommandParser` and `ImageUtil` class.
Expand All @@ -188,22 +193,27 @@ The add-image mechanism is facilitated by `AddImageCommand`, `AddImageCommandPar

The `AddImageCommandParser` parses the user input into index of contact and path to an image.
It returns a `AddImageCommand` with the 2 information retrieved.
`AddImageCommand#execute` copies the image provided by the user via a path and replaces the current image with the new one.
`AddImageCommand#execute` copies the image provided by the user via a path and replaces the current image with the new
one.
It also saves the file name of the new image to the `model`.

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

Step 1. When user wants to add an image to a contact, they use the `add-image` command.

Step 2. The `LogicManager` receives the command text from the user input and gives it to `AddressBookParser`. `AddressBookParser` calls `AddImageCommandParser` to parse the user input.
Step 2. The `LogicManager` receives the command text from the user input and gives it to `AddressBookParser`
. `AddressBookParser` calls `AddImageCommandParser` to parse the user input.

Step 3. The `AddImageCommandParser` retrieves the contact index as well as the image path and creates a `AddImageCommand`
Step 3. The `AddImageCommandParser` retrieves the contact index as well as the image path and creates
a `AddImageCommand`

Step 4. `AddImageCommand#execute` is called. The method calls `ImageUtil#importImage` to copy the image into the "profile_pictures/" directory.
Step 4. `AddImageCommand#execute` is called. The method calls `ImageUtil#importImage` to copy the image into the "
profile_pictures/" directory.
Once that is successful, `AddImageCommand#execute` proceeds to call `ImageUtil#deleteImage` to remove the current image.
Finally `AddImageCommand#execute` updates the model provided in the arguments.

> **Note**: If the path given is invalid or if the file at the given path is not a png/jpeg image, the command will not be completed.
> **Note**: If the path given is invalid or if the file at the given path is not a png/jpeg image, the command will not
> be completed.
The following sequence diagram shows how the add-image operation works:<br>
![AddImageSequenceDiagram](images/AddImageSequenceDiagram.png)
Expand All @@ -214,19 +224,22 @@ The following activity diagram summarizes what happens when a user executes add-
### Design considerations:

- Alternative 1 (current choice): Copy the image into application-created directory
- Pros:
- A single location to store/check for images
- Naming scheme determined by application
- Cons:
- Copying is a file I/O which have many caveats
- Pros:
- A single location to store/check for images
- Naming scheme determined by application
- Cons:
- Copying is a file I/O which have many caveats
- Alternative 2: Save the path provided by User
- Pros:
- Does not require any file I/O
- Easy to save as only the Path as a string
- Cons:
- Path is easily invalidated (e.g. user moves/deletes/renames the image)
- Pros:
- Does not require any file I/O
- Easy to save as only the Path as a string
- Cons:
- Path is easily invalidated (e.g. user moves/deletes/renames the image)

## Delete Image Feature

### Delete Image Implementation

The delete-image feature is facilitated by the classes `DeleteImageCommand`,
`DeleteImageCommandParser`, `ImageUtil`, and `ParserUtil`.
The `DeleteImageCommandParser` first parses through the user command to obtain
Expand All @@ -247,8 +260,8 @@ suitable, and wants to delete it. The user inputs `delete-image 4`.
desired index.

> **Note**: If the user inputs an index of a contact which currently does not have
an image, or if the user inputs an invalid index, an error will be returned to
the user
> an image, or if the user inputs an invalid index, an error will be returned to
> the user
Step 3: If the instruction was valid, `Model#deleteImage` is called to set the
image of the contact to the default image.
Expand All @@ -270,8 +283,9 @@ delete-image command:
![DeleteImageActivityDiagram](images/DeleteImageActivityDiagram.png)

### Design Considerations:

- **Alternative 1 (current choice):** Delete the existing image file from program
directory.
directory.
- Pros:
- Ensures application does not consume excess storage
- Cons:
Expand All @@ -283,8 +297,11 @@ directory.
- Cons:
- Application will take up increasingly more unnecessary storage during
its lifetime of usage

## Import Contacts Feature

### Import Contacts Implementation

The import feature is facilitated by the classes `ImportCommand`, `ImportCommandParser`,
`SocContacts` and `ChsContacts`. The `ImportCommandParser` first parses through the user
command to obtain the desired faculty to be imported. An instance of
Expand All @@ -310,35 +327,37 @@ with the valid faculty that was parsed
Step 4: `Model#addPerson` is called for however
many non-duplicate contacts are to be added.


The following sequence diagram shows how the import command works.

![ImportSequenceDiagram](images/ImportSequenceDiagram.png)


The following activity diagram summarizes what happens when a user executes an
import command:

![ImportActivityDiagram](images/ImportActivityDiagram.png)

### Design Considerations:

- **Alternative 1 (current choice):** ImportCommand#execute takes in a string to
determine which faculty of in-built contacts to import
determine which faculty of in-built contacts to import
- Pros:
- User input is easily parsed (as it is just a string), faster to read and
execute the command
execute the command
- Cons:
- Possibly bad OOP design, ImportCommand#execute should take in a Faculty object

- **Alternative 2:** ImportCommand#execute takes in a Faculty object instead of a string
to determine which faculty of in-built contacts to import
to determine which faculty of in-built contacts to import
- Pros:
- Better OOP design then simply taking in a string
- Cons:
- Input will take longer to parse as the string input has to be parsed into
a faculty object to be used as input to ImportCommand#execute

## Add Feature

### Add Implementation

The Add feature is facilitated by the classes `AddCommand`,
`AddCommandParser` and `ParserUtil`.
The `AddCommandParser` first parses through the user command to obtain
Expand All @@ -354,45 +373,42 @@ Step 1: User starts up the application and sees their list of contacts. User mus
[name] [status] [phone] [email] [address] as they are required by the system if not it will cause
an invalid exception.

Step 2: The user decides that the image given to the contact at index 4 is not
suitable, and wants to delete it. The user inputs `delete-image 4`.
`DeleteImageCommandParser#parse` is then called to parse this input for the
desired index.
Step 2: The user can add optional fields, that is the tags. Each of the tags is colour-coded based on its type.

> **Note**: If the user inputs an index of a contact which currently does not have
an image, or if the user inputs an invalid index, an error will be returned to
the user
> **Note**: If the user inputs a contact that exists in the contact list, or if the user misses out a compulsory
> input, an error will be thrown.
Step 3: If the instruction was valid, `Model#deleteImage` is called to set the
image of the contact to the default image.
Step 3: If the instruction was valid, `AddCommand#execute` is called to wrap the details into person and set the
person to the next available index.

Step 4: `ImageUtil#deleteImage` is then called to delete the existing image
from the program directory.
Step 4: User can use edit index to select the chosen person card and `EditCommand#execute` is then called to
change the contents inside and update the program directory.

The following sequence diagram shows how the delete-image operation works.
The following sequence diagram shows how the `add` operation works.

![AddSequenceDiagram](images/AddSequenceDiagram.png)

> **Note**: The lifeline of the `DeleteImageCommandParser` and `DeleteImageCommand`
> **Note**: The lifeline of the `AddCommandParser` and `AddCommand`
> should end at the destroy marker (X) but due to the limitations of PlantUML, the
> lifeline reaches the end of the diagram.
The following activity diagram summarizes what happens when a user executes a
delete-image command:
add command:

![AddActivityDiagram](images/AddActivityDiagram.png)

### Design Considerations:
- **Alternative 1 (current choice):** Delete the existing image file from program
directory.

- **Alternative 1 (current choice):** Improve on tags by adding more colours to the
program directory.
- Pros:
- Ensures application does not consume excess storage
- Ensures the labels are organised neatly in different colour
- Cons:
- Extra complexity in requiring file i/o operations
- Extra complexity in requiring to map the additional tag operations

- **Alternative 2:** Disregard deleting the image file from program directory.
- **Alternative 2:** Make status field compulsory from program directory.
- Pros:
- Easier to implement
- Easier to implement and user can search based on year and course
- Cons:
- Application will take up increasingly more unnecessary storage during
its lifetime of usage
- Application will not detect the input content from the users which could contain
non-related strings.
42 changes: 26 additions & 16 deletions docs/UserGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,15 +59,25 @@ Example:

## Add user contacts: `add`

Format: `add [name] [year/course] [phone number] [email] [address]`
Format: `add [name] [year/course] [phone number] [email] [address]` Optional to add: `t/TAGS`

* User is *required* to enter name and course
* Privacy information such as phone number and address can be optionals
* User is *required* to enter **name, status, phone number, email, address**
* Tags can be optional
* If the account exists, user can add in related field of interests to share with others

Example:
* `add Shenghan Y2/Computer-science 0 punngol place 696a #12-348` will displays user's name, year/course
and address only
* `add n/Shenghan s/Year2 Computer-science p/99999999 e/[email protected] a/punngol place 696a #12-348` will displays the
necessary basic information that are the user's name, year/course, phone number, email, address. Optional fields are tags,
for which there are commitment/cca tags, module tags and lastly the general tags for users to enter non-specific typed tags.

Example (with the addition of tags):
* `add n/Shenghan s/Year2 Computer-science p/99999999 e/[email protected] a/punngol place 696a #12-348 t/developer ct/soccer
mt/cs2103` Note that the tags can be placed in any part of the command, and it will not break!

Tags are categorised according to tag colors:
* Commitment tags: `coral pink`
* Module tags: `Dark green`
* General tags: `default blue`

## Delete user contacts: `delete`

Expand All @@ -92,15 +102,15 @@ Format: `help`

## Command summary

| Action | Format, Examples |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Add** | `add n/NAME y/YEAR COURSE p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​` <br> e.g., `add n/James Ho y/y2-science p/22224444 e/[email protected] a/123, Clementi Rd, 1234665 t/friend t/colleague` |
| **Delete** | `delete INDEX`<br> e.g., `delete 3` |
| **Edit** | `edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [t/TAG]…​`<br> e.g.,`edit 2 n/James Lee e/[email protected]` |
| **Find** | `find KEYWORD [MORE_KEYWORDS]`<br> e.g., `find James Jake` |
| **List** | `list` |
| **Help** | `help` |
| **Add-Image** | `add-image INDEX [NAME-OF-IMAGE]` <br> e.g., `add-image 2 weekiat.png` |
| **Delete-Image** | `delete-image INDEX` <br> e.g., `delete-image 2` | |
| **Import** | `import [faculty]` <br> e.g., `import soc, import chs` |
| Action | Format, Examples |
|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Add** | `add n/NAME y/YEAR COURSE p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG, ct/COMMITMENT_TAG, mt/MODULE_TAG]…​` <br> e.g., `add n/James Ho y/y2-science p/22224444 e/[email protected] a/123, Clementi Rd, 1234665 ct/soccer mt/cs1010s` |
| **Delete** | `delete INDEX`<br> e.g., `delete 3` |
| **Edit** | `edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [a/ADDRESS] [t/TAG]…​`<br> e.g.,`edit 2 n/James Lee e/[email protected]` |
| **Find** | `find KEYWORD [MORE_KEYWORDS]`<br> e.g., `find James Jake` |
| **List** | `list` |
| **Help** | `help` |
| **Add-Image** | `add-image INDEX [NAME-OF-IMAGE]` <br> e.g., `add-image 2 weekiat.png` |
| **Delete-Image** | `delete-image INDEX` <br> e.g., `delete-image 2` | |
| **Import** | `import [faculty]` <br> e.g., `import soc, import chs` |

0 comments on commit 841cd7e

Please sign in to comment.