Skip to content
This repository has been archived by the owner on Dec 9, 2017. It is now read-only.

Commit

Permalink
Update developer guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@joanneong
joanneong committed Nov 13, 2017
1 parent 73af83c commit d4c19f4
Show file tree
Hide file tree
Showing 3 changed files with 3 additions and 267 deletions.
266 changes: 2 additions & 264 deletions docs/DeveloperGuide.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -852,255 +852,10 @@ Here are the steps to create a new release.

=== Managing Dependencies

A project often depends on third-party libraries. For example, Address Book depends on the http://wiki.fasterxml.com/JacksonHome[Jackson library] for XML parsing. Managing these _dependencies_ can be automated using Gradle. For example, Gradle can download the dependencies automatically, which is better than these alternatives. +
A project often depends on third-party libraries. For example, Intelli depends on the http://graphstream-project.org/[GraphStream] for the graph display. Managing these _dependencies_ can be automated using Gradle. For example, Gradle can download the dependencies automatically, which is better than these alternatives. +
a. Include those libraries in the repo (this bloats the repo size) +
b. Require developers to download those libraries manually (this creates extra work for developers)

[appendix]
== Suggested Programming Tasks to Get Started

Suggested path for new programmers:

1. First, add small local-impact (i.e. the impact of the change does not go beyond the component) enhancements to one component at a time. Some suggestions are given in this section link:#improving-each-component[Improving a Component].

2. Next, add a feature that touches multiple components to learn how to implement an end-to-end feature across all components. The section link:#creating-a-new-command-code-remark-code[Creating a new command: `remark`] explains how to go about adding such a feature.

=== Improving each component

Each individual exercise in this section is component-based (i.e. you would not need to modify the other components to get it to work).

[discrete]
==== `Logic` component

[TIP]
Do take a look at the link:#logic-component[Design: Logic Component] section before attempting to modify the `Logic` component.

. Add a shorthand equivalent alias for each of the individual commands. For example, besides typing `clear`, the user can also type `c` to remove all persons in the list.
+
****
* Hints
** Just like we store each individual command word constant `COMMAND_WORD` inside `*Command.java` (e.g. link:{repoURL}/src/main/java/seedu/address/logic/commands/FindCommand.java[`FindCommand#COMMAND_WORD`], link:{repoURL}/src/main/java/seedu/address/logic/commands/DeleteCommand.java[`DeleteCommand#COMMAND_WORD`]), you need a new constant for aliases as well (e.g. `FindCommand#COMMAND_ALIAS`).
** link:{repoURL}/src/main/java/seedu/address/logic/parser/AddressBookParser.java[`AddressBookParser`] is responsible for analyzing command words.
* Solution
** Modify the switch statement in link:{repoURL}/src/main/java/seedu/address/logic/parser/AddressBookParser.java[`AddressBookParser#parseCommand(String)`] such that both the proper command word and alias can be used to execute the same intended command.
** See this https://github.com/se-edu/addressbook-level4/pull/590/files[PR] for the full solution.
****

[discrete]
==== `Model` component

[TIP]
Do take a look at the link:#model-component[Design: Model Component] section before attempting to modify the `Model` component.

. Add a `removeTag(Tag)` method. The specified tag will be removed from everyone in the address book.
+
****
* Hints
** The link:{repoURL}/src/main/java/seedu/address/model/Model.java[`Model`] API needs to be updated.
** Find out which of the existing API methods in link:{repoURL}/src/main/java/seedu/address/model/AddressBook.java[`AddressBook`] and link:{repoURL}/src/main/java/seedu/address/model/person/Person.java[`Person`] classes can be used to implement the tag removal logic. link:{repoURL}/src/main/java/seedu/address/model/AddressBook.java[`AddressBook`] allows you to update a person, and link:{repoURL}/src/main/java/seedu/address/model/person/Person.java[`Person`] allows you to update the tags.
* Solution
** Add the implementation of `deleteTag(Tag)` method in link:{repoURL}/src/main/java/seedu/address/model/ModelManager.java[`ModelManager`]. Loop through each person, and remove the `tag` from each person.
** See this https://github.com/se-edu/addressbook-level4/pull/591/files[PR] for the full solution.
****

[discrete]
==== `Ui` component

[TIP]
Do take a look at the link:#ui-component[Design: UI Component] section before attempting to modify the `UI` component.

. Use different colors for different tags inside person cards. For example, `friends` tags can be all in grey, and `colleagues` tags can be all in red.
+
**Before**
+
image::getting-started-ui-tag-before.png[width="300"]
+
**After**
+
image::getting-started-ui-tag-after.png[width="300"]
+
****
* Hints
** The tag labels are created inside link:{repoURL}/src/main/java/seedu/address/ui/PersonCard.java[`PersonCard#initTags(ReadOnlyPerson)`] (`new Label(tag.tagName)`). https://docs.oracle.com/javase/8/javafx/api/javafx/scene/control/Label.html[JavaFX's `Label` class] allows you to modify the style of each Label, such as changing its color.
** Use the .css attribute `-fx-background-color` to add a color.
* Solution
** See this https://github.com/se-edu/addressbook-level4/pull/592/files[PR] for the full solution.
****

. Modify link:{repoURL}/src/main/java/seedu/address/commons/events/ui/NewResultAvailableEvent.java[`NewResultAvailableEvent`] such that link:{repoURL}/src/main/java/seedu/address/ui/ResultDisplay.java[`ResultDisplay`] can show a different style on error (currently it shows the same regardless of errors).
+
**Before**
+
image::getting-started-ui-result-before.png[width="200"]
+
**After**
+
image::getting-started-ui-result-after.png[width="200"]
+
****
* Hints
** link:{repoURL}/src/main/java/seedu/address/commons/events/ui/NewResultAvailableEvent.java[`NewResultAvailableEvent`] is raised by link:{repoURL}/src/main/java/seedu/address/ui/CommandBox.java[`CommandBox`] which also knows whether the result is a success or failure, and is caught by link:{repoURL}/src/main/java/seedu/address/ui/ResultDisplay.java[`ResultDisplay`] which is where we want to change the style to.
** Refer to link:{repoURL}/src/main/java/seedu/address/ui/CommandBox.java[`CommandBox`] for an example on how to display an error.
* Solution
** Modify link:{repoURL}/src/main/java/seedu/address/commons/events/ui/NewResultAvailableEvent.java[`NewResultAvailableEvent`] 's constructor so that users of the event can indicate whether an error has occurred.
** Modify link:{repoURL}/src/main/java/seedu/address/ui/ResultDisplay.java[`ResultDisplay#handleNewResultAvailableEvent(event)`] to react to this event appropriately.
** See this https://github.com/se-edu/addressbook-level4/pull/593/files[PR] for the full solution.
****

. Modify the link:{repoURL}/src/main/java/seedu/address/ui/StatusBarFooter.java[`StatusBarFooter`] to show the total number of people in the address book.
+
**Before**
+
image::getting-started-ui-status-before.png[width="500"]
+
**After**
+
image::getting-started-ui-status-after.png[width="500"]
+
****
* Hints
** link:{repoURL}/src/main/resources/view/StatusBarFooter.fxml[`StatusBarFooter.fxml`] will need a new `StatusBar`. Be sure to set the `GridPane.columnIndex` properly for each `StatusBar` to avoid misalignment!
** link:{repoURL}/src/main/java/seedu/address/ui/StatusBarFooter.java[`StatusBarFooter`] needs to initialize the status bar on application start, and to update it accordingly whenever the address book is updated.
* Solution
** Modify the constructor of link:{repoURL}/src/main/java/seedu/address/ui/StatusBarFooter.java[`StatusBarFooter`] to take in the number of persons when the application just started.
** Use link:{repoURL}/src/main/java/seedu/address/ui/StatusBarFooter.java[`StatusBarFooter#handleAddressBookChangedEvent(AddressBookChangedEvent)`] to update the number of persons whenever there are new changes to the addressbook.
** See this https://github.com/se-edu/addressbook-level4/pull/596/files[PR] for the full solution.
****

[discrete]
==== `Storage` component

[TIP]
Do take a look at the link:#storage-component[Design: Storage Component] section before attempting to modify the `Storage` component.

. Add a new method `backupAddressBook(ReadOnlyAddressBook)`, so that the address book can be saved in a fixed temporary location.
+
****
* Hint
** Add the API method in link:{repoURL}/src/main/java/seedu/address/storage/AddressBookStorage.java[`AddressBookStorage`] interface.
** Implement the logic in link:{repoURL}/src/main/java/seedu/address/storage/StorageManager.java[`StorageManager`] class.
* Solution
** See this https://github.com/se-edu/addressbook-level4/pull/594/files[PR] for the full solution.
****

=== Creating a new command: `remark`

By creating this command, you will get a chance to learn how to implement a feature end-to-end, touching all major components of the app.

==== Description
Edits the remark for a person specified in the `INDEX`. +
Format: `remark INDEX r/[REMARK]`

Examples:

* `remark 1 r/Likes to drink coffee.` +
Edits the remark for the first person to `Likes to drink coffee.`
* `remark 1 r/` +
Removes the remark for the first person.

==== Step-by-step Instructions

===== [Step 1] Logic: Teach the app to accept 'remark' which does nothing
Let's start by teaching the application how to parse a `remark` command. We will add the logic of `remark` later.

**Main:**

. Add a `RemarkCommand` that extends link:{repoURL}/src/main/java/seedu/address/logic/commands/UndoableCommand.java[`UndoableCommand`]. Upon execution, it should just throw an `Exception`.
. Modify link:{repoURL}/src/main/java/seedu/address/logic/parser/AddressBookParser.java[`AddressBookParser`] to accept a `RemarkCommand`.

**Tests:**

. Add `RemarkCommandTest` that tests that `executeUndoableCommand()` throws an Exception.
. Add new test method to link:{repoURL}/src/test/java/seedu/address/logic/parser/AddressBookParserTest.java[`AddressBookParserTest`], which tests that typing "remark" returns an instance of `RemarkCommand`.

===== [Step 2] Logic: Teach the app to accept 'remark' arguments
Let's teach the application to parse arguments that our `remark` command will accept. E.g. `1 r/Likes to drink coffee.`

**Main:**

. Modify `RemarkCommand` to take in an `Index` and `String` and print those two parameters as the error message.
. Add `RemarkCommandParser` that knows how to parse two arguments, one index and one with prefix 'r/'.
. Modify link:{repoURL}/src/main/java/seedu/address/logic/parser/AddressBookParser.java[`AddressBookParser`] to use the newly implemented `RemarkCommandParser`.

**Tests:**

. Modify `RemarkCommandTest` to test the `RemarkCommand#equals()` method.
. Add `RemarkCommandParserTest` that tests different boundary values
for `RemarkCommandParser`.
. Modify link:{repoURL}/src/test/java/seedu/address/logic/parser/AddressBookParserTest.java[`AddressBookParserTest`] to test that the correct command is generated according to the user input.

===== [Step 3] Ui: Add a placeholder for remark in `PersonCard`
Let's add a placeholder on all our link:{repoURL}/src/main/java/seedu/address/ui/PersonCard.java[`PersonCard`] s to display a remark for each person later.

**Main:**

. Add a `Label` with any random text inside link:{repoURL}/src/main/resources/view/PersonListCard.fxml[`PersonListCard.fxml`].
. Add FXML annotation in link:{repoURL}/src/main/java/seedu/address/ui/PersonCard.java[`PersonCard`] to tie the variable to the actual label.

**Tests:**

. Modify link:{repoURL}/src/test/java/guitests/guihandles/PersonCardHandle.java[`PersonCardHandle`] so that future tests can read the contents of the remark label.

===== [Step 4] Model: Add `Remark` class
We have to properly encapsulate the remark in our link:{repoURL}/src/main/java/seedu/address/model/person/ReadOnlyPerson.java[`ReadOnlyPerson`] class. Instead of just using a `String`, let's follow the conventional class structure that the codebase already uses by adding a `Remark` class.

**Main:**

. Add `Remark` to model component (you can copy from link:{repoURL}/src/main/java/seedu/address/model/person/Address.java[`Address`], remove the regex and change the names accordingly).
. Modify `RemarkCommand` to now take in a `Remark` instead of a `String`.

**Tests:**

. Add test for `Remark`, to test the `Remark#equals()` method.

===== [Step 5] Model: Modify `ReadOnlyPerson` to support a `Remark` field
Now we have the `Remark` class, we need to actually use it inside link:{repoURL}/src/main/java/seedu/address/model/person/ReadOnlyPerson.java[`ReadOnlyPerson`].

**Main:**

. Add three methods `setRemark(Remark)`, `getRemark()` and `remarkProperty()`. Be sure to implement these newly created methods in link:{repoURL}/src/main/java/seedu/address/model/person/ReadOnlyPerson.java[`Person`], which implements the link:{repoURL}/src/main/java/seedu/address/model/person/ReadOnlyPerson.java[`ReadOnlyPerson`] interface.
. You may assume that the user will not be able to use the `add` and `edit` commands to modify the remarks field (i.e. the person will be created without a remark).
. Modify link:{repoURL}/src/main/java/seedu/address/model/util/SampleDataUtil.java/[`SampleDataUtil`] to add remarks for the sample data (delete your `addressBook.xml` so that the application will load the sample data when you launch it.)

===== [Step 6] Storage: Add `Remark` field to `XmlAdaptedPerson` class
We now have `Remark` s for `Person` s, but they will be gone when we exit the application. Let's modify link:{repoURL}/src/main/java/seedu/address/storage/XmlAdaptedPerson.java[`XmlAdaptedPerson`] to include a `Remark` field so that it will be saved.

**Main:**

. Add a new Xml field for `Remark`.
. Be sure to modify the logic of the constructor and `toModelType()`, which handles the conversion to/from link:{repoURL}/src/main/java/seedu/address/model/person/ReadOnlyPerson.java[`ReadOnlyPerson`].

**Tests:**

. Fix `validAddressBook.xml` such that the XML tests will not fail due to a missing `<remark>` element.

===== [Step 7] Ui: Connect `Remark` field to `PersonCard`
Our remark label in link:{repoURL}/src/main/java/seedu/address/ui/PersonCard.java[`PersonCard`] is still a placeholder. Let's bring it to life by binding it with the actual `remark` field.

**Main:**

. Modify link:{repoURL}/src/main/java/seedu/address/ui/PersonCard.java[`PersonCard#bindListeners()`] to add the binding for `remark`.

**Tests:**

. Modify link:{repoURL}/src/test/java/seedu/address/ui/testutil/GuiTestAssert.java[`GuiTestAssert#assertCardDisplaysPerson(...)`] so that it will compare the remark label.
. In link:{repoURL}/src/test/java/seedu/address/ui/PersonCardTest.java[`PersonCardTest`], call `personWithTags.setRemark(ALICE.getRemark())` to test that changes in the link:{repoURL}/src/main/java/seedu/address/model/person/ReadOnlyPerson.java[`Person`] 's remark correctly updates the corresponding link:{repoURL}/src/main/java/seedu/address/ui/PersonCard.java[`PersonCard`].

===== [Step 8] Logic: Implement `RemarkCommand#execute()` logic
We now have everything set up... but we still can't modify the remarks. Let's finish it up by adding in actual logic for our `remark` command.

**Main:**

. Replace the logic in `RemarkCommand#execute()` (that currently just throws an `Exception`), with the actual logic to modify the remarks of a person.

**Tests:**

. Update `RemarkCommandTest` to test that the `execute()` logic works.

==== Full Solution

See this https://github.com/se-edu/addressbook-level4/pull/599[PR] for the step-by-step solution.

[appendix]
== User Stories

Expand Down Expand Up @@ -1191,7 +946,7 @@ Priorities: High (must have) - `* * \*`, Medium (nice to have) - `* \*`, Low (un
[appendix]
== 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 `Intelli` and the *Actor* is the `user`, unless specified otherwise)

[discrete]
=== Use case: Delete person
Expand Down Expand Up @@ -1460,20 +1215,3 @@ Relationship name
....
A specific status for the relationship(eg. lecturer-student)
....

[appendix]
== Product Survey

*Product Name*

Author: ...

Pros:

* ...
* ...

Cons:

* ...
* ...
Binary file modified docs/images/Ui.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 1 addition & 3 deletions docs/team/TanYikai.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
== Project: Intelli
Intelli is a desktop relationship tracker used by private investigators (PI) to manage their information and leads. The PI interacts with it using a CLI, and it has a GUI created with JavaFX and GraphStream. It is written in Java, and has about 6 kLoC.

*Code contributed*: [https://github.com/CS2103AUG2017-F10-B1/main/tree/master/collated/main/TanYikai.md[Functional code]] [https://github.com/CS2103AUG2017-F10-B1/main/tree/master/collated/test/TanYikai.md[Test code]] {give links to collated code files}
*Code contributed*: [https://github.com/CS2103AUG2017-F10-B1/main/tree/master/collated/main/TanYikai.md[Functional code]] [https://github.com/CS2103AUG2017-F10-B1/main/tree/master/collated/test/TanYikai.md[Test code]] [https://github.com/CS2103AUG2017-F10-B1/main/tree/master/collated/unused/TanYikai.md[Unused code]]

=== Enhancement Added: Alias

Expand Down Expand Up @@ -111,5 +111,3 @@ include::../DeveloperGuide.adoc[tag=EnhancedAddCommand]
=== Other contributions

* Enhanced Remark Command which was left out of the final product due to the more fitting relationship graph


0 comments on commit d4c19f4

Please sign in to comment.