Skip to content

Commit

Permalink
Merge pull request #276 from iynixil/232-dg-pagebreaks
Browse files Browse the repository at this point in the history 
Add page breaks in DG
  • Loading branch information
@whitesnowx
whitesnowx authored Apr 15, 2024
2 parents 5264ce0 + 9a82329 commit 1670564
Showing 1 changed file with 64 additions and 9 deletions.
73 changes: 64 additions & 9 deletions docs/DeveloperGuide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ title: Developer Guide

--------------------------------------------------------------------------------------------------------------------

<div style="page-break-after: always;"></div>

## **Acknowledgements**

* This developer guide is adapted from [AB-3 Developer Guide](https://se-education.org/addressbook-level3/DeveloperGuide.html).
Expand All @@ -19,6 +21,8 @@ Refer to the guide [_Setting up and getting started_](SettingUp.md).

--------------------------------------------------------------------------------------------------------------------

<div style="page-break-after: always;"></div>

## **Design**

<div markdown="span" class="alert alert-primary">
Expand Down Expand Up @@ -67,6 +71,8 @@ For example, the `Logic` component defines its API in the `Logic.java` interface

The sections below give more details of each component.

<div style="page-break-after: always;"></div>

### UI component

The **API** of this component is specified in [`Ui.java`](https://github.com/AY2324S2-CS2103-F08-3/tp/blob/master/src/main/java/staffconnect/ui/Ui.java)
Expand All @@ -86,6 +92,8 @@ The `UI` component,
* keeps a reference to the `Logic` component, because the `UIManager` relies on the `Logic` component to execute commands.
* depends on some classes in the `Model` component, as it displays `Person` object residing in the `Model` component.

<div style="page-break-after: always;"></div>

### Logic component

**API** : [`Logic.java`](https://github.com/AY2324S2-CS2103-F08-3/tp/blob/master/src/main/java/staffconnect/logic/Logic.java)
Expand All @@ -109,6 +117,8 @@ How the `Logic` component works:
Note that although this is shown as a single step in the diagram above (for simplicity), in the code it can take several interactions (between the command object and the `Model`) to achieve.
4. The result of the command execution is encapsulated as a `CommandResult` object which is returned back from `LogicManger`.

<div style="page-break-after: always;"></div>

Here are the other classes in `Logic` (omitted from the class diagram above) that are used for parsing a user command:

<img src="images/ParserClasses.png" width="600"/>
Expand All @@ -117,6 +127,8 @@ How the parsing works:
* When called upon to parse a user command, the `StaffConnectParser` class creates an `XYZCommandParser` (`XYZ` is a placeholder for the specific command name e.g., `AddCommandParser`) which uses the other classes shown above to parse the user command and create a `XYZCommand` object (e.g., `AddCommand`) which the `StaffConnectParser` returns back as a `Command` object.
* All `XYZCommandParser` classes (e.g., `AddCommandParser`, `DeleteCommandParser`, ...) inherit from the `Parser` interface so that they can be treated similarly where possible e.g, during testing.

<div style="page-break-after: always;"></div>

### Model component

**API** : [`Model.java`](https://github.com/AY2324S2-CS2103-F08-3/tp/blob/master/src/main/java/staffconnect/model/Model.java)
Expand All @@ -136,6 +148,8 @@ The `Model` component,

</div>

<div style="page-break-after: always;"></div>

### Storage component

**API** : [`Storage.java`](https://github.com/AY2324S2-CS2103-F08-3/tp/blob/master/src/main/java/staffconnect/storage/Storage.java)
Expand All @@ -147,12 +161,16 @@ The `Storage` component,
* inherits from both `StaffBookStorage` and `UserPrefStorage`, which means it can be treated as either one (if only the functionality of only one is needed).
* depends on some classes in the `Model` component (because the `Storage` component's job is to save/retrieve objects that belong to the `Model`)

<div style="page-break-after: always;"></div>

### Common classes

Classes used by multiple components are in the `staffconnect.commons` package.

--------------------------------------------------------------------------------------------------------------------

<div style="page-break-after: always;"></div>

## **Implementation**

This section describes some noteworthy details on how certain features are implemented.
Expand Down Expand Up @@ -197,6 +215,8 @@ This is to make sure at least one field is modified, or the command will not hav
Call `model.updateFilteredPersonList())` with a `Predicate` that always evaluates to true:
This is to refresh the list of `Person` in `Model` component.

<div style="page-break-after: always;"></div>

### Find feature

#### How the feature is implemented
Expand Down Expand Up @@ -232,6 +252,8 @@ Below are some explanations for the special considerations in the implementation
`FindCommmandParser` parsing the `Predicate` objects:
This is to prevent `FindCommand` from taking on more responsibilities (Separation of Concerns).

<div style="page-break-after: always;"></div>

### Filter feature

#### How the feature is implemented
Expand Down Expand Up @@ -273,6 +295,8 @@ This is to prevent `FilterCommand` from taking on more responsibilities (Separat
`FilterCommand` having `setPersonPredicate()` method:
This is so that `FilterCommand` has the required argument of type `Predicate<Person>` to be used in the `updateFilteredPersonList()` method. Since the `Predicate<Person>` object is created by chaining the multiple predicates, no parsing is involved to create this `Predicate`.

<div style="page-break-after: always;"></div>

### Sort feature

##### How the feature is implemented
Expand All @@ -292,10 +316,14 @@ Given below is an example usage scenario and how the sort mechanism behaves at e

4. The `SortCommand` is returned to Logic manager which calls on its `execute()` to return a `CommandResult()`. During its execution, `ModelManager.updateSortedPersonList(NameComparator)` is invoked which updates the model to show the list of persons being sorted by name.

<div style="page-break-after: always;"></div>

The sequence diagram for executing a **"sort n/"** is shown below:

<img src="images/SortSequenceDiagram.png" width="740" />

<div style="page-break-after: always;"></div>

The following activity diagram summarizes what happens when a user executes a new sort command:

<img src="images/SortActivityDiagram.png" width="600" />
Expand All @@ -314,7 +342,7 @@ This is to map the 1 or more comparator objects and act as a layer of abstractio
`SortCommmandParser` parsing the `Comparator` objects:
This is to prevent `SortCommand` from taking on more responsibilities (Separation of Concerns).

#### What designs were considered:
#### What designs were considered

**Aspect: Determining order of sorting of attribute(s):**

Expand All @@ -336,8 +364,9 @@ This is to prevent `SortCommand` from taking on more responsibilities (Separatio
* Pros: Easy to implement, controlled and less likely to be used incorrectly. This increase ease of use for users.
* Cons: Limited sorting and lesser functionality.

<div style="page-break-after: always;"></div>

### Meeting Feature
### Meeting feature

Meeting is feature that allows the user to keep track of any events they may have with the particular contact. It contains the description of the meeting event with the date and time it would occur.

Expand All @@ -357,13 +386,16 @@ The operations for adding and deleting meeting are handled by `AddMeetingCommand
4. `AddMeetingCommand` or `DeleteMeetingCommand` is created with the parsed values.
5. `Logic Manager` executes the `AddMeetingCommand` or `DeleteMeetingCommand`, which handles adding/removing meeting from the `Person` respectively and updates the model with the new information.

<div style="page-break-after: always;"></div>

Below is the sequence diagram for parsing inputs with `AddMeetingCommandParser` executing `meeting-add 2 d/Finals s/20/04/2024 15:00`:
<br>![AddMeetingCommandParser Sequence Diagram](images/AddMeetingParserSequenceDiagram.png)
<br>Below in the in-depth reference of how `AddMeetingCommandParser` utilise `ParseUtil` to parse the arguments:
<br>![Add Parser Reference Diagram](images/AddParserRefrenceDiagram.png)
<br> Similarly, the sequence diagram for parsing inputs with `DeleteMeetingCommandParser` executing `meeting-delete 1 i/1`:
<br>![DeleteMeetingCommandParser Sequence Diagram](images/DeleteMeetingParserSequenceDiagram.png)
<br><br>
<div style="page-break-after: always;"></div>
After parsing, the commands are executed by the logic manager as show below. (Execute in the diagrams below comes form the logic manager)
<br> Below is the sequence diagram for adding meeting with `AddMeetingCommand`:
<br>![AddMeetingCommand Sequence Diagram](images/AddMeetingSequenceDiagram.png)
Expand All @@ -372,7 +404,7 @@ After parsing, the commands are executed by the logic manager as show below. (Ex
<br> Below is the sequence diagram of how both `AddMeetingCommand` and `DeleteMeetingCommand` copies the selected person from the model for editing:
<br>![Copy selectedPerson](images/MeetingCopyPerson.png)

#### What are the design considered:
#### What designs were considered

**Aspect: How the meetings are stored :**

Expand All @@ -384,6 +416,8 @@ After parsing, the commands are executed by the logic manager as show below. (Ex
* Pros: Easier implementation.
* Cons: There is an efficiency gap as each element has to be placed into a list before it can be shown to the UI ListView.

<div style="page-break-after: always;"></div>

### Fav/unfav feature

This feature enables us to sets/remove a particular contact using an index as favourite.
Expand All @@ -407,15 +441,15 @@ The following sequence diagrams shows how the `fav 1` command works:
</div>

1. When the user issues the command `fav 1`, `LogicManager` is called upon to execute the command, it is passed to the `StaffCommandParser` object which creates a `FavCommandParser` to parse the arguments for the `fav` command.
2. The parsing of `FavCommandParser` results in a new `FavCommand` initialized by an index `Index`.

![Execute Fav Command Sequence Diagram](images/ExecuteFavCommandSequenceDiagram.png)
2. The parsing of `FavCommandParser` results in a new `FavCommand` initialized by an index `Index`. ![Execute Fav Command Sequence Diagram](images/ExecuteFavCommandSequenceDiagram.png)

3. When the `FavCommand` is executed, it retrieves the last shown list using `getSortedFilteredPersonList()` and creates a favourite person. This portions' details has been separated from the main sequence diagram into the reference sequence diagram below.
4. After creating a new `Person` object, `FavCommand` replaces the old `Person` object with the new one.
5. The command communicates with the `Model` when it is executed. More specifically, it calls `updateFilteredPersonList()` method using `PREDICATE_SHOW_ALL_PERSONS` which resets the view to default.
6. The result of the command execution is encapsulated as a `CommandResult` object which is returned back from `LogicManager`, to show in the `UI` component the success message that the `Person` at the given index is set as favourite.

<div style="page-break-after: always;"></div>

The below sequence diagram goes into more details on how the execution of the command creates a favourite person:

![Fav Ref Sequence Diagram](images/FavRefSequenceDiagram.png)
Expand All @@ -427,6 +461,8 @@ The following activity diagram summarizes what happens when a user executes a ne

![Fav Activity Diagram](images/FavActivityDiagram.png)

<div style="page-break-after: always;"></div>

Similarly, the following diagrams shows how the `unfav 1` command works:

![Unfav Command Sequence Diagram](images/UnfavSequenceDiagram.png)
Expand All @@ -435,9 +471,7 @@ Similarly, the following diagrams shows how the `unfav 1` command works:
</div>

1. When the user issues the command `unfav 1`, `LogicManager` is called upon to execute the command, it is passed to the `StaffCommandParser` object which creates a `UnfavCommandParser` to parse the arguments for the `unfav` command.
2. The parsing of `UnfavCommandParser` results in a new `UnfavCommand` initialized by an index `Index`.

![ExecuteUnfavCommandSequenceDiagram.png](images/ExecuteUnfavCommandSequenceDiagram.png)
2. The parsing of `UnfavCommandParser` results in a new `UnfavCommand` initialized by an index `Index`. ![ExecuteUnfavCommandSequenceDiagram.png](images/ExecuteUnfavCommandSequenceDiagram.png)

3. When the `UnfavCommand` is executed, it retrieves the last shown list using `getSortedFilteredPersonList()` and creates an unfavourite person. This portions' details has been separated from the main sequence diagram into the reference sequence diagram below.
4. After creating a new `Person` object, `UnfavCommand` replaces the old `Person` object with the new one.
Expand All @@ -451,10 +485,14 @@ The below sequence diagram goes into more details on how the execution of the co
7. `UnfavCommand` calls the static `UnfavCommand#createUnfavPerson(personToUnfav)` function which calls for the static `PersonUtil#createPersonWithFavouriteStatus(Person selectedPerson, Favourite favourite)` using the `selectedPerson` and a new `Favourite` with the value `false`.
8. This static `PersonUtil#createPersonWithFavouriteStatus(Person selectedPerson, Favourite favourite)` function creates a new `Person` with the given `Favourite` attribute and returns back to `UnfavCommand`.

<div style="page-break-after: always;"></div>

The following activity diagram summarizes what happens when a user executes a new `unfav` command:

![Unfav Activity Diagram](images/UnfavActivityDiagram.png)

<div style="page-break-after: always;"></div>

### \[Proposed\] Undo/redo feature

#### Proposed Implementation
Expand Down Expand Up @@ -540,6 +578,8 @@ The following activity diagram summarizes what happens when a user executes a ne

--------------------------------------------------------------------------------------------------------------------

<div style="page-break-after: always;"></div>

## **Documentation, logging, testing, configuration, dev-ops**

* [Documentation guide](Documentation.md)
Expand All @@ -550,6 +590,8 @@ The following activity diagram summarizes what happens when a user executes a ne

--------------------------------------------------------------------------------------------------------------------

<div style="page-break-after: always;"></div>

## **Appendix: Requirements**

### Product scope
Expand All @@ -565,6 +607,8 @@ He also sometimes forgets that he has scheduled consultations with a professor o
StaffConnect offers convenience and efficiency for a forgetful tech-savvy student.
StaffConnect allows users to easily identify and connect with educators by providing visual cues alongside their contact details, supported by an easy-to-use filtering system.

<div style="page-break-after: always;"></div>

### User stories

Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unlikely to have) - `*`
Expand Down Expand Up @@ -597,6 +641,8 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
| `* *` | time-conscious user | clear my outdated meetings with professors/tutors | save time by removing outdated meetings with one command |
| `* *` | proficient typer | select a professor/tutor to see their contact details with a command | use the app with my more proficient method of typing instead of using other input devices (i.e. mouse) |

<div style="page-break-after: always;"></div>

### Use cases

(For all use cases below, the **System** is the `StaffConnect` and the **Actor** is the `user`, unless specified otherwise)
Expand Down Expand Up @@ -752,6 +798,7 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
* 2a1. StaffConnect shows an error message.
Use case resumes at step 1.

<div style="page-break-after: always;"></div>

### Non-Functional Requirements

Expand All @@ -766,6 +813,8 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli
9. The app should be up-to-date with the latest NUS faculty names.
10. The data stored in the app should not change unless the user has modified the data through usage of the app with user-issued commands, or the `[JAR file location]/data/staffconnect.json` file has been modified with valid values.

<div style="page-break-after: always;"></div>

### Glossary

* **Mainstream OS**: Windows, Linux, Unix, MacOS, with versions that support Java 11
Expand All @@ -778,6 +827,8 @@ Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unli

--------------------------------------------------------------------------------------------------------------------

<div style="page-break-after: always;"></div>

## **Appendix: Instructions for manual testing**

Given below are instructions to test the app manually.
Expand All @@ -802,6 +853,8 @@ testers are expected to do more *exploratory* testing.
2. Re-launch the app by double-clicking the jar file.<br>
Expected: The most recent window size and location is retained.

<div style="page-break-after: always;"></div>

### Deleting a person

1. Deleting a person while all persons are being shown
Expand All @@ -817,6 +870,8 @@ testers are expected to do more *exploratory* testing.
4. Other incorrect delete commands to try: `delete`, `delete x`, `...` (where x is larger than the list size)<br>
Expected: Similar to previous.

<div style="page-break-after: always;"></div>

### Saving data

1. Dealing with missing/corrupted data files
Expand Down

0 comments on commit 1670564

Please sign in to comment.