Merge AB-4 "Migrate to PlantUML from PowerPoint"

* commit '5272d589ab491ea68fdf98d341c8ec6570663320':
  Migrate to PlantUML from PowerPoint

docs/DeveloperGuide.adoc

@@ -26,12 +26,13 @@ Refer to the guide <<SettingUp#, here>>.
 === Architecture
 
 .Architecture Diagram
-image::Architecture.png[width="600"]
+image::ArchitectureDiagram.png[]
 
 The *_Architecture Diagram_* given above explains the high-level design of the App. Given below is a quick overview of each component.
 
 [TIP]
-The `.pptx` files used to create diagrams in this document can be found in the link:{repoURL}/docs/diagrams/[diagrams] folder. To update a diagram, modify the diagram in the pptx file, select the objects of the diagram, and choose `Save as picture`.
+The `.puml` files used to create diagrams in this document can be found in the link:{repoURL}/docs/diagrams/[diagrams] folder.
+Refer to the <<UsingPlantUml#, Using PlantUML guide>> to learn how to create and edit diagrams.
 
 `Main` has two classes called link:{repoURL}/src/main/java/seedu/address/Main.java[`Main`] and link:{repoURL}/src/main/java/seedu/address/MainApp.java[`MainApp`]. It is responsible for,
 
@@ -58,23 +59,23 @@ Each of the four components
 For example, the `Logic` component (see the class diagram given below) defines it's API in the `Logic.java` interface and exposes its functionality using the `LogicManager.java` class.
 
 .Class Diagram of the Logic Component
-image::LogicClassDiagram.png[width="800"]
+image::LogicClassDiagram.png[]
 
 [discrete]
 ==== How the architecture components interact with each other
 
 The _Sequence Diagram_ below shows how the components interact with each other for the scenario where the user issues the command `delete 1`.
 
 .Component interactions for `delete 1` command
-image::SDforDeletePerson.png[width="800"]
+image::ArchitectureSequenceDiagram.png[]
 
 The sections below give more details of each component.
 
 [[Design-Ui]]
 === UI component
 
 .Structure of the UI Component
-image::UiClassDiagram.png[width="800"]
+image::UiClassDiagram.png[]
 
 *API* : link:{repoURL}/src/main/java/seedu/address/ui/Ui.java[`Ui.java`]
 
@@ -92,7 +93,7 @@ The `UI` component,
 
 [[fig-LogicClassDiagram]]
 .Structure of the Logic Component
-image::LogicClassDiagram.png[width="800"]
+image::LogicClassDiagram.png[]
 
 *API* :
 link:{repoURL}/src/main/java/seedu/address/logic/Logic.java[`Logic.java`]
@@ -106,13 +107,15 @@ link:{repoURL}/src/main/java/seedu/address/logic/Logic.java[`Logic.java`]
 Given below is the Sequence Diagram for interactions within the `Logic` component for the `execute("delete 1")` API call.
 
 .Interactions Inside the Logic Component for the `delete 1` Command
-image::DeletePersonSdForLogic.png[width="800"]
+image::DeleteSequenceDiagram.png[]
+
+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-Model]]
 === Model component
 
 .Structure of the Model Component
-image::ModelClassDiagram.png[width="800"]
+image::ModelClassDiagram.png[]
 
 *API* : link:{repoURL}/src/main/java/seedu/address/model/Model.java[`Model.java`]
 
@@ -126,13 +129,13 @@ The `Model`,
 [NOTE]
 As a more OOP model, we can store a `Tag` list in `Address Book`, which `Person` can reference. This would allow `Address Book` to only require one `Tag` object per unique `Tag`, instead of each `Person` needing their own `Tag` object. An example of how such a model may look like is given below. +
  +
-image:ModelClassBetterOopDiagram.png[width="800"]
+image:BetterModelClassDiagram.png[]
 
 [[Design-Storage]]
 === Storage component
 
 .Structure of the Storage Component
-image::StorageClassDiagram.png[width="800"]
+image::StorageClassDiagram.png[]
 
 *API* : link:{repoURL}/src/main/java/seedu/address/storage/Storage.java[`Storage.java`]
 
@@ -168,29 +171,31 @@ Given below is an example usage scenario and how the undo/redo mechanism behaves
 
 Step 1. The user launches the application for the first time. The `VersionedAddressBook` will be initialized with the initial address book state, and the `currentStatePointer` pointing to that single address book state.
 
-image::UndoRedoStartingStateListDiagram.png[width="800"]
+image::UndoRedoState0.png[]
 
 Step 2. The user executes `delete 5` command to delete the 5th person in the address book. The `delete` command calls `Model#commitAddressBook()`, causing the modified state of the address book after the `delete 5` command executes to be saved in the `addressBookStateList`, and the `currentStatePointer` is shifted to the newly inserted address book state.
 
-image::UndoRedoNewCommand1StateListDiagram.png[width="800"]
+image::UndoRedoState1.png[]
 
 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`.
 
-image::UndoRedoNewCommand2StateListDiagram.png[width="800"]
+image::UndoRedoState2.png[]
 
 [NOTE]
 If a command fails its execution, it will not call `Model#commitAddressBook()`, so the address book state will not be saved into the `addressBookStateList`.
 
 Step 4. The user now decides that adding the person was a mistake, and decides to undo that action by executing the `undo` command. The `undo` command will call `Model#undoAddressBook()`, which will shift the `currentStatePointer` once to the left, pointing it to the previous address book state, and restores the address book to that state.
 
-image::UndoRedoExecuteUndoStateListDiagram.png[width="800"]
+image::UndoRedoState3.png[]
 
 [NOTE]
 If the `currentStatePointer` is at index 0, pointing to the initial address book state, then there are no previous address book states to restore. The `undo` command uses `Model#canUndoAddressBook()` to check if this is the case. If so, it will return an error to the user rather than attempting to perform the undo.
 
 The following sequence diagram shows how the undo operation works:
 
-image::UndoRedoSequenceDiagram.png[width="800"]
+image::UndoSequenceDiagram.png[]
+
+NOTE: The lifeline for `UndoCommand` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.
 
 The `redo` command does the opposite -- it calls `Model#redoAddressBook()`, which shifts the `currentStatePointer` once to the right, pointing to the previously undone state, and restores the address book to that state.
 
@@ -199,15 +204,15 @@ If the `currentStatePointer` is at index `addressBookStateList.size() - 1`, poin
 
 Step 5. The user then decides to execute the command `list`. Commands that do not modify the address book, such as `list`, will usually not call `Model#commitAddressBook()`, `Model#undoAddressBook()` or `Model#redoAddressBook()`. Thus, the `addressBookStateList` remains unchanged.
 
-image::UndoRedoNewCommand3StateListDiagram.png[width="800"]
+image::UndoRedoState4.png[]
 
 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. We designed it this way because it no longer makes sense to redo the `add n/David ...` command. This is the behavior that most modern desktop applications follow.
 
-image::UndoRedoNewCommand4StateListDiagram.png[width="800"]
+image::UndoRedoState5.png[]
 
 The following activity diagram summarizes what happens when a user executes a new command:
 
-image::UndoRedoActivityDiagram.png[width="650"]
+image::CommitActivityDiagram.png[]
 
 ==== Design Considerations
 

docs/Documentation.adoc

@@ -26,6 +26,10 @@ We chose asciidoc over Markdown because asciidoc, although a bit more complex th
 See <<UsingGradle#rendering-asciidoc-files, UsingGradle.adoc>> to learn how to render `.adoc` files locally to preview the end result of your edits.
 Alternatively, you can download the AsciiDoc plugin for IntelliJ, which allows you to preview the changes you have made to your `.adoc` files in real-time.
 
+== Editing Diagrams
+
+See <<UsingPlantUml#, UsingPlantUml.adoc>> to find out how to create and update the UML diagrams in the developer guide.
+
 == Publishing Documentation
 
 See <<UsingTravis#deploying-github-pages, UsingTravis.adoc>> to learn how to deploy GitHub Pages using Travis.

docs/UsingPlantUml.adoc

@@ -0,0 +1,211 @@
+= Using PlantUML
+:site-section: DeveloperGuide
+:imagesDir: images/plantuml
+:stylesDir: stylesheets
+:experimental:
+ifdef::env-github[]
+:tip-caption: :bulb:
+:note-caption: :information_source:
+endif::[]
+
+== Introduction to PlantUML
+
+PlantUML is a tool used in this project to create UML diagrams.
+For more information about the basics of PlantUML, head over to http://plantuml.com/[its official website].
+
+== Set up PlantUML
+
+=== Installing Graphviz
+
+Graphviz is a dependency that PlantUML requires to generate more advanced diagrams.
+Head over to the https://www.graphviz.org/download/[downloads page] on the official Graphviz website and follow instructions to install Graphviz.
+
+=== Installing the `PlantUML integration` plugin for IntelliJ IDEA
+
+Go to `Settings` > `Plugins` > `Marketplace` and install the plugin `PlantUML integration`.
+
+Then go to `Settings` > `Other Settings` > `PlantUML` or search for PlantUML.
+Configure the path to the `dot` executable.
+This executable can be found in the `/bin` directory where you installed GraphViz.
+
+.Settings - Other Settings - PlantUML: input the path to your dot executable
+image::ConfiguringGraphviz.png[]
+
+== Create/Edit PlantUML diagrams
+
+After installing the `PlantUML integration` plugin, simply create or open any `.puml` file to start editing it.
+
+.Editing `DeleteSequenceDiagram.puml`
+image::EditingDeleteSequenceDiagram.png[]
+Any changes you make in editor pane on the left will be reflected in the preview pane on the right.
+However, do take note that these changes _will not_ be reflected in the developers guide until you export the diagram.
+//TODO: Discussion about why we're not using asciidoctor-diagram
+
+== Export PlantUML diagrams
+
+The `PlantUML integration` plugin allows you to export individual diagrams to a location of your choosing.
+Click the `Save Current Diagram Only` button and choose the location to export the image file.
+
+NOTE: You will have to `git add` any new diagrams generated!
+
+== Common tasks
+
+=== Applying consistent formatting to PlantUML diagrams
+
+It is highly recommended to consistently color your UML diagrams as an visual aid.
+You can achieve this by creating a dictionary of colors and import it like CSS.
+
+For example, you can create a `Style.puml` with the contents:
+
+.Style.puml
+[source]
+----
+...
+!define LOGIC_COLOR #3333C4
+!define LOGIC_COLOR_T1 #7777DB
+!define LOGIC_COLOR_T2 #5252CE
+!define LOGIC_COLOR_T3 #1616B0
+!define LOGIC_COLOR_T4 #101086
+...
+----
+
+Then you can use it in another PlantUML file like this:
+
+.UndoSequenceDiagram.puml
+[source]
+----
+!include Style.puml
+
+box Logic LOGIC_COLOR_T2
+participant ":LogicManager" as LogicManager LOGIC_COLOR
+participant ":AddressBookParser" as AddressBookParser LOGIC_COLOR
+participant ":UndoCommand" as UndoCommand LOGIC_COLOR
+end box
+----
+
+You can fine-tune the formatting of PlantUML diagrams with the `skinparam` command.
+For example, `skinparam backgroundColor transparent` turns the background of the diagram transparent.
+
+For a comprehensive list of ``skinparam``s head over to the https://plantuml-documentation.readthedocs.io/en/latest/[unofficial PlantUML skinparam documentation].
+
+***
+
+=== Repositioning elements in PlantUML diagrams
+
+While PlantUML's automatic layout engine usually produces satisfactory results, at times the result can be less than ideal, especially on larger diagrams.
+Here is an example where the default layout generated by PlantUML has a lot of overlapping lines that are hard to decipher:
+
+.The UI class diagram without additional formatting
+image::RawUiDiagram.png[]
+
+NOTE: In most cases, you should consider decomposing the diagram into smaller ones or focusing on a more specific portion of the diagram.
+
+Here are some of the techniques we used in this project to obtain a more palatable diagram.
+
+==== Link lengths
+By default, a short link (`\->`) points to right and a long link (`-\->`)
+points downwards. you can extend any link to make it longer (```--\->```).
+
+.Length of arrows and its effects
+image::ArrowLength.png[]
+
+==== Link directions
+Clever usage of arrow directions will resolve most layout issues.
+For example, the table below shows how the way in which you specify arrows can results in drastically different layouts for the same diagram.
+
+.Link directions
+[cols="40a,60a"]
+|===
+|Source |Result
+
+|[source, puml]
+----
+A --> Z
+B --> Z
+C --> Z
+D --> Z
+
+A --> 1
+B --> 2
+C --> 3
+D --> 4
+----
+|image::AllDown.png[]
+
+|[source, puml]
+----
+'default is down
+A --> Z
+'specify down
+B -down-> Z
+'shorthand for down
+C -d-> Z
+'arrow lengths take priority
+D -down> Z
+
+A -up-> 1
+B -up-> 2
+C -up-> 3
+D -up-> 4
+
+----
+|image::UpAndDown.png[]
+
+|[source, puml]
+----
+A -up-> Z
+B -up-> Z
+C -up-> Z
+D -up-> Z
+
+A --> 1
+B --> 2
+C --> 3
+D --> 4
+
+'Force A B C D
+A -right[hidden]- B
+B -right[hidden]- C
+C -right[hidden]- D
+----
+|image::HiddenArrows.png[]
+|===
+
+==== Reordering definitions
+As a general rule of thumb, the layout engine will attempt to order objects in the order in which they are defined.
+If there is no formal definition, the objects is taken to be declared upon its first usage.
+
+.Definition ordering and outcomes
+[cols="70a,30a"]
+|===
+|Source |Result
+
+|[source, puml]
+----
+A --> B
+C --> D
+----
+|image::ABeforeC.png[]
+
+|[source, puml]
+----
+'Class C is defined before A
+Class C
+
+A --> B
+C --> D
+----
+|image::CBeforeA.png[]
+
+|[source, puml]
+----
+package "Rule Of Thumb"{
+    Class C
+    A --> B
+    C --> D
+}
+----
+|image::PackagesAndConsistency.png[]
+|===
+
+TIP: Explicitly define all symbols to avoid any potential layout mishaps.