Skip to content

Commit 5272d58

Browse files
j-lumpyokagan
j-lum
authored and
pyokagan
committed
Migrate to PlantUML from PowerPoint
PlantUML is a mature, specialized tool to generate UML diagrams. As it is avtext-based markup language, it works very well with git (e.g. produces easy to grok diffs).Moreover, it is an open-source tool which does not require students to obtain proprietary, paid software to use. Based on these advantages that PlantUML offer over PowerPoint, let's adopt PlantUML as the tool of choice to generate UML diagrams. Introduce a tutorial to help students understand the basics of PlantUML and how its used in AddressBook to generate diagrams. Replace .pptx diagram templates with .puml files. Replace instances of pptx generated diagrams with puml diagrams.
1 parent 4a8e46c commit 5272d58

81 files changed

Lines changed: 1033 additions & 18 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/DeveloperGuide.adoc‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,13 @@ Refer to the guide <<SettingUp#, here>>.
2626
=== Architecture
2727

2828
.Architecture Diagram
29-
image::Architecture.png[width="600"]
29+
image::ArchitectureDiagram.png[]
3030

3131
The *_Architecture Diagram_* given above explains the high-level design of the App. Given below is a quick overview of each component.
3232

3333
[TIP]
34-
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`.
34+
The `.puml` files used to create diagrams in this document can be found in the link:{repoURL}/docs/diagrams/[diagrams] folder.
35+
Refer to the <<UsingPlantUml#, Using PlantUML guide>> to learn how to create and edit diagrams.
3536

3637
`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,
3738

@@ -58,23 +59,23 @@ Each of the four components
5859
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.
5960

6061
.Class Diagram of the Logic Component
61-
image::LogicClassDiagram.png[width="800"]
62+
image::LogicClassDiagram.png[]
6263

6364
[discrete]
6465
==== How the architecture components interact with each other
6566

6667
The _Sequence Diagram_ below shows how the components interact with each other for the scenario where the user issues the command `delete 1`.
6768

6869
.Component interactions for `delete 1` command
69-
image::SDforDeletePerson.png[width="800"]
70+
image::ArchitectureSequenceDiagram.png[]
7071

7172
The sections below give more details of each component.
7273

7374
[[Design-Ui]]
7475
=== UI component
7576

7677
.Structure of the UI Component
77-
image::UiClassDiagram.png[width="800"]
78+
image::UiClassDiagram.png[]
7879

7980
*API* : link:{repoURL}/src/main/java/seedu/address/ui/Ui.java[`Ui.java`]
8081

@@ -92,7 +93,7 @@ The `UI` component,
9293

9394
[[fig-LogicClassDiagram]]
9495
.Structure of the Logic Component
95-
image::LogicClassDiagram.png[width="800"]
96+
image::LogicClassDiagram.png[]
9697

9798
*API* :
9899
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`]
106107
Given below is the Sequence Diagram for interactions within the `Logic` component for the `execute("delete 1")` API call.
107108

108109
.Interactions Inside the Logic Component for the `delete 1` Command
109-
image::DeletePersonSdForLogic.png[width="800"]
110+
image::DeleteSequenceDiagram.png[]
111+
112+
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.
110113

111114
[[Design-Model]]
112115
=== Model component
113116

114117
.Structure of the Model Component
115-
image::ModelClassDiagram.png[width="800"]
118+
image::ModelClassDiagram.png[]
116119

117120
*API* : link:{repoURL}/src/main/java/seedu/address/model/Model.java[`Model.java`]
118121

@@ -126,13 +129,13 @@ The `Model`,
126129
[NOTE]
127130
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. +
128131
+
129-
image:ModelClassBetterOopDiagram.png[width="800"]
132+
image:BetterModelClassDiagram.png[]
130133

131134
[[Design-Storage]]
132135
=== Storage component
133136

134137
.Structure of the Storage Component
135-
image::StorageClassDiagram.png[width="800"]
138+
image::StorageClassDiagram.png[]
136139

137140
*API* : link:{repoURL}/src/main/java/seedu/address/storage/Storage.java[`Storage.java`]
138141

@@ -168,29 +171,31 @@ Given below is an example usage scenario and how the undo/redo mechanism behaves
168171

169172
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.
170173

171-
image::UndoRedoStartingStateListDiagram.png[width="800"]
174+
image::UndoRedoState0.png[]
172175

173176
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.
174177

175-
image::UndoRedoNewCommand1StateListDiagram.png[width="800"]
178+
image::UndoRedoState1.png[]
176179

177180
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`.
178181

179-
image::UndoRedoNewCommand2StateListDiagram.png[width="800"]
182+
image::UndoRedoState2.png[]
180183

181184
[NOTE]
182185
If a command fails its execution, it will not call `Model#commitAddressBook()`, so the address book state will not be saved into the `addressBookStateList`.
183186

184187
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.
185188

186-
image::UndoRedoExecuteUndoStateListDiagram.png[width="800"]
189+
image::UndoRedoState3.png[]
187190

188191
[NOTE]
189192
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.
190193

191194
The following sequence diagram shows how the undo operation works:
192195

193-
image::UndoRedoSequenceDiagram.png[width="800"]
196+
image::UndoSequenceDiagram.png[]
197+
198+
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.
194199

195200
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.
196201

@@ -199,15 +204,15 @@ If the `currentStatePointer` is at index `addressBookStateList.size() - 1`, poin
199204

200205
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.
201206

202-
image::UndoRedoNewCommand3StateListDiagram.png[width="800"]
207+
image::UndoRedoState4.png[]
203208

204209
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.
205210

206-
image::UndoRedoNewCommand4StateListDiagram.png[width="800"]
211+
image::UndoRedoState5.png[]
207212

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

210-
image::UndoRedoActivityDiagram.png[width="650"]
215+
image::CommitActivityDiagram.png[]
211216

212217
==== Design Considerations
213218

‎docs/Documentation.adoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,10 @@ We chose asciidoc over Markdown because asciidoc, although a bit more complex th
2626
See <<UsingGradle#rendering-asciidoc-files, UsingGradle.adoc>> to learn how to render `.adoc` files locally to preview the end result of your edits.
2727
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.
2828

29+
== Editing Diagrams
30+
31+
See <<UsingPlantUml#, UsingPlantUml.adoc>> to find out how to create and update the UML diagrams in the developer guide.
32+
2933
== Publishing Documentation
3034

3135
See <<UsingTravis#deploying-github-pages, UsingTravis.adoc>> to learn how to deploy GitHub Pages using Travis.

‎docs/UsingPlantUml.adoc‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
= Using PlantUML
2+
:site-section: DeveloperGuide
3+
:imagesDir: images/plantuml
4+
:stylesDir: stylesheets
5+
:experimental:
6+
ifdef::env-github[]
7+
:tip-caption: :bulb:
8+
:note-caption: :information_source:
9+
endif::[]
10+
11+
== Introduction to PlantUML
12+
13+
PlantUML is a tool used in this project to create UML diagrams.
14+
For more information about the basics of PlantUML, head over to http://plantuml.com/[its official website].
15+
16+
== Set up PlantUML
17+
18+
=== Installing Graphviz
19+
20+
Graphviz is a dependency that PlantUML requires to generate more advanced diagrams.
21+
Head over to the https://www.graphviz.org/download/[downloads page] on the official Graphviz website and follow instructions to install Graphviz.
22+
23+
=== Installing the `PlantUML integration` plugin for IntelliJ IDEA
24+
25+
Go to `Settings` > `Plugins` > `Marketplace` and install the plugin `PlantUML integration`.
26+
27+
Then go to `Settings` > `Other Settings` > `PlantUML` or search for PlantUML.
28+
Configure the path to the `dot` executable.
29+
This executable can be found in the `/bin` directory where you installed GraphViz.
30+
31+
.Settings - Other Settings - PlantUML: input the path to your dot executable
32+
image::ConfiguringGraphviz.png[]
33+
34+
== Create/Edit PlantUML diagrams
35+
36+
After installing the `PlantUML integration` plugin, simply create or open any `.puml` file to start editing it.
37+
38+
.Editing `DeleteSequenceDiagram.puml`
39+
image::EditingDeleteSequenceDiagram.png[]
40+
Any changes you make in editor pane on the left will be reflected in the preview pane on the right.
41+
However, do take note that these changes _will not_ be reflected in the developers guide until you export the diagram.
42+
//TODO: Discussion about why we're not using asciidoctor-diagram
43+
44+
== Export PlantUML diagrams
45+
46+
The `PlantUML integration` plugin allows you to export individual diagrams to a location of your choosing.
47+
Click the `Save Current Diagram Only` button and choose the location to export the image file.
48+
49+
NOTE: You will have to `git add` any new diagrams generated!
50+
51+
== Common tasks
52+
53+
=== Applying consistent formatting to PlantUML diagrams
54+
55+
It is highly recommended to consistently color your UML diagrams as an visual aid.
56+
You can achieve this by creating a dictionary of colors and import it like CSS.
57+
58+
For example, you can create a `Style.puml` with the contents:
59+
60+
.Style.puml
61+
[source]
62+
----
63+
...
64+
!define LOGIC_COLOR #3333C4
65+
!define LOGIC_COLOR_T1 #7777DB
66+
!define LOGIC_COLOR_T2 #5252CE
67+
!define LOGIC_COLOR_T3 #1616B0
68+
!define LOGIC_COLOR_T4 #101086
69+
...
70+
----
71+
72+
Then you can use it in another PlantUML file like this:
73+
74+
.UndoSequenceDiagram.puml
75+
[source]
76+
----
77+
!include Style.puml
78+
79+
box Logic LOGIC_COLOR_T2
80+
participant ":LogicManager" as LogicManager LOGIC_COLOR
81+
participant ":AddressBookParser" as AddressBookParser LOGIC_COLOR
82+
participant ":UndoCommand" as UndoCommand LOGIC_COLOR
83+
end box
84+
----
85+
86+
You can fine-tune the formatting of PlantUML diagrams with the `skinparam` command.
87+
For example, `skinparam backgroundColor transparent` turns the background of the diagram transparent.
88+
89+
For a comprehensive list of ``skinparam``s head over to the https://plantuml-documentation.readthedocs.io/en/latest/[unofficial PlantUML skinparam documentation].
90+
91+
***
92+
93+
=== Repositioning elements in PlantUML diagrams
94+
95+
While PlantUML's automatic layout engine usually produces satisfactory results, at times the result can be less than ideal, especially on larger diagrams.
96+
Here is an example where the default layout generated by PlantUML has a lot of overlapping lines that are hard to decipher:
97+
98+
.The UI class diagram without additional formatting
99+
image::RawUiDiagram.png[]
100+
101+
NOTE: In most cases, you should consider decomposing the diagram into smaller ones or focusing on a more specific portion of the diagram.
102+
103+
Here are some of the techniques we used in this project to obtain a more palatable diagram.
104+
105+
==== Link lengths
106+
By default, a short link (`\->`) points to right and a long link (`-\->`)
107+
points downwards. you can extend any link to make it longer (```--\->```).
108+
109+
.Length of arrows and its effects
110+
image::ArrowLength.png[]
111+
112+
==== Link directions
113+
Clever usage of arrow directions will resolve most layout issues.
114+
For example, the table below shows how the way in which you specify arrows can results in drastically different layouts for the same diagram.
115+
116+
.Link directions
117+
[cols="40a,60a"]
118+
|===
119+
|Source |Result
120+
121+
|[source, puml]
122+
----
123+
A --> Z
124+
B --> Z
125+
C --> Z
126+
D --> Z
127+
128+
A --> 1
129+
B --> 2
130+
C --> 3
131+
D --> 4
132+
----
133+
|image::AllDown.png[]
134+
135+
|[source, puml]
136+
----
137+
'default is down
138+
A --> Z
139+
'specify down
140+
B -down-> Z
141+
'shorthand for down
142+
C -d-> Z
143+
'arrow lengths take priority
144+
D -down> Z
145+
146+
A -up-> 1
147+
B -up-> 2
148+
C -up-> 3
149+
D -up-> 4
150+
151+
----
152+
|image::UpAndDown.png[]
153+
154+
|[source, puml]
155+
----
156+
A -up-> Z
157+
B -up-> Z
158+
C -up-> Z
159+
D -up-> Z
160+
161+
A --> 1
162+
B --> 2
163+
C --> 3
164+
D --> 4
165+
166+
'Force A B C D
167+
A -right[hidden]- B
168+
B -right[hidden]- C
169+
C -right[hidden]- D
170+
----
171+
|image::HiddenArrows.png[]
172+
|===
173+
174+
==== Reordering definitions
175+
As a general rule of thumb, the layout engine will attempt to order objects in the order in which they are defined.
176+
If there is no formal definition, the objects is taken to be declared upon its first usage.
177+
178+
.Definition ordering and outcomes
179+
[cols="70a,30a"]
180+
|===
181+
|Source |Result
182+
183+
|[source, puml]
184+
----
185+
A --> B
186+
C --> D
187+
----
188+
|image::ABeforeC.png[]
189+
190+
|[source, puml]
191+
----
192+
'Class C is defined before A
193+
Class C
194+
195+
A --> B
196+
C --> D
197+
----
198+
|image::CBeforeA.png[]
199+
200+
|[source, puml]
201+
----
202+
package "Rule Of Thumb"{
203+
Class C
204+
A --> B
205+
C --> D
206+
}
207+
----
208+
|image::PackagesAndConsistency.png[]
209+
|===
210+
211+
TIP: Explicitly define all symbols to avoid any potential layout mishaps.

‎docs/diagrams/Architecture.pptx‎

-39.7 KB
Binary file not shown.

0 commit comments

Comments
 (0)