Add Stats implementation and diagrams

docs/DeveloperGuide.md

@@ -216,6 +216,8 @@ The add feature ensures that user input is correctly parsed and validated, and i
 
 ### Delete feature
 
+#### Implementation
+
 The delete mechanism allows users to delete fosterers in the address book. This feature is facilitated by the `DeleteCommand`, `DeleteCommandParser` and `Indices` classes, to handle user input and delete the correct fosterers.  This feature is implemented using the following components and operations:
 
 * `DeleteCommand` — The core component responsible for executing the deletion of fosterers in the address book.
@@ -226,32 +228,87 @@ Given below is an example usage scenario and how the delete mechanism behaves at
 
 ![Interactions Inside the Logic Component for the `delete 1 2 3` Command](images/DeleteMultipleSequenceDiagram.png)
 
+<div markdown="span" class="alert alert-info">:information_source: **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.
+</div>
+
 Step 1. The user enters the delete command with at least one index. The `DeleteCommandParser` is invoked to parse the user's input. 
 
-Step 2. `DeleteCommandParser` will then invoke the `ParserUtil` to check for the validity of indices. If indices are invalid, the system will generate an error message. The error message will be displayed to the user, providing feedback about the issue and the specific constraints that are not met.
+Step 2. `DeleteCommandParser` will then invoke the `ParserUtil` to check for the validity of indices (omitted from diagram for simplicity). If indices are invalid, the system will generate an error message. The error message will be displayed to the user, providing feedback about the issue and the specific constraints that are not met.
 
-Step 3. If indices are valid, the `DeleteCommand` will then execute the deletion by obtaining the fosterers from last seen list, and then deleting them from the address book. This is done in the `execute`  method of `DeleteCommand`.
+Step 3. For each valid index, the `DeleteCommand` will execute the deletion by obtaining that fosterer from the list of unique persons in the address book, and then updating the model to remove the fosterer. This is done in the `execute` method of `DeleteCommand`.
 
-Step 4. A success message is displayed to the user to confirm that the fosterers have been deleted from the address book.
+Step 4. A success message is displayed to the user to confirm that the selected fosterers have been deleted from the address book.
 
 Therefore, by ensuring that the user input indices are correctly parsed and validated, this delete feature allows the user to delete multiple fosterers at once.
 
-
-
 #### Design considerations:
 
 **Aspect: How delete executes:**
 
 * **Alternative 1 (current choice):** Delete multiple fosterers at once.
-    * Pros: Avoid having to update the model multiple times for multiple delete commands.
-    * Cons: Slightly harder to implement. 
-
+    * Pros: Do not have to parse user input multiple times in order for the user to perform mass deletion.
+    * Cons: Slightly harder to implement.
 
 * **Alternative 2:** Delete only one fosterer at a time.
     * Pros: Easy to implement. 
     * Cons: Overhead associated with a chain of delete commands should the user choose to perform multiple deletions.
 
 
+### Statistics feature
+#### Implementation
+
+The Statistics feature provides a summary of selected address book data to the user. The data we can provide insights to are those of available fosterers, current fosterers and housing type of fosterers. Statistics include _number_ and _percentage_ information. <br>
+This is facilitated by the `StatsCommand`, `StatsAvailCommand`, `StatsCurrentCommand` and `StatsHousingCommand` classes, as well as the `StatsCommandParser` class. The relationship between the Stats command classes are shown below.
+![StatsClassDiagram](images/StatsClassDiagram.png)
+
+* `StatsCommand` — This is an abstract class that contains utility methods used by its subclasses for percentage calculation.
+* `StatsAvailCommand` — Contains methods to calculate statistics of available fosterers and the animals they can foster. 
+* `StatsCurrentCommand` — Contains methods to calculate statistics of current fosterers and the animals they are currently fostering. 
+* `StatsHousingCommand` — Contains methods to calculate statistics of the different housing types of fosterers. 
+* `StatsCommandParser` — Contains the parsing methods for string input of the user. It is in charge of parsing the type of statistics requested by the user, and creating the corresponding `StatsCommand`.<br>
+
+Given below is an example usage scenario and how the statistics feature behaves at each step. It shows the execution of a `stats avail` command, which requests for statistics about the available fosterers. 
+
+![Interactions Inside the Logic Component for the StatsAvailCommand](images/StatsAvailSequenceDiagram.png)
+
+![Self Invocation StatsAvail](images/StatsAvailSelfInvDiagram.png)
+
+
+<div markdown="span" class="alert alert-info">:information_source: **Note:** The lifeline for `StatsCommandParser` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram.
+</div>
+
+Step 1. The user enters the `stats avail` command. The `StatsCommandParser` is invoked to parse the user's input.
+
+Step 2. `StatsCommandParser` will then parse the argument inputted with the `stats` command, in this case it is `avail`. If the argument is not `avail`, `curr` or `housing`, the `StatsCommandParser` will then generate an error message to the user, indicating that the requested statistic is not available. 
+
+Step 3. The `StatsAvailCommand` will then call relevant methods to obtain the needed numbers and percentages, done in the `execute` command. 
+
+Step 4. A success message with the statistics will then be displayed to the user.
+
+The other commands `stats curr` and `stats housing` have a similar execution path, replacing `StatsAvailCommand` with `StatsCurrCommand` and `StatsHousingCommand` respectively.
+
+#### Design considerations:
+
+**Aspect: How to display the statistics:**
+
+* **Alternative 1 (current choice):** Show the availability and current statistics separately.
+    * Pros: Displayed statistics are specific to the user's query, showing only the relevant data.
+    * Cons: Need to create more classes.
+
+* **Alternative 2:** Show availability and current statistics together.
+    * Pros: Easier to implement.
+    * Cons: Result message displayed will be very long, making the UI less desirable.
+
+**Aspect: Which list should the statistics be calculated from:**
+
+* **Alternative 1 (current choice):** Calculated from the currently displayed list.
+    * Pros: The resulting statistic corresponds to what the user sees, allowing for easy verification.
+    * Cons: The user may need to perform a find or list to query the list of interest before entering the stats command. 
+
+* **Alternative 2:** Calculated from the main list of fosterers.
+    * Pros: The resulting statistic corresponds to the whole address book, which may cause less confusion for the user.
+    * Cons: Less flexibility for the user.
+
 ### \[Proposed\] Undo/redo feature
 
 #### Proposed Implementation

docs/diagrams/StatsAvailSelfInvDiagram.puml

@@ -0,0 +1,41 @@
+@startuml
+!include style.puml
+
+skinparam ArrowFontStyle plain
+
+mainframe **sd** get availability statistics
+
+participant "a:StatsAvailCommand" as StatsAvailCommand LOGIC_COLOR
+
+StatsAvailCommand -> StatsAvailCommand : getAvailableFosterers(list)
+activate StatsAvailCommand
+StatsAvailCommand --> StatsAvailCommand : availableFosterers
+deactivate StatsAvailCommand
+
+StatsAvailCommand -> StatsAvailCommand : getAbleDogCount(availableFosterers)
+activate StatsAvailCommand
+StatsAvailCommand --> StatsAvailCommand : ableDogCount
+deactivate StatsAvailCommand
+
+StatsAvailCommand -> StatsAvailCommand : getAbleCatCount(availableFosterers)
+activate StatsAvailCommand
+StatsAvailCommand --> StatsAvailCommand : ableCatCount
+deactivate StatsAvailCommand
+
+StatsAvailCommand -> StatsAvailCommand : calculatePercentage(availableCount, total)
+activate StatsAvailCommand
+StatsAvailCommand --> StatsAvailCommand
+deactivate StatsAvailCommand
+
+StatsAvailCommand -> StatsAvailCommand : calculatePercentage(ableDogCount, availableCount)
+activate StatsAvailCommand
+StatsAvailCommand --> StatsAvailCommand
+deactivate StatsAvailCommand
+
+StatsAvailCommand -> StatsAvailCommand : calculatePercentage(ableCatCount, availableCount)
+activate StatsAvailCommand
+StatsAvailCommand --> StatsAvailCommand
+deactivate StatsAvailCommand
+|||
+
+@enduml

docs/diagrams/StatsAvailSequenceDiagram.puml

@@ -0,0 +1,74 @@
+@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 ":StatsCommandParser" as StatsCommandParser LOGIC_COLOR
+participant "a:StatsAvailCommand" as StatsAvailCommand LOGIC_COLOR
+participant ":CommandResult" as CommandResult LOGIC_COLOR
+end box
+
+box Model MODEL_COLOR_T1
+participant ":Model" as Model MODEL_COLOR
+end box
+
+[-> LogicManager : execute("stats avail")
+activate LogicManager
+
+LogicManager -> AddressBookParser : parseCommand("stats avail")
+activate AddressBookParser
+
+create StatsCommandParser
+AddressBookParser -> StatsCommandParser
+activate StatsCommandParser
+
+StatsCommandParser --> AddressBookParser
+deactivate StatsCommandParser
+
+AddressBookParser -> StatsCommandParser : parse("avail")
+activate StatsCommandParser
+
+create StatsAvailCommand
+StatsCommandParser -> StatsAvailCommand
+activate StatsAvailCommand
+
+StatsAvailCommand --> StatsCommandParser : a
+deactivate StatsAvailCommand
+
+StatsCommandParser --> AddressBookParser : a
+deactivate StatsCommandParser
+'Hidden arrow to position the destroy marker below the end of the activation bar.
+StatsCommandParser -[hidden]-> AddressBookParser
+destroy StatsCommandParser
+
+AddressBookParser --> LogicManager : a
+deactivate AddressBookParser
+
+LogicManager -> StatsAvailCommand : execute()
+activate StatsAvailCommand
+
+StatsAvailCommand -> Model : getFilteredPersonList()
+activate Model
+
+Model --> StatsAvailCommand : list
+deactivate Model
+
+ref over StatsAvailCommand
+get availability statistics
+end ref
+
+create CommandResult
+StatsAvailCommand -> CommandResult
+activate CommandResult
+
+CommandResult --> StatsAvailCommand
+deactivate CommandResult
+
+StatsAvailCommand --> LogicManager : result
+deactivate StatsAvailCommand
+
+[<--LogicManager
+deactivate LogicManager
+@enduml

docs/diagrams/StatsClassDiagram.puml

@@ -0,0 +1,15 @@
+@startuml
+!include style.puml
+skinparam arrowThickness 1.1
+skinparam arrowColor LOGIC_COLOR
+skinparam classBackgroundColor LOGIC_COLOR
+
+Class StatsCommand
+Class "{abstract}\nCommand" as Command
+
+StatsCommand -up-|> Command
+StatsAvailCommand -up-|> StatsCommand
+StatsCurrentCommand -up-|> StatsCommand
+StatsHousingCommand -up-|> StatsCommand
+
+@enduml