Merge pull request #90 from yucheng11122017/pin-command

Update developer guide for pin command

docs/DeveloperGuide.md

@@ -238,6 +238,39 @@ _{more aspects and alternatives to be added}_
 
 _{Explain here how the data archiving feature will be implemented}_
 
+### \[Work in progress\] Pin feature
+
+#### Proposed Implementation
+
+The operation are exposed in the `Command` interface as `Command#Execute`, specifically in `PinCommand#Execute`
+
+Given below is an example usage scenario and how the pin mechanism behaves at each step.
+
+Step 1. The user launches the application for the first time.
+
+Step 2. The user executes `add n/David …​` to add a new person.
+
+Step 3. Connections displays the new person. 
+
+Step 4. The user decides that the contact, currently at index 1, is important and should be pinned. User executes pin 1
+
+Step 5. Connections will pin the contact and moves the contact to the top of the list of contacts.
+
+The following sequence diagram shows how the pin operation works:
+
+![PinSequenceDiagram](images/PinSequenceDiagram.png)
+
+#### Design considerations:
+
+**Aspect: How pin executes:**
+
+* **Alternative 1:** Person has a boolean field isPinned to indicate if the person is pinned or not
+    * Pros: Easy to implement, less memory usage
+    * Cons: Less flexibility in expanding the usage of pin.
+
+* **Alternative 2 (current choice):** Person has Pin object to indicate if the person is pinned or not
+    * Pros: More flexible to expand, other methods can be added to Pin if needed.
+    * Cons: Will use more memory.
 
 --------------------------------------------------------------------------------------------------------------------
 

docs/diagrams/PinSequenceDiagram.puml

@@ -0,0 +1,82 @@
+@startuml
+!include style.puml
+
+box UI UI_COLOR
+participant "UI" as UI UI_COLOR
+end box
+
+box Logic LOGIC_COLOR_T1
+participant ":LogicManager" as LogicManager LOGIC_COLOR
+participant ":AddressBookParser" as AddressBookParser LOGIC_COLOR
+participant ":PinCommandParser" as PinCommandParser LOGIC_COLOR
+participant "d:PinCommand" as PinCommand LOGIC_COLOR
+participant ":CommandResult" as CommandResult LOGIC_COLOR
+end box
+
+box Model MODEL_COLOR_T1
+participant ":Model" as Model MODEL_COLOR
+end box
+
+UI -> LogicManager : execute("pin 1")
+activate LogicManager
+
+LogicManager -> AddressBookParser : parseCommand("pin 1")
+activate AddressBookParser
+
+create PinCommandParser
+AddressBookParser -> PinCommandParser
+activate PinCommandParser
+
+PinCommandParser --> AddressBookParser
+deactivate PinCommandParser
+
+AddressBookParser -> PinCommandParser : parse("1")
+activate PinCommandParser
+
+create PinCommand
+PinCommandParser -> PinCommand
+activate PinCommand
+
+PinCommand --> PinCommandParser : d
+deactivate PinCommand
+
+PinCommandParser --> AddressBookParser : d
+deactivate PinCommandParser
+'Hidden arrow to position the destroy marker below the end of the activation bar.
+PinCommandParser -[hidden]-> AddressBookParser
+destroy PinCommandParser
+
+AddressBookParser --> LogicManager : d
+deactivate AddressBookParser
+
+LogicManager -> PinCommand : execute()
+activate PinCommand
+
+PinCommand -> Model : getFilteredPersonList()
+activate Model
+Model --> PinCommand : filteredPersonList
+deactivate Model
+
+PinCommand -> PinCommand : createPinnedPerson(personToPin)
+activate PinCommand
+PinCommand --> PinCommand : pinnedPerson
+deactivate PinCommand
+
+create CommandResult
+PinCommand -> CommandResult
+activate CommandResult
+
+CommandResult --> PinCommand
+deactivate CommandResult
+
+PinCommand -> Model : setPerson(originalPerson, pinnedPerson)
+activate Model
+Model --> PinCommand
+deactivate Model
+
+PinCommand --> LogicManager : result
+deactivate PinCommand
+
+UI <--LogicManager: result
+deactivate LogicManager
+@enduml