[AB3: Tracing Code] Add more headers to section instructions

tutorials/ab3TracingCode.md

@@ -6,21 +6,22 @@ pageNav: 3
 
 # {{ title }}
 
-
+<link rel="stylesheet" href="images/tracing/static/tracing.css">
 > Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. …[Therefore,] making it easy to read makes it easier to write.
 >
 > —  Robert C. Martin Clean Code: A Handbook of Agile Software Craftsmanship
 
 When trying to understand an unfamiliar code base, one common strategy used is to trace some representative execution path through the code base. One easy way to trace an execution path is to use a debugger to step through the code. In this tutorial, you will be using the IntelliJ IDEA’s debugger to trace the execution path of a specific user command.
 
 
-## Before we start
+<h2 id="before-we-start">Before we start</h2>
 
 Before we jump into the code, it is useful to get an idea of the overall structure and the high-level behavior of the application. This is provided in the 'Architecture' section of the developer guide. In particular, the architecture diagram (reproduced below), tells us that the App consists of several components.
 
 <pic src="https://se-education.org/addressbook-level3/images/ArchitectureDiagram.png" alt="ArchitectureDiagram" />
 
-It also has a sequence diagram (reproduced below) that tells us how a command propagates through the App.
+It also has a sequence diagram (reproduced below)
+that tells us how a command propagates through the App.
 
 <pic src="https://se-education.org/addressbook-level3/images/ArchitectureSequenceDiagram.png" width="550" />
 
@@ -88,15 +89,44 @@ Bingo\! `MainWindow#executeCommand()` seems to be exactly what we’re looking f
 Now let’s set the breakpoint. First, double-click the item to reach the corresponding code. Once there, click on the left gutter to set a breakpoint, as shown below.
  ![LeftGutter](images/tracing/LeftGutter.png)
 
+
 ## Tracing the execution path
 
-Recall from the User Guide that the `edit` command has the format: `edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]…` For this tutorial we will be issuing the command `edit 1 n/Alice Yeoh`.
+At this point, you should have appreciated the general sequence diagram **shown** [above](#before-we-start)
+
+
+For this code tracing,
+we will explore the `EditCommand` which is a feature that allows users to edit exising person fields in AB3.
+
+<box type="tip" seamless>
+    Recall from the <a href="https://se-education.org/addressbook-level3/UserGuide.html#editing-a-person--edit">User Guide</a> that the <code>edit</code> command has the format: <code>edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]…</code>.
+</box>
+
+For this tutorial, we will be issuing the command <code>edit 1 n/Alice Yeoh</code>
+
+Specifically,
+we trace the following sequence diagram
+which explores the `Logic` component in more detail which will be paramount to understanding other commands as well! 
+
+<puml src="images/tracing/LogicSequenceDiagramWithMainWindow.puml" alt="Tracing an `edit` command with specific arguments"></puml>
+
 
 <box type="tip" seamless>
 
 **Tip:** Over the course of the debugging session, you will encounter every major component in the application. Try to keep track of what happens inside the component and where the execution transfers to another component.
 </box>
 
+
+
+
+
+### 1. MainWindow -> LogicManager
+
+<annotate src="images/tracing/LogicSequenceDiagramWithMainWindow.png" width="900" alt="Sample Image">
+  <!-- Set Legend to both -->
+  <a-point x="26%" y="20%"  label="1"/>
+</annotate>
+
 1. To start the debugging session, simply `Run` \> `Debug Main`
 
 1. When the GUI appears, enter `edit 1 n/Alice Yeoh` into the command box and press `Enter`.
@@ -111,7 +141,17 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
 1. We are interested in the `logic.execute(commandText)` portion of that line so let’s _Step in_ into that method call:<br>
     ![StepInto](images/tracing/StepInto.png)
 
-1. We end up in `LogicManager#execute()` (not `Logic#execute` -- but this is expected because we know the `execute()` method in the `Logic` interface is actually implemented by the `LogicManager` class). Let’s take a look at the body of the method. Given below is the same code, with additional explanatory comments.
+### 2. LogicManager -> AddressBookParser
+
+<annotate src="images/tracing/LogicSequenceDiagramWithMainWindow.png" width="900" alt="Sample Image">
+  <!-- Set Legend to both -->
+  <a-point x="50.7%" y="29%"  label="2"/>
+</annotate>
+
+
+1. After stepping in, we note that `MainWindow` has passed control to the `Logic` component.
+
+1. Specifically, We end up in `LogicManager#execute()` (not `Logic#execute` -- but this is expected because we know the `execute()` method in the `Logic` interface is actually implemented by the `LogicManager` class). Let’s take a look at the body of the method. Given below is the same code, with additional explanatory comments.
 
    **LogicManager\#execute().**
 
@@ -146,7 +186,8 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
 1. _Step over_ the logging code since it is of no interest to us now.
    ![StepOver](images/tracing/StepOver.png)
 
-1. _Step into_ the line where user input is parsed from a String to a Command, which should bring you to the `AddressBookParser#parseCommand()` method (partial code given below):
+1. _Step into_ the line where user input in parsed from a String to a Command, which should bring you to the `AddressBookParser#parseCommand()` method (partial code given below):
+
    ```java
    public Command parseCommand(String userInput) throws ParseException {
        ...
@@ -155,6 +196,18 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
        ...
    ```
 
+<h3 id="flow-3">3. AddressBookParser -> EditCommandParser</h3>
+
+
+<annotate src="images/tracing/LogicSequenceDiagramWithMainWindow.png" width="900" alt="Sample Image">
+  <!-- Set Legend to both -->
+  <a-point x="60.7%" y="30%"  label="3"/>
+  <a-point x="69%" y="53%"  label="4"/>
+</annotate>
+
+
+1. Now, `LogicManager` has passed control to `AddressBookParser`
+
 1. _Step over_ the statements in that method until you reach the `switch` statement. The 'Variables' window now shows the value of both `commandWord` and `arguments`:<br>
     ![Variables](images/tracing/Variables.png)
 
@@ -169,6 +222,13 @@ Recall from the User Guide that the `edit` command has the format: `edit INDEX [
     ...
     ```
 
+1. Note that this creates the `EditCommandParser` first.
+
+
+### 4. AddressBookParser -> EditCommand
+
+1. `AddressBookParser` calling `parse(...)` of the newly created `EditCommandParser`. This is shown in the diagram [earlier when EditCommand was created](#flow-3).
+
 1. Let’s see what `EditCommandParser#parse()` does by stepping into it. You might have to click the 'step into' button multiple times here because there are two method calls in that statement: `EditCommandParser()` and `parse()`.
 
    <box type="tip" seamless>

tutorials/images/style.puml

@@ -18,12 +18,14 @@
 !define LOGIC_COLOR_T2 #6A6ADC
 !define LOGIC_COLOR_T3 #1616B0
 !define LOGIC_COLOR_T4 #101086
+!define LOGIC_COLOR_T5 #adbc40
 
 !define MODEL_COLOR #9D0012
 !define MODEL_COLOR_T1 #F97181
 !define MODEL_COLOR_T2 #E41F36
 !define MODEL_COLOR_T3 #7B000E
 !define MODEL_COLOR_T4 #51000A
+!define MODEL_COLOR_T5 #c6d4c0
 
 !define STORAGE_COLOR #A38300
 !define STORAGE_COLOR_T1 #FFE374

tutorials/images/tracing/EditSequenceDiagramWithMainWindow.puml

@@ -0,0 +1,80 @@
+@startuml
+!include ../style.puml
+skinparam ArrowFontStyle plain
+
+box Ui MODEL_COLOR_T5
+participant "m:MainWindow" as MainWindow LOGIC_COLOR_T5
+
+box Logic LOGIC_COLOR_T1
+participant ":LogicManager" as LogicManager LOGIC_COLOR
+participant ":AddressBookParser" as AddressBookParser LOGIC_COLOR
+participant ":EditCommandParser" as EditCommandParser LOGIC_COLOR
+participant "d:EditCommand" as EditCommand LOGIC_COLOR
+participant "r:CommandResult" as CommandResult LOGIC_COLOR
+end box
+
+box Model MODEL_COLOR_T1
+participant "m:Model" as Model MODEL_COLOR
+end box
+
+
+
+--> MainWindow
+activate MainWindow
+MainWindow -> LogicManager : execute("edit 1 n/Alice Yeoh")
+activate LogicManager
+
+LogicManager -> AddressBookParser : parseCommand("edit 1 n/Alice Yeoh")
+activate AddressBookParser
+
+create EditCommandParser
+AddressBookParser -> EditCommandParser
+activate EditCommandParser
+
+EditCommandParser --> AddressBookParser
+deactivate EditCommandParser
+
+AddressBookParser -> EditCommandParser : parse("1 n/Alice Yeoh")
+activate EditCommandParser
+
+create EditCommand
+EditCommandParser -> EditCommand
+activate EditCommand
+
+EditCommand --> EditCommandParser :
+deactivate EditCommand
+
+EditCommandParser --> AddressBookParser : d
+deactivate EditCommandParser
+'Hidden arrow to position the destroy marker below the end of the activation bar.
+EditCommandParser -[hidden]-> AddressBookParser
+destroy EditCommandParser
+
+AddressBookParser --> LogicManager : d
+deactivate AddressBookParser
+
+LogicManager -> EditCommand : execute(m)
+activate EditCommand
+
+EditCommand -> Model : ...
+activate Model
+
+Model --> EditCommand
+deactivate Model
+
+create CommandResult
+EditCommand -> CommandResult
+activate CommandResult
+
+CommandResult --> EditCommand
+deactivate CommandResult
+
+EditCommand --> LogicManager : r
+deactivate EditCommand
+
+LogicManager --> MainWindow
+deactivate LogicManager
+
+[<-- MainWindow
+deactivate MainWindow
+@enduml

tutorials/images/tracing/LogicSequenceDiagram.puml

@@ -9,14 +9,18 @@ Participant "command:EditCommand" as ec LOGIC_COLOR
 
 [-> logic : execute
 activate logic
-logic -> abp ++: parseCommand(commandText)
+logic -> abp ++: parseCommand(edit 1 n/Alice Yeoh)
 create ecp
 abp -> ecp
-abp -> ecp ++: parse(arguments)
+activate ecp
+ecp -> abp
+deactivate ecp
+abp -> ecp ++: parse(1 n/Alice Yeoh)
 create ec
-ecp -> ec ++: index, editPersonDescriptor
+ecp -> ec ++: 1, n/Alice Yeoh
 ec --> ecp --
 ecp --> abp --: command
 abp --> logic --: command
+[<-- logic
 
 @enduml

tutorials/images/tracing/LogicSequenceDiagramWithMainWindow.puml

@@ -0,0 +1,27 @@
+@startuml
+!include ../style.puml
+skinparam ArrowFontStyle plain
+
+Participant ":MainWindow" as main LOGIC_COLOR
+Participant ":LogicManager" as logic LOGIC_COLOR
+Participant ":AddressBookParser" as abp LOGIC_COLOR
+Participant ":EditCommandParser" as ecp LOGIC_COLOR
+Participant "command:EditCommand" as ec LOGIC_COLOR
+
+main -> logic : execute(edit 1 n/Alice Yeoh)
+activate logic
+logic -> abp ++: parseCommand(edit 1 n/Alice Yeoh)
+create ecp
+abp -> ecp
+activate ecp
+ecp -> abp
+deactivate ecp
+abp -> ecp ++: parse(1 n/Alice Yeoh)
+create ec
+ecp -> ec ++: 1, editPersonDescriptor
+ec --> ecp --
+ecp --> abp --: command
+abp --> logic --: command
+logic --> main --: command
+
+@enduml

tutorials/images/tracing/static/tracing.css

@@ -0,0 +1,6 @@
+/* custom.css */
+h3 {
+    color: #ff6347;
+    padding: 10px;
+    border-radius: 5px;
+}