Update user docs

docs/DeveloperGuide.md

@@ -96,7 +96,6 @@ The sequence diagram below illustrates the interactions within the `Logic` compo
 
 ![Interactions Inside the Logic Component for the `delete 1` Command](images/DeleteSequenceDiagram.png)
 
-
 How the `Logic` component works:
 
 1. When `Logic` is called upon to execute a command, it is passed to an `AddressBookParser` object which in turn creates a parser that matches the command (e.g., `DeleteCommandParser`) and uses it to parse the command.
@@ -173,7 +172,7 @@ on the list of contacts in the `ModelManager`.
 
 The contact list is automatically kept in a constantly sorted state by leveraging `SortedList` from the JavaFX Collections library. Since the class works with `ObservableList`s, which the Model's `Contacts` also utilises, we are able to leverage this class more easily.
 
-The Model obtains an unsorted, unmodifiable list from `Contacts` and wraps it in a `SortedList`. We specify an `AlphabeticalComparator` to define our own alphabetical sorting order, which takes casing into account. This facilitates the intended propagation of changes from the nested list to the sorted list.
+The Model obtains an unsorted, unmodifiable list from `Contacts` and wraps it in a `SortedList`. We specify an `AlphabeticalComparator` to define our own alphabetical sorting order, which takes capitalization into account. This facilitates the intended propagation of changes from the nested list to the sorted list.
 
 For operability with the find feature, this sorted list is further wrapped in a `FilteredList` to limit the scope of what the user sees as needed. A dummy filter `Predicate` which allows all contacts to pass is used as the default filter. It is this filtered list that the model stores in a field.
 
@@ -206,9 +205,11 @@ The following activity diagram summarises what happens when a user executes an e
 ### Product scope
 
 **Target user profile**: NUS SoC students, who:
-- can type fast and prefer typing
-- are reasonably comfortable with command-line inputs
-- wish to label contacts by category (e.g. classmates from certain courses, professors)
+
+- Can type fast and prefer typing
+- Are reasonably comfortable with command-line inputs
+- Wish to label contacts by category (e.g. professors, classmates from certain courses)
+- Have many different ways to reach their contacts (e.g. local/overseas phone number, Telegram, Discord etc.)
 
 **Value proposition**: Manage contacts quickly via text commands, with useful features relevant to SoC students.
 
@@ -422,3 +423,7 @@ testers are expected to do more *exploratory* testing.
    1. _{explain how to simulate a missing/corrupted file, and the expected behavior}_
 
 1. _{ more test cases …​ }_
+
+## **Appendix: Planned enhancements**
+
+//TODO this is for countering known feature flaws to help grading, after the feature freeze. We can only list `4 members x 2 = 8` enhancements here

docs/UserGuide.md

@@ -1,155 +1,245 @@
 ---
-
 layout: page
 title: User Guide
 ---
 
-**ConText** is a **desktop app designed for managing contacts of NUS SoC students.** ConText leverages a Command Line Interface (CLI) combined with a modern Graphical User Interface (GUI) to offer speedy contact management. If you're familiar with typing commands, you'll find ConText incredibly efficient.
-![ConText UI](images/Ui.png)
+**ConText** is a desktop app that allows for managing contacts quickly via text commands.
+It is optimized for use via an in-app Command Line Interface (CLI), while still having the benefits of a Graphical User Interface (GUI).
+
+It has useful features relevant to NUS SoC students:
+
+- Tagging contacts by category: You could tag all your professors and classmates with custom tags such as "Professor", "Tutorial mate", "CS2103" etc., then filter by tag.
+- Storing different ways to reach people: By adding alternate contact details, you could have local phone number, overseas phone number, Telegram, Discord etc. all in the same contact.
 
-* Table of Contents
-  {:toc}
+If you can type fast, prefer typing, and are reasonably comfortable with CLI inputs, ConText can let you manage contacts faster than traditional GUI apps.
+
+- Table of Contents
+{:toc}
 
 ---
 
-## Getting Started
+## Quick start
+
+1. Ensure you have [Java 11](https://openjdk.org/) or above installed.
 
-Upon launching ConText, you'll be presented with a clean interface. At the top is the command input box. Right below it, feedback from the commands you input will be displayed. Beneath the feedback section, you'll find a list of your contacts.
+1. Download the latest `context.jar` [here](https://github.com/AY2324S1-CS2103-W14-3/tp/releases).
 
-### Entering text commands
+1. Place the JAR file in the folder you want to use as the app's home folder.
 
-1. Click on the command input box at the top of the application.
-2. Type your command.
-3. Press `Enter` to run the command.
+1. Open a command terminal, `cd` into the folder you put the JAR file in, and use the `java -jar context.jar` command to run the application.\
+A window should open with a GUI similar to the one below. Note how the app starts off with some sample data.\
+![Ui](images/Ui.png)
 
-Any feedback, including errors, will appear directly below the input box.
+1. The text box at the top of the window should be automatically selected. This is where you can type your text commands. Press <kbd>Enter</kbd> to execute them.\
+The feedback from each command's execution will be displayed below the text box, with the currently displayed list of contacts below that.
+
+1. Refer to the [Features](#features) section below to find out about the various commands.
+
+<div markdown="span" class="alert alert-primary">
+    :bulb: **Tip:**
+    You could test out some commands on the sample data.
+    Once you are familiarised, feel free to use the `clear` command to delete all the sample data, and start adding your own contacts!
+</div>
 
 ---
 
-### Adding a Contact: `add`
+## Features
+
+<div markdown="block" class="alert alert-info">
+    **:information_source: About the command format:**\
 
-//TODO UG needs quite a lot of updates. We should take from or re-edit off the original AB3 documentation to make ours more fleshed out. We should also make ours match the messages in the code.
+    - Some commands take in parameters.
+    e.g. in `add n/NAME`, the `add` command takes in an `n/` parameter.
 
-Easily add a new contact to your list with the `add` command.
+    - Words in `UPPER_CASE` are placeholders for values to be specified.\
+    e.g. in `edit INDEX`, you should specify an `INDEX` such as `edit 1`.\
+    e.g. in `add n/NAME`, you should specify a `NAME` such as `add n/John Doe`.
+
+    - Parameters in square brackets are optional.\
+    e.g in `n/NAME [o/NOTE]`, you could specify `n/John Doe o/Good at SE.`, or just `n/John Doe`.
+
+    - Parameters with `…`​ after them can be specified multiple times.\
+    e.g. in `[t/TAG]…​`, which is optional but can also be specified multiple times, you could specify ` ` (none specified), `t/NUS`, `t/NUS t/CS2103 course` etc.
+
+    - Parameters can be specified in any order.\
+    e.g. in `n/NAME p/PHONE_NUMBER`, the order `p/PHONE_NUMBER n/NAME` also works.
+
+    - Extra words for commands that do not take any parameters (such as `list` or `help`) will be ignored.\
+    e.g. `list 10 n/John Doe z/Extra` will be interpreted as just `list`.
+
+    - If you are using the PDF version of this user guide, be careful when copy-pasting commands that span multiple lines. Spaces surrounding line breaks may get omitted when copied over to the app.
+</div>
+
+### Adding a contact: `add`
+
+Adds a new contact.
 
 **Format:**
-`add n/FULL_NAME p/PHONE_NUMBER e/EMAIL [o/NOTE] [t/TAG]... [a/ALTERNATE_CONTACT]...`
+`add n/NAME p/PHONE_NUMBER e/EMAIL [o/NOTE] [t/TAG]... [a/ALTERNATE_CONTACT]...`
 
-* A contact can have 0 or 1 note
-* A contact can have any number of tags (including 0)
-* A contact can have any number of alternate contacts (including 0)
+<div markdown="span" class="alert alert-primary">
+    :bulb: **About tags:**
+    Duplicate tags are only counted once.
+</div>
 
-<div markdown="span" class="alert alert-primary">:bulb: **Tip:**
-The format for alternate contact is "Type of alternate contact": "Name of alternate contact"
+<div markdown="span" class="alert alert-primary">
+    :bulb: **About the alternate contact format:**
+    The format for `ALTERNATE_CONTACT` is `TYPE: USERNAME`, roughly looking like `SocialMedia: Username`.
 </div>
 
 **Examples:**
-- `add n/John Doe p/98765432 e/[email protected]`
-- `add n/John Doe p/98765432 e/[email protected] o/CS2103 Prof. t/NUS t/CS2103 course a/Telegram: JohnDoe`
 
----
+- `add n/John Doe p/98765432 e/[email protected]`
+- `add n/John Doe p/98765432 e/[email protected] o/Good at SE. t/NUS t/CS2103 course a/Telegram: JohnDoe`
 
-### Viewing All Contacts: `list`
+### Editing a contact: `edit`
 
-Display all your stored contacts.
+Edits an existing contact at the specified `INDEX`.
 
 **Format:**
-`list`
+`edit INDEX [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [o/NOTE] [t/TAG]... [a/ALTERNATE_CONTACT]...`
 
----
+<div markdown="span" class="alert alert-primary">
+    :bulb: **About index numbers:**
+    `INDEX` refers to the index number currently shown in the displayed contact list (#1, #2, #3 etc.).
+    Indices must be a positive integer to be valid (1, 2, 3 etc.), and must exist in the displayed contact list.
+</div>
 
-### Filtering Contacts by Tag: `filter`
+<div markdown="span" class="alert alert-primary">
+    :bulb: **About tags/the alternate contact format:**
+    Please refer to the [above](#adding-a-contact-add).
+</div>
 
-Search and display contacts with tag matching the given keywords (case-insensitive).
+- At least one of the optional parameters must be specified.
 
-**Format:**
-`filter [KEYWORDS]`
+- Each specified parameter will have its new value(s) replace all existing value(s) for that parameter.\
+e.g. `edit 1 n/The Myth` will edit the name of contact #`1` to `The Myth`, without changing any other parameter values for that contact.
+    - When editing tags, the new specified tag(s) will similarly replace all existing tag(s).\
+    You can specify no tags via a _single_ `t/` without a value.
+    - Likewise, when editing alternate contacts, you can specify no alternate contacts via a _single_ `a/` without a value.
 
-**Example:**
-`filter Friend`
+**Examples:**
 
----
+- `edit 1 p/87654321 e/[email protected]`
+(Edits the phone number and email address of contact #`1` to `87654321` and `[email protected]` respectively.)
 
-### Deleting Contacts: `delete`
+- `edit 3 o/Member of NUS S/U t/` (Edits the note of contact #`3` to `Member of NUS S/U` and clears any of its existing tags.)
 
-Remove one or more contacts based on their indices. The indices refer to the index numbers shown in the displayed contact list.
+### Deleting contacts: `delete`
+
+Deletes the contact(s) at the specified `INDEX` or indices.
 
 **Format:**
-`delete INDEX [INDEX]...`
+`delete INDEX...`
+
+<div markdown="span" class="alert alert-primary">
+    :bulb: **About index numbers:**
+    Please refer to the [above](#editing-a-contact-edit).
+</div>
 
 - You can delete multiple contacts at once by specifying multiple indices separated by spaces.
-- Indices **must be positive integers** like 1, 2, 3, …​
-- Duplicated indices only count once.
+
+- Duplicate indices are only counted once.
+
 - Invalid indices will cause abortion of the delete command.
 
 **Examples:**
+
 - `delete 1`
-  Deletes the contact at index 1.
+(Deletes the contact at index #1.)
 
 - `delete 1 3 5`
-  Deletes the contacts at the specified indices: 1, 3, and 5.
+(Deletes the contacts at indices #1, #3, and #5.)
 
----
+### Clearing all contacts: `clear`
 
-### Viewing Help: `help`
+Deletes all contacts!
 
-Click the help button on the top to navigate to a comprehensive help manual.
+**Format:**
+`clear`
 
----
+<div markdown="span" class="alert alert-warning">
+    :exclamation: **Caution:**
+    This command will immediately delete all your contacts. **Use with caution!**
+</div>
+
+### Listing all contacts: `list`
+
+Shows all contacts.
 
-### Locating Contacts by Name: `find`
+**Format:**
+`list`
+
+### Finding by name: `find`
 
-Search and display contacts with names containing any of the given keywords.
+Shows contacts whose names have a word that fully matches any of the specified keywords.
 
 **Format:**
-`find [KEYWORD]...`
+`find KEYWORD...`
+
+- The search is case-insensitive.\
+e.g Keyword `john` will match the name `John`.
+
+- The order of the keywords does not matter.\
+e.g. Keywords `Amy John` will show the same contacts as keywords `John Amy`.
+
+- Only full words will be matched.\
+e.g. Keyword `John` will not match the names `Johnny` or `Jo`.
+
+- Each name only needs one word to fully match at least one keyword (i.e. `OR` search).\
+e.g. `find Bee John` will match the names `Amy Bee` and `John Doe`.
+
+**Examples:**
+
+- `find John`
+- `find alex Bernice CHARLOTTE`
+
+### Filtering by tag: `filter`
+
+Search and display contacts with tag matching the given keywords (case-insensitive).
+
+**Format:**
+`filter [KEYWORDS]`
 
 **Example:**
-`find John Alice`
 
----
+- `filter Friend`
 
-### Clearing All Entries: `clear`
+### Viewing help: `help`
 
-Remove all contacts from your list. **Apply with caution!**
+Opens a subwindow with a convenient link to the user guide.
 
 **Format:**
-`clear`
+`help`
 
----
+Alternatively, you can press <kbd>F1</kbd> or click Help → Help in the top toolbar.
 
-### Exiting the Program: `exit`
+### Exiting the app: `exit`
 
-Close the ConText application.
+Exits the app.
 
 **Format:**
 `exit`
 
----
+Alternatively, you can click File → Exit in the top toolbar.
 
-### Editing a Contact: `edit`
+### Automatic sorting
 
-Modify an existing contact's details in your list.
+The displayed contact list is always automatically sorted in ascending alphabetical order, regardless of capitalization.
 
-**Format:**
-`edit INDEX [n/FULL_NAME] [p/PHONE_NUMBER] [e/EMAIL] [o/NOTE] [t/TAGS]... [a/ALTERNATE_CONTACT]...`
-
-* Edits the person at the specified `INDEX`. The index refers to the index number shown in the displayed person list. 
-The index must be a positive integer 1, 2, 3, ...
-* At least one of the optional fields must be provided.
-* Existing values will be updated to the input values.
-* When editing tags, existing tags will be removed. The adding of tags is not cumulative.
-* Similar to tags, existing alternate contacts will be removed when editing them.
-* You can remove all the contact's tags by typing `t/` without specifying any tags after it.
-* Similar to tags, you can remove all the contact's alternate contacts by typing `a/` without specifying any alternate
-contacts after it.
-
-<div markdown="span" class="alert alert-primary">:bulb: **Tip:**
-The format for alternate contact is the same as mentioned above in the <a href="#adding-a-contact-add">Adding a Contact</a> section.
-</div>
+### Automatic saving
 
-**Example:**
-`edit 2 n/John Doe p/98765432 e/[email protected]`
+Your contacts get automatically saved to the file system after each successful command execution. There is no need to save manually.
 
 ---
-Remember, whenever in doubt, you can always navigate to the help webpage via the `help` tab at the top.
+
+## Known limitations
+
+1. **Long contact details are not in the product's scope.**\
+e.g. names/phone numbers/emails/notes/tags/alternate contacts with hundreds of characters.\
+Such long text is likely to get shortened with ellipses (`...`) or cut off by the app's window.\
+You may try to remedy this by resizing the app's window to be wider.
+
+1. **Multiple monitors are not in the product's scope.**\
+When using multiple monitors, if you move the app's window to a secondary monitor, then later switch to using just the primary monitor, the GUI will reopen off-screen.\
+You can remedy this by deleting the `settings.json` file created by the app before running the app again.

docs/index.md

@@ -8,11 +8,10 @@ title: ConText
 
 ![UI](images/Ui.png)
 
+**ConText** is a desktop app that allows for managing contacts quickly via text commands, with useful features relevant to NUS SoC students.
+While it has a Graphical User Interface, most of its user interactions happen via an in-app Command Line Interface.
 
-**ConText is a desktop app designed for NUS SoC students to manage their contacts quickly via text commands.**
-While it has a GUI, most of its user interactions happen via a CLI (Command Line Interface).
-
-- If you are interested in using ConText, head over to the [_Quick Start_ section of the **User Guide**](./UserGuide.html#quick-start).
+- If you are interested in using ConText, please check out the [**User Guide**](./UserGuide.html).
 - If you are interested about developing ConText, the [**Developer Guide**](./DeveloperGuide.html) is a good place to start.
 
 **Acknowledgements**

src/main/java/swe/context/logic/commands/AddCommand.java

@@ -22,8 +22,6 @@
 public class AddCommand extends Command {
     public static final String COMMAND_WORD = "add";
 
-    //TODO values like these could be in some kind of ProductionData, which
-    // could be used in tests alongside TestData.Valid
     public static final String MESSAGE_USAGE = COMMAND_WORD + ": Adds a contact. "
             + "Parameters: "
             + PREFIX_NAME + "NAME "

src/main/java/swe/context/model/util/AlphabeticalComparator.java

@@ -20,8 +20,8 @@ public int compare(Contact a, Contact b) {
             return n;
         }
 
-        // Only take true casing into account if names would otherwise be
-        // identical
+        // Only take true capitalization into account if names would otherwise
+        // be identical
         return aName.compareTo(bName);
     }
 }