Merge pull request AY2324S2-CS2103T-F12-2#79 from bennyLCK/branch-b-D…

…eveloperGuide

Add description for the Sort persons feature to the Developer Guide

build.gradle

@@ -25,6 +25,10 @@ test {
     finalizedBy jacocoTestReport
 }
 
+run {
+    enableAssertions = true
+}
+
 task coverage(type: JacocoReport) {
     sourceDirectories.from files(sourceSets.main.allSource.srcDirs)
     classDirectories.from files(sourceSets.main.output)

docs/DeveloperGuide.md

@@ -160,6 +160,43 @@ Classes used by multiple components are in the `seedu.addressbook.commons` packa
 
 This section describes some noteworthy details on how certain features are implemented.
 
+
+### \[Implemented\] Sort persons feature
+
+#### Implementation
+
+The sort persons command is implemented in the `SortCommand` class. The `SortCommand` class is a subclass of the `PersonCommand` class, which is in turn a subclass of the `Command` class. The `SortCommand` class is responsible for sorting the persons in the address book according to a field present in the `Person` class by overriding the following method in the `Command` class:
+
+* `execute(Model model)` — Sorts the persons in the address book according to a field present in the `Person` class which is mapped to the `prefix` field in the `SortCommand` object.
+
+Given below is an example usage scenario and how the sort persons feature behaves at each step.
+
+Step 1. The user launches the application for the first time. The `AddressBook` will be initialized with the initial address book state.
+
+Step 2. The user executes `sort n/` command. The `sort` command calls `Model#sortAddressBook("n/")` which sorts the persons in the address book by name in increasing lexicographical order.
+
+The following sequence diagram shows how a sort persons operation goes through the `Logic` component:
+
+<puml src="diagrams/SortPersonsSequenceDiagram-Logic.puml" alt="SortPersonsSequenceDiagram-Logic" />
+
+Similarly, how a sort persons operation goes through the `Model` component is shown below:
+
+<puml src="diagrams/SortPersonsSequenceDiagram-Model.puml" alt="SortPersonsSequenceDiagram-Model" />
+
+#### Design considerations:
+
+**Aspect: How sort persons executes:**
+
+* **Alternative 1 (current choice):** Directly sort the `internalList` field present in the `UniquePersonList` object.
+    * Pros: Easy to implement.
+    * Cons: Permanently orders all persons in the `AddressBook` by the `Person` field specified by the related `prefix`.
+
+
+* **Alternative 2:** Clone the current `internalList` field
+  present in the `UniquePersonList` object, sort the clone, then replace the `internalUnmodifiableList` field in the `UniquePersonList` object with the sorted clone.
+    * Pros: Will not permanently order all persons in the `AddressBook` by the `Person` field specified by the related `prefix`, but only the current view displayed to the user which is refreshed for every opening of the application or commands that changes the view (e.g. `List`, `Find` commands).
+    * Cons: Takes up much more memory space directly proportional to the size of the `AddressBook` since a clone of all `Persons` has to be made.
+
 ### \[Implementing\] Filter feature
 
 <puml src="diagrams/ModelFilterClassDiagram.puml" width="250" />
@@ -184,6 +221,7 @@ Note: If start date is later than the end date, Press Planner will refuse to exe
 
 Note: Filters are **NOT** stored by the program. If you close the app, your filters will be reset. 
 
+
 ### \[Proposed\] Undo/redo feature
 
 #### Proposed Implementation

docs/diagrams/SortPersonsSequenceDiagram-Logic.puml

@@ -0,0 +1,63 @@
+@startuml
+!include style.puml
+skinparam ArrowFontStyle plain
+
+box Logic LOGIC_COLOR_T1
+participant ":LogicManager" as LogicManager LOGIC_COLOR
+participant ":AddressBookParser" as AddressBookParser LOGIC_COLOR
+participant ":SortCommandParser" as SortCommandParser LOGIC_COLOR
+participant "s:SortCommand" as SortCommand LOGIC_COLOR
+end box
+
+box Model MODEL_COLOR_T1
+participant ":Model" as Model MODEL_COLOR
+end box
+[-> LogicManager : execute("sort n/")
+activate LogicManager
+
+LogicManager -> AddressBookParser : parseCommand("sort n/")
+activate AddressBookParser
+
+create SortCommandParser
+AddressBookParser -> SortCommandParser : SortCommandParser("sort n/")
+activate SortCommandParser
+
+SortCommandParser --> AddressBookParser
+deactivate SortCommandParser
+
+AddressBookParser -> SortCommandParser : parse("sort n/")
+activate SortCommandParser
+
+create SortCommand
+SortCommandParser -> SortCommand : SortCommand("n/")
+activate SortCommand
+
+SortCommand --> SortCommandParser
+deactivate SortCommand
+
+SortCommandParser --> AddressBookParser : s
+deactivate SortCommandParser
+SortCommandParser -[hidden]-> AddressBookParser : s
+destroy SortCommandParser
+
+
+AddressBookParser --> LogicManager : s
+deactivate AddressBookParser
+
+LogicManager -> SortCommand : execute()
+activate SortCommand
+
+SortCommand -> Model : sortAddressBook("n/")
+activate Model
+
+Model --> SortCommand
+deactivate Model
+
+SortCommand --> LogicManager : commandResult
+deactivate SortCommand
+SortCommand -[hidden]-> LogicManager : commandResult
+destroy SortCommand
+
+[<--LogicManager : commandResult
+deactivate LogicManager
+@enduml

docs/diagrams/SortPersonsSequenceDiagram-Model.puml

@@ -0,0 +1,36 @@
+@startuml
+!include style.puml
+skinparam ArrowFontStyle plain
+
+box Model MODEL_COLOR_T1
+participant ":Model" as Model MODEL_COLOR
+participant ":ModelManager" as ModelManager MODEL_COLOR
+participant ":AddressBook" as AddressBook MODEL_COLOR
+participant ":UniquePersonList" as UniquePersonList MODEL_COLOR
+end box
+
+[-> Model : sortAddressBook("n/")
+activate Model
+
+Model -> ModelManager : sortAddressBook("n/")
+activate ModelManager
+
+ModelManager -> AddressBook : sortAddressBook("n/")
+activate AddressBook
+
+AddressBook -> UniquePersonList : sortPersons("n/")
+activate UniquePersonList
+
+UniquePersonList --> AddressBook
+deactivate UniquePersonList
+
+AddressBook --> ModelManager
+deactivate AddressBook
+
+ModelManager --> Model :
+deactivate ModelManager
+
+[<-- Model :
+deactivate Model
+
+@enduml