From fae40b8e51c9bf37690450e0ec58259216207f10 Mon Sep 17 00:00:00 2001
From: RingoftheKing <90739493+RingoftheKing@users.noreply.github.com>
Date: Sat, 13 Apr 2024 01:37:01 +0800
Subject: [PATCH 1/4] Add Find implementation to DG
---
docs/DeveloperGuide.md | 66 ++++++++++++++++++++++++++
docs/diagrams/FindActivityDiagram.puml | 16 +++++++
2 files changed, 82 insertions(+)
create mode 100644 docs/diagrams/FindActivityDiagram.puml
diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md
index cafb729a2f0..c5ce12b2aff 100644
--- a/docs/DeveloperGuide.md
+++ b/docs/DeveloperGuide.md
@@ -286,6 +286,72 @@ The following activity diagram summarizes what happens when a user inputs a sche
* Pros: It follows the DRY principle.
* Cons: We must ensure that the implementation of each individual command are correct.
+### `Find` feature
+
+A `Person` has many details one may query for, this command searches for contacts that matches all the given details.
+Currently, this command supports finding by `nusId`, `name`, `phone`, `email`, `group`s, `tag` fields.
+
+
+
+**Note:** `find` requires at least one field mentioned above to be an input
+
+
+
+Given below is an example usage scenario and how the `find` mechanism behaves at each step.
+
+Step 1. The user executes `find` command.
+
+Step 2. The `AddressBookParser` will call `parseCommand` on the user's input string and return an instance of `FindCommandParser`.
+
+Step 3. `ScheduleCommandParser` will call `parse` which create instances of objects for each of the fields and return an instance of `FindCommand`.
+
+Step 4. The `LogicManager` calls the `execute` method in `FindCommand`.
+
+Step 5. The `execute` method in `FindCommand` executes and finds the relevant person(s) with the given fields.
+
+Step 6. `Model#updateFilteredPersonList()` is called to update the list of persons displayed in AronaPro.
+
+Step 7. Success message is printed onto the results display to notify user.
+
+
+
+**Note:** If a command fails its execution, it will not call `Model#updateFilteredPersonList()` and the list of persons displayed remains the same.
+**Note:** If a command finds no person, it will display an empty list and not an error message.
+
+
+
+The following sequence diagram shows how a find operation goes through the `Logic` component:
+
+
+The following activity diagram summarizes what happens when a user inputs a `find` command:
+
+
+#### Design considerations:
+
+**How find executes**
+
+* User inputs a `find` command with at least one of the fields `nusId`, `name`, `phone`, `email`, `group` or `tag`. The inputs are parsed and a `FindCommand` is created.
+* Each of these fields are made into Java `Predicates` which checks if each field's input matches any person's field (Choice of matching can be changed flexibly in each field's corresponding `Predicate` class) in AronaPro.
+* If any field was not required by the user, a special string (not possible for the user to type when using the add or edit commands) is used to default the `Predicate` to True.
+* A list of persons is created by chaining these `Predicates` using logical `AND`. A list of relevant person(s) are found.
+* The relevant persons are used to update the person list which the model displays.
+
+**Why is it implemented this way?**
+
+* The functionality of find is advertised as finding people that matches ALL the supplemented fields. As such logical AND search is relevant to our case.
+* Use of predicates is also easily extendable, requiring future programmers to simply create a new `Predicate` for new fields and chaining it with the existing predicates
+* The use of a special string to denote a non-specified field, while rudimentary, avoids the hassle required to juggle Java `Optional`s and less transparent Functional Programming paradigms.
+
+**Alternative considerations**
+
+* **Alternative 1 (current choice):** Set non-required fields to a special string that makes a field match everyone, otherwise filter based on the input.
+ * Pros: Easy to implement.
+ * Cons: If the user is able to enter this special string in `add` or `edit` commands, it could result in unexpected behaviour.
+
+* **Alternative 2:** Introduce Java `Optional`s to determine which fields are required.
+ * Pros: There is usage of Single Responsibility Principle. (Current implementation has `Predicate` implicitly handling added responsibility of checking optionality)
+ * Cons: Harder to debug when using Functional Programming paradigms while passing results across classes.
+
### \[Proposed\] Undo/redo feature
diff --git a/docs/diagrams/FindActivityDiagram.puml b/docs/diagrams/FindActivityDiagram.puml
new file mode 100644
index 00000000000..c483f98762a
--- /dev/null
+++ b/docs/diagrams/FindActivityDiagram.puml
@@ -0,0 +1,16 @@
+@startuml
+skin rose
+skinparam ActivityFontSize 15
+skinparam ArrowFontSize 12
+start
+:User executes find command;
+
+if () then ([some field exists])
+ :get a filtered list;
+ :update model with filtered list;
+else ([no field exists])
+ :show an error message;
+endif
+stop
+
+@enduml
\ No newline at end of file
From 037ea2136cd06ccbf05a3ee1837036a66e20d9f5 Mon Sep 17 00:00:00 2001
From: RingoftheKing <90739493+RingoftheKing@users.noreply.github.com>
Date: Sat, 13 Apr 2024 01:37:33 +0800
Subject: [PATCH 2/4] Change inconsistency of Find in UG
---
docs/UserGuide.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/UserGuide.md b/docs/UserGuide.md
index 24baaa2c46c..2d49f818672 100644
--- a/docs/UserGuide.md
+++ b/docs/UserGuide.md
@@ -162,7 +162,7 @@ Examples:
### Locating persons by name: `find`
-Finds persons whose names contain any of the given keywords.
+Finds persons whose details match ALL the given keywords.
Format: `find [id/NUSID] [n/NAME] [p/PHONE] [e/EMAIL] [t/TAG] [g/GROUP] [g/MORE GROUPS]`
From 18c723c06fac75034502a9a599eabc556cd2d03f Mon Sep 17 00:00:00 2001
From: RingoftheKing <90739493+RingoftheKing@users.noreply.github.com>
Date: Sun, 14 Apr 2024 16:44:29 +0800
Subject: [PATCH 3/4] Fix CheckStyle issues
---
docs/diagrams/FindActivityDiagram.puml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/diagrams/FindActivityDiagram.puml b/docs/diagrams/FindActivityDiagram.puml
index c483f98762a..ff052cf13be 100644
--- a/docs/diagrams/FindActivityDiagram.puml
+++ b/docs/diagrams/FindActivityDiagram.puml
@@ -13,4 +13,4 @@ else ([no field exists])
endif
stop
-@enduml
\ No newline at end of file
+@enduml
From cbaeaeaa6289cadbb92de3f6ac75ee3c709fc0b5 Mon Sep 17 00:00:00 2001
From: RingoftheKing <90739493+RingoftheKing@users.noreply.github.com>
Date: Sun, 14 Apr 2024 17:05:02 +0800
Subject: [PATCH 4/4] Fix typo in DG
FindCommand was incorrectly written as
ScheduleCommand
---
docs/DeveloperGuide.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md
index c5ce12b2aff..91397de1f14 100644
--- a/docs/DeveloperGuide.md
+++ b/docs/DeveloperGuide.md
@@ -303,7 +303,7 @@ Step 1. The user executes `find` command.
Step 2. The `AddressBookParser` will call `parseCommand` on the user's input string and return an instance of `FindCommandParser`.
-Step 3. `ScheduleCommandParser` will call `parse` which create instances of objects for each of the fields and return an instance of `FindCommand`.
+Step 3. `FindCommandParser` will call `parse` which create instances of objects for each of the fields and return an instance of `FindCommand`.
Step 4. The `LogicManager` calls the `execute` method in `FindCommand`.