From 4b633ec12b50925e80a1314c1c4af696cfe3d99b Mon Sep 17 00:00:00 2001 From: Titus Chew <39845485+tituschewxj@users.noreply.github.com> Date: Sun, 7 Apr 2024 14:18:27 +0800 Subject: [PATCH 1/4] Improve formatting of DG --- docs/DeveloperGuide.md | 532 +++++++++++++++++++++--------- docs/_markbind/layouts/default.md | 4 +- docs/_markbind/variables.md | 10 + 3 files changed, 397 insertions(+), 149 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index 9bacfd5279b..8539b3cfdea 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -7,52 +7,61 @@ # TAPro Developer Guide - +Table of Contents --------------------------------------------------------------------------------------------------------------------- +{{ newPage }} ## **Acknowledgements** * Trie implementation is reused from [eugenp's tutorials](https://github.com/eugenp/tutorials) with minor modifications. + _{ list here sources of all reused/adapted ideas, code, documentation, and third-party libraries -- include links to the original source as well }_ --------------------------------------------------------------------------------------------------------------------- +{{ newPage }} ## **Setting up, getting started** Refer to the guide [_Setting up and getting started_](SettingUp.md). --------------------------------------------------------------------------------------------------------------------- +{{ newPage }} ## **Design** +This section describes the design of various components of TAPro. + +
+ ### Architecture -The ***Architecture Diagram*** given above explains the high-level design of the App. +The ***Architecture Diagram*** given above explains the high-level design of TAPro. Given below is a quick overview of main components and how they interact with each other. -**Main components of the architecture** +
-**`Main`** (consisting of classes [`Main`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/java/seedu/address/Main.java) and [`MainApp`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/MainApp.java)) is in charge of the app launch and shut down. +#### Main components of the architecture + +**`Main`** (consisting of classes [`Main`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/java/seedu/address/Main.java) and [`MainApp`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/java/seedu/address/MainApp.java)) is in charge of the app launch and shut down. * At app launch, it initializes the other components in the correct sequence, and connects them up with each other. * At shut down, it shuts down the other components and invokes cleanup methods where necessary. -The bulk of the app's work is done by the following four components: +The bulk of TAPro's work is done by the following four components: -* [**`UI`**](#ui-component): The UI of the App. +* [**`UI`**](#ui-component): The UI of TAPro. * [**`Logic`**](#logic-component): The command and autocomplete executor. -* [**`Model`**](#model-component): Holds the data of the App in memory. +* [**`Model`**](#model-component): Holds the data of TAPro in memory. * [**`Storage`**](#storage-component): Reads data from, and writes data to, the hard disk. [**`Commons`**](#common-classes) represents a collection of classes used by multiple other components. -**How the architecture components interact with each other** +
+ +#### How the architecture components interact with each other The *Sequence Diagram* below shows how the components interact with each other for the scenario where the user -issues the command `delstu e1234567`. +issues the command `delstu nn/E1234567`. @@ -61,12 +70,26 @@ Each of the four main components (also shown in the diagram above), * defines its *API* in an `interface` with the same name as the Component. * implements its functionality using a concrete `{Component Name}Manager` class (which follows the corresponding API `interface` mentioned in the previous point. -For example, the `Logic` component defines its API in the `Logic.java` interface and implements its functionality using the `LogicManager.java` class which follows the `Logic` interface. Other components interact with a given component through its interface rather than the concrete class (reason: to prevent outside component's being coupled to the implementation of a component), as illustrated in the (partial) class diagram below. + + +**#g#Example:##** + +The `Logic` component defines its API in the `Logic.java` interface and implements its functionality using the `LogicManager.java` class which follows the `Logic` interface. + +Other components interact with a given component through its interface rather than the concrete class, as illustrated in the (partial) class diagram below. + + +Reason: To prevent outside component's being coupled to the implementation of a component. + + + The sections below give more details of each component. +{{ newPage }} + ### UI component The **API** of this component is specified in [`Ui.java`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/java/seedu/address/ui/Ui.java) @@ -75,15 +98,17 @@ The **API** of this component is specified in [`Ui.java`](https://github.com/AY2 The UI consists of a `MainWindow` that is made up of parts e.g.`CommandBox`, `ResultDisplay`, `PersonListPanel`, `StatusBarFooter` etc. All these, including the `MainWindow`, inherit from the abstract `UiPart` class which captures the commonalities between classes that represent parts of the visible GUI. -The `UI` component uses the JavaFx UI framework. The layout of these UI parts are defined in matching `.fxml` files that are in the `src/main/resources/view` folder. For example, the layout of the [`MainWindow`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/java/seedu/address/ui/MainWindow.java) is specified in [`MainWindow.fxml`](https://github.com/se-edu/addressbook-level3/tree/master/src/main/resources/view/MainWindow.fxml) +The `UI` component uses the JavaFx UI framework. The layout of these UI parts are defined in matching `.fxml` files that are in the `src/main/resources/view` folder. For example, the layout of the [`MainWindow`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/java/seedu/address/ui/MainWindow.java) is specified in [`MainWindow.fxml`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/resources/view/MainWindow.fxml) -The `UI` component, +**The `UI` component,** * executes user commands using the `Logic` component. * listens for changes to `Model` data so that the UI can be updated with the modified data. * keeps a reference to the `Logic` component, because the `UI` relies on the `Logic` to execute commands. * depends on some classes in the `Model` component, as it displays `Person` object residing in the `Model`. +{{ newPage }} + ### Logic component **API** : [`Logic.java`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/java/seedu/address/logic/Logic.java) @@ -98,12 +123,12 @@ call as an example. - + **Note:** The lifeline for `DeleteCommandParser` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline continues till the end of diagram. -How command execution works in `Logic` component: +**How command execution works in `Logic` component:** 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. 1. This results in a `Command` object (more precisely, an object of one of its subclasses e.g., `DeleteCommand`) which is executed by the `LogicManager`. @@ -111,7 +136,9 @@ How command execution works in `Logic` component: Note that although this is shown as a single step in the diagram above (for simplicity), in the code it can take several interactions (between the command object and the `Model`) to achieve. 1. The result of the command execution is encapsulated as a `CommandResult` object which is returned back from `Logic`. -How autocomplete execution works in `Logic` component: +
+ +**How autocomplete execution works in `Logic` component:** 1. When `Logic` is called upon to autocomplete an input string, it is passed to an `AddressBookParser` object which in turn matches the input and return the corresponding autocomplete object (e.g. `AutoCompleteCommand`). 1. This results in a `AutoComplete` object (more precisely, an object of one of its subclasses e.g., `AutoCompleteCommand`) which is executed by the `LogicManager`. @@ -120,62 +147,87 @@ How autocomplete execution works in `Logic` component: Here are the other classes in `Logic` (omitted from the class diagram above) that are used for parsing a user command: - +

-How the parsing works: +**How the parsing works:** * When called upon to parse a user command, the `AddressBookParser` class creates an `XYZCommandParser` (`XYZ` is a placeholder for the specific command name e.g., `AddCommandParser`) which uses the other classes shown above to parse the user command and create a `XYZCommand` object (e.g., `AddCommand`) which the `AddressBookParser` returns back as a `Command` object. * All `XYZCommandParser` classes (e.g., `AddCommandParser`, `DeleteCommandParser`, ...) inherit from the `Parser` interface so that they can be treated similarly where possible e.g, during testing. -* When called upon to parse an autocomplete input, the `AddressBookParser` class checks whether the input contains arguments. If it does not contain arguments, it creates an `AutoCompleteCommand` object which autocompletes Commands. Otherwise, it checks for the last argument in the user input and creates the matching `AutoComplete` object if it exists (e.g. `arbitrary_command arg_a/arbitrary_arg` lead to the AutoCompleteArgA object, if it exists). Otherwise, a default `AutoComplete` object that always return an empty string is returned. +* When called upon to parse an autocomplete input, the `AddressBookParser` class checks whether the input contains arguments. If it does not contain arguments, it creates an `AutoCompleteCommand` object which autocompletes Commands. Otherwise, it checks for the last argument in the user input and creates the matching `AutoComplete` object if it exists (e.g. `arbitrary_command arg_a/arbitrary_arg` lead to the `AutoCompleteArgA` object, if it exists). Otherwise, a default `AutoComplete` object that always return an empty string is returned. + +--- +
+
### Model component **API** : [`Model.java`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/java/seedu/address/model/Model.java) - - - -The `Model` component, +

+**The `Model` component,** * stores the contact book data i.e., all `Person` objects (which are contained in a `UniquePersonList` object). * stores the currently 'selected' `Person` objects (e.g., results of a search query) as a separate _filtered_ list which is exposed to outsiders as an unmodifiable `ObservableList` that can be 'observed' e.g. the UI can be bound to this list so that the UI automatically updates when the data in the list change. * stores a `UserPref` object that represents the user’s preferences. This is exposed to the outside as a `ReadOnlyUserPref` objects. * does not depend on any of the other three components (as the `Model` represents data entities of the domain, they should make sense on their own without depending on other components) - + -**Note:** An alternative (arguably, a more OOP) model is given below. It has a `Tag` list in the `AddressBook`, which `Person` references. This allows `AddressBook` to only require one `Tag` object per unique tag, instead of each `Person` needing their own `Tag` objects.
+**An alternative model:** + +An alternative (arguably, a more OOP) model is given below. It has a `Tag` list in the `AddressBook`, which `Person` references. This allows `AddressBook` to only require one `Tag` object per unique tag, instead of each `Person` needing their own `Tag` objects.
 +{{ newPage }} ### Storage component **API** : [`Storage.java`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/java/seedu/address/storage/Storage.java) - +

-The `Storage` component, +**The `Storage` component,** * can save both contact book data and user preference data in JSON format, and read them back into corresponding objects. * inherits from both `AddressBookStorage` and `UserPrefStorage`, which means it can be treated as either one (if only the functionality of only one is needed). * depends on some classes in the `Model` component (because the `Storage` component's job is to save/retrieve objects that belong to the `Model`) +{{ newPage }} + ### Common classes Classes used by multiple components are in the `seedu.addressbook.commons` package. +
+ #### Trie -The `Trie` class is a data structure that allows for efficient prefix matching of strings. It is used in the `AutoComplete` feature to suggest completions for user input.
+The `Trie` class is a data structure that allows for efficient prefix matching of strings. It is used in the `AutoComplete` feature to suggest completions for user input. + We added the ability to search for the first word that matches a given prefix. This is useful for the autocomplete feature, where we want to suggest the first word that matches the prefix. --------------------------------------------------------------------------------------------------------------------- +{{ newPage }} ## **Implementation** This section describes some noteworthy details on how certain features are implemented. -### \[Proposed\] Undo/redo feature +--- +
+ +### Autocomplete Feature + +**TODO** + +{{ newPage }} + +### Command History Retrieval + +**TODO** + +{{ newPage }} + +### \[Proposed\] Undo/Redo Feature #### Proposed Implementation @@ -189,11 +241,11 @@ These operations are exposed in the `Model` interface as `Model#commitAddressBoo Given below is an example usage scenario and how the undo/redo mechanism behaves at each step. -Step 1. The user launches the application for the first time. The `VersionedAddressBook` will be initialized with the initial contact book state, and the `currentStatePointer` pointing to that single contact book state. +**Step 1.** The user launches the application for the first time. The `VersionedAddressBook` will be initialized with the initial contact book state, and the `currentStatePointer` pointing to that single contact book state. - +

-Step 2. The user executes `delstu e1234567` command to delete student with nusnet ID as e1234567 from the contact book. +**Step 2.** The user executes `delstu e1234567` command to delete student with nusnet ID as e1234567 from the contact book. The `delstu` command calls @@ -201,29 +253,28 @@ calls executes to be saved in the `addressBookStateList`, and the `currentStatePointer` is shifted to the newly inserted contact book state. - +

-Step 3. The user executes `add n/David …​` to add a new person. The `add` command also calls `Model#commitAddressBook()`, causing another modified contact book state to be saved into the `addressBookStateList`. +**Step 3.** The user executes `add n/David …​` to add a new person. The `add` command also calls `Model#commitAddressBook()`, causing another modified contact book state to be saved into the `addressBookStateList`. - + **Note:** If a command fails its execution, it will not call `Model#commitAddressBook()`, so the contact book state will not be saved into the `addressBookStateList`. - - -Step 4. The user now decides that adding the person was a mistake, and decides to undo that action by executing the `undo` command. The `undo` command will call `Model#undoAddressBook()`, which will shift the `currentStatePointer` once to the left, pointing it to the previous contact book state, and restores the contact book to that state. +

- +**Step 4.** The user now decides that adding the person was a mistake, and decides to undo that action by executing the `undo` command. The `undo` command will call `Model#undoAddressBook()`, which will shift the `currentStatePointer` once to the left, pointing it to the previous contact book state, and restores the contact book to that state. -Step 5. The user wants to set the course name. He enters the command `setcrs CS2103T`, causing the course name to appear on the main window's title. +

+**Step 5.** The user wants to set the course name. He enters the command `setcrs CS2103T`, causing the course name to appear on the main window's title. - + -**Note:** If the `currentStatePointer` is at index 0, pointing to the initial AddressBook state, then there are no previous AddressBook states to restore. The `undo` command uses `Model#canUndoAddressBook()` to check if this is the case. If so, it will return an error to the user rather +**Note:** If the `currentStatePointer` is at index 0, pointing to the initial `AddressBook` state, then there are no previous `AddressBook` states to restore. The `undo` command uses `Model#canUndoAddressBook()` to check if this is the case. If so, it will return an error to the user rather than attempting to perform the undo. @@ -232,7 +283,7 @@ The following sequence diagram shows how an undo operation goes through the `Log - + **Note:** The lifeline for `UndoCommand` should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram. @@ -244,23 +295,23 @@ Similarly, how an undo operation goes through the `Model` component is shown bel The `redo` command does the opposite — it calls `Model#redoAddressBook()`, which shifts the `currentStatePointer` once to the right, pointing to the previously undone state, and restores the contact book to that state. - + -**Note:** If the `currentStatePointer` is at index `addressBookStateList.size() - 1`, pointing to the latest contact book state, then there are no undone AddressBook states to restore. The `redo` command uses `Model#canRedoAddressBook()` to check if this is the case. If so, it will return an error to the user rather than attempting to perform the redo. +**Note:** If the `currentStatePointer` is at index `addressBookStateList.size() - 1`, pointing to the latest contact book state, then there are no undone `AddressBook` states to restore. The `redo` command uses `Model#canRedoAddressBook()` to check if this is the case. If so, it will return an error to the user rather than attempting to perform the redo. - +

-Step 5. The user then decides to execute the command `list`. Commands that do not modify the contact book, such as `list`, will usually not call `Model#commitAddressBook()`, `Model#undoAddressBook()` or `Model#redoAddressBook()`. Thus, the `addressBookStateList` remains unchanged. +**Step 6.** The user then decides to execute the command `list`. Commands that do not modify the contact book, such as `list`, will usually not call `Model#commitAddressBook()`, `Model#undoAddressBook()` or `Model#redoAddressBook()`. Thus, the `addressBookStateList` remains unchanged. - +

-Step 6. The user executes `clear`, which calls `Model#commitAddressBook()`. Since the `currentStatePointer` is not pointing at the end of the `addressBookStateList`, all contact book states after the `currentStatePointer` will be purged. Reason: It no longer makes sense to redo the `add n/David …​` command. This is the behavior that most modern desktop applications follow. +**Step 7.** The user executes `clear`, which calls `Model#commitAddressBook()`. Since the `currentStatePointer` is not pointing at the end of the `addressBookStateList`, all contact book states after the `currentStatePointer` will be purged. Reason: It no longer makes sense to redo the `add n/David …​` command. This is the behavior that most modern desktop applications follow. The following activity diagram summarizes what happens when a user executes a new command: - +

#### Design considerations: @@ -277,12 +328,14 @@ The following activity diagram summarizes what happens when a user executes a ne _{more aspects and alternatives to be added}_ +{{ newPage }} + ### \[Proposed\] Data archiving _{Explain here how the data archiving feature will be implemented}_ --------------------------------------------------------------------------------------------------------------------- +{{ newPage }} ## **Documentation, logging, testing, configuration, dev-ops** @@ -291,125 +344,180 @@ _{Explain here how the data archiving feature will be implemented}_ * [Logging guide](Logging.md) * [Configuration guide](Configuration.md) * [DevOps guide](DevOps.md) - --------------------------------------------------------------------------------------------------------------------- + +--- +
+
## **Appendix: Requirements** +
+ ### Product scope **Target user profile**: -* Teaching Assistant for a Computer Science module in NUS -* tech savvy -* prefer desktop apps over other types -* can type fast -* prefers typing to mouse interactions -* is reasonably comfortable using CLI apps +* Teaching Assistant for a Computer Science module in NUS +* Tech savvy +* Prefer desktop apps over other types +* Can type fast +* Prefers typing to mouse interactions +* Is reasonably comfortable using CLI apps -**Value proposition**: All in one Address book managing student’s progress in the course, by means of participation, grades, and other course specific attributes of an NUS CS class. Can quickly find information, filter and sort with keyboard shortcuts. +**Value proposition**: All in one contact book managing student’s progress in the course, by means of participation, grades, and other course specific attributes of an NUS CS class. Can quickly find information, filter and sort with keyboard shortcuts. +{{ newPage }} ### User stories -Priorities: High (must have) - `* * *`, Medium (nice to have) - `* *`, Low (unlikely to have) - `*` + + +**Priorities:** +* #g#High:## (must have) - {{ threeStars }} +* Medium (nice to have) - {{ twoStars }} +* #r#Low:## (unlikely to have) - {{ oneStar }} + -| Priority | As a …​ | I want to …​ | So that I can…​ | -|----------|---------|--------------|-----------------| -| `* * *` | TA | name/rename the CS course that I am tutoring this semester | keep track of the module I am teaching | -| `* * *` | TA | add a student to the CS course that I am tutoring that semester to my class | keep track of him or her | -| `* * *` | TA | view all students from my class | view details about all of them | -| `* * *` | TA | mark attendance for a student in my class | keep track of who's present | -| `* * *` | TA | unmark attendance for a student in my class | keep track of who is absent | -| `* * *` | TA | delete a student | remove a student if he or she leaves the class | -| `* * *` | TA | know all the commands of the contact book | use it effectively | +[//]: # (  is added to force the header row into one line) +| Priority | As a … | I want to … | So that I can… | +|------------------|----------------------------------------------------|-----------------------------------------------------------------------------|------------------------------------------------| +| {{ threeStars }} | TA         | name/rename the CS course that I am tutoring this semester | keep track of the module I am teaching | +| {{ threeStars }} | TA | add a student to the CS course that I am tutoring that semester to my class | keep track of him or her | +| {{ threeStars }} | TA | view all students from my class | view details about all of them | +| {{ threeStars }} | TA | mark attendance for a student in my class | keep track of who's present | +| {{ threeStars }} | TA | unmark attendance for a student in my class | keep track of who is absent | +| {{ threeStars }} | TA | delete a student | remove a student if he or she leaves the class | +| {{ threeStars }} | TA | know all the commands of the contact book | use it effectively | + +**TODO: Add more user stories that are applicable** *{More to be added}* +{{ newPage }} + ### Use cases -(For all use cases below, the **System** is the `TA Pro` and the **Actor** is the `user`, unless specified otherwise) + -**Use case: Delete a student** +For all use cases below, the **System** is the `TAPro` and the **Actor** is the `user`, unless specified otherwise. + +
-**MSS** + -1. User requests to delete a specific student based on NUSNet ID. +**Use case: Add a Student** + +MSS + +1. User requests to add a student, providing the name and NUSNet ID as compulsory information, with the phone number being optional. Use case ends. -Extensions + -* 1a. No such student exists. + - * 1a1. AddressBook shows an error message. - - * Use case ends. +**TODO: Use case: Edit a Student** -**Use case: Add a student** + -**MSS** + -1. User requests to add a student, providing the name and NUSNet ID as compulsory information, with the phone number being optional. +**Use case: Delete a Student** + +MSS + +1. User requests to delete a specific student based on NUSNet ID. Use case ends. -**Use case: Name/Rename CS Course** +Extensions + +* 1a. No such student exists. + + * 1a1. TAPro shows an error message. + + * Use case ends. + + + + -**MSS** +**Use case: Name or Rename CS Course** + +MSS 1. User requests to name or rename a CS course by specifying the course name and the new name if applicable. Use case ends. + + + + **Use case: View All Students** -**MSS** +MSS 1. User requests to view a list of all students. - Use case ends. + Use case ends. + + + + + +**TODO: Use case: Find a Student by Name** + + + + **Use case: Mark Attendance** -**MSS** +MSS 1. User requests to mark attendance for a student by providing the student's NUSNet ID. Use case ends. -**Use case: Un-mark Attendance** + + + + +**Use case: Unmark Attendance** -**MSS** +MSS -1. User requests to un-mark attendance for a student by providing the student's NUSNet ID. +1. User requests to unmark attendance for a student by providing the student's NUSNet ID. Use case ends. -**Use case: Know Commands for the Address Book** + -**MSS** + -1. User requests to view the list of available commands for the AddressBook. +**TODO: Use case: Clear All Data** - Use case ends. + + -**Extensions** +**Use case: Know Available Commands in TAPro** -* 2a. The list is empty. +MSS - Use case ends. +1. User requests to view the list of available commands for TAPro. -* 3a. The given index is invalid. + Use case ends. - * 3a1. AddressBook shows an error message. + - Use case resumes at step 2. + -**Use case: Autocompletion of command inputs** +**Use case: Autocompletion of Command Inputs** -**MSS** +MSS 1. User focuses on the command box. @@ -418,7 +526,7 @@ Extensions 3. Autocompleted command is shown in the command box. Use case ends. -**Extensions** +Extensions * 3a. No autocompletion is available for the current input. @@ -426,11 +534,23 @@ Extensions * Use case ends. + + + + +**TODO: Use case: Retrieve a previous successful command input** + + + +**TODO: Add more use cases** + *{More to be added}* +{{ newPage }} + ### Non-Functional Requirements -1. Should work on any _mainstream OS_ as long as it has Java `11` installed. +1. Should work on any _mainstream OS_ as long as it has Java 11 installed. 2. System to load the main interface in under 1 second on standard educational institution hardware. 3. Application to be accessible on devices commonly used by the educational institution, such as desktop computers, laptops, and tablet. 4. System to ensure data integrity, with a goal of zero data loss over the academic year. @@ -439,36 +559,81 @@ Extensions *{More to be added}* +{{ newPage }} + ### Glossary -* **Mainstream OS**: Windows, Linux, Unix, MacOS -* **CS**: Computer Science -* **NUS**: National University of Singapore -* **TA**: Teaching Assistant -* **NUSNet ID**: A unique identifier for each student in NUS + + +**TAPro**: The name of our product + + + + +**Mainstream OS**: Windows, Linux, Unix, MacOS + + + + +**CS**: Computer Science + + + + +**NUS**: National University of Singapore + + + + +**TA**: Teaching Assistant + + + + +**NUSNet ID**: A unique identifier for each student in NUS + + + + +**API**: Application Programming Interface + --------------------------------------------------------------------------------------------------------------------- + + +**CLI**: Command Line Interface + + + + +**UI**: User Interface + + +--- +
+
## **Appendix: Instructions for manual testing** Given below are instructions to test the app manually. - + **Note:** These instructions only provide a starting point for testers to work on; testers are expected to do more *exploratory* testing. +
+ ### Launch and shutdown -1. Initial launch +1. **Initial launch** 1. Download the jar file and copy into an empty folder 1. Double-click the jar file Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum. -1. Saving window preferences +1. **Saving window preferences** 1. Resize the window to an optimum size. Move the window to a different location. Close the window. @@ -477,86 +642,157 @@ testers are expected to do more *exploratory* testing. 1. _{ more test cases …​ }_ +
+ ### Adding a student If TAPro does not have any student contacts, the following commands can be used to add some students. -1. Adding a student with NUSNet ID e0123456 +1. **Adding a student with NUSNet ID E0123456** - 1. Prerequisites: No student with NUSNet ID e0123456 in the contact book. + 1. Prerequisites: No student with NUSNet ID E0123456 in the contact book. - 1. Test case: `addstu n/John Doe p/98765432 e/johndoe@example.com nn/e0123456 a/311, Clementi Ave 2, #02-25 t/friends t/owesMoney` + 1. Test case: `addstu n/John Doe p/98765432 e/johndoe@example.com nn/E0123456 m/Computer Science, #02-25 t/friends t/owesMoney` - Expected: Student with NUSNet ID `e0123456` is added to the contact book. Details of the added contact + Expected: Student with NUSNet ID `E0123456` is added to the contact book. Details of the added contact shown in the status message. -1. Adding a student with NUSNet ID e0123457 +1. **Adding a student with NUSNet ID E0123457** - 1. Prerequisites: No student with NUSNet ID e0123457 in the contact book. + 1. Prerequisites: No student with NUSNet ID E0123457 in the contact book. - 1. Test case: `addstu n/Mary Jane p/91234911 e/janemary@example.com nn/e0123457 a/312, Clementi St 1, #03-25 t/friends t/owesTutorial2` + 1. Test case: `addstu n/Mary Jane p/91234911 e/janemary@example.com nn/E0123457 m/Computer Science t/friends t/owesTutorial2` - Expected: Student with NUSNet ID `e0123457` is added to the contact book. Details of the added contact + Expected: Student with NUSNet ID `E0123457` is added to the contact book. Details of the added contact shown in the status message. +
+ +### Editing a student + +**TODO** + +
+ ### Deleting a student -1. Deleting a student +1. **Deleting a student** 1. Prerequisites: Contact book contains at least one student with NUSNet ID e0123456. - 1. Test case: `delete e0123456`
- Expected: Student with NUSNet ID `e0123456` is deleted from the contact book. Details of the deleted contact + 1. Test case: `delstu nn/E0123456`
+ Expected: Student with NUSNet ID `E0123456` is deleted from the contact book. Details of the deleted contact shown in the status message. - 1. Other incorrect delete commands to try: `delete`, `delete x`, `...` (where x is not an NUSNet ID of a student - in TA Pro)
+ 1. Other incorrect delete commands to try: `delstu`, `delstu x`, `...` (where x is not an NUSNet ID of a student + in TAPro)
1. _{ more test cases …​ }_ +
+ +### Finding a student + +**TODO** + +
+ ### Marking a student's attendance -1. Marking attendance for a student +1. **Marking attendance for a student** 1. Prerequisites: Contact book contains at least one student with NUSNet ID e0123456. - 1. Test case: `mark nn/e0123456 wk/1`
- Expected: Student with NUSNet ID `e0123456` is marked as 'present' from the contact book, depicted on that student's card. + 1. Test case: `mark nn/E0123456 wk/1`
+ Expected: Student with NUSNet ID `E0123456` is marked as 'present' from the contact book, depicted on that student's card. Details of the marked contact shown in the status message. - 1. Other incorrect mark commands to try: `mark`, `mark x`, `mark nn/e0123456`, `mark wk/1`, `mark e0123456 1`, `...` (where x is not an NUSNet ID of a student - in TA Pro)
+ 1. Other incorrect mark commands to try: `mark`, `mark x`, `mark nn/E0123456`, `mark wk/1`, `mark E0123456 1`, `...` (where x is not an NUSNet ID of a student + in TAPro)
+
-### Saving data +### Unmarking a student's attendance -1. Dealing with missing/corrupted data files +**TODO** - 1. _{explain how to simulate a missing/corrupted file, and the expected behavior}_ +
-1. _{ more test cases …​ }_ +### Setting the course name -### Setting the course - -1. Setting a course +1. **Setting a course name** 1. Test case: `setcrs CS2103`
Enter setcrs followed by a whitespace, followed by a course code in the format `XXYYYYZ`, where `X` and `Z` can be any letter - in upper or lower case, `YYYY` can be any 4 digit number and `Z` is optional. + in upper or lower case, `YYYY` can be any 4-digit number and `Z` is optional. Expected: The main window's title is set as the course code provided --------------------------------------------------------------------------------------------------------------------- +
+ +### Autocompleting fields + +**TODO** + +
+ +### Retrieving previous successful commands + +**TODO** + +
+ +### Accessing help + +**TODO** + +
+ +### Clearing all data + +**TODO** + +
+ +### Saving data + +1. **Dealing with missing/corrupted data files** + + 1. _{explain how to simulate a missing/corrupted file, and the expected behavior}_ + +1. _{ more test cases …​ }_ + + +{{ newPage }} ## **Appendix: Design Decisions** -1. Why does `edit` command use `INDEX` as identifier instead fo `NUSNet ID`? - 1. For our users, using `edit nn/e0123456 nn/e1234567` is unintuitive. +1. Why does `edit` command use `INDEX` as identifier instead of `NUSNET`? + 1. For our users, using `edit nn/E0123456 nn/E1234567` is unintuitive to edit the NUSNet ID of a student. 1. `INDEX` is visually easier to reference and requires less effort to type. - 1. The alternative solution we considered was to disallow editing of `NUSNet ID`, but this would be a limitation on + 1. The alternative solution we considered was to disallow editing of `NUSNET`, but this would be a limitation on the user's freedom, or would necessitate that the user deletes the student and re-enter all the details again. - +
+ - **Note:** `delstu` command uses `NUSNet ID` as identifier because it requires more intentional effort and + **Note:** `delstu` command uses `NUSNET` as identifier because it requires more intentional effort and therefore ensures that the TA intends to perform this dangerous action. + +{{ newPage }} + +## **Appendix: Effort** + +**TODO** + +{{ newPage }} + +## **Appendix: Planned Enhancements** + + + +**Team size:** 5 + + + +**TODO: Add feature flaws here** diff --git a/docs/_markbind/layouts/default.md b/docs/_markbind/layouts/default.md index 6c6382ce7b0..55c737ddf50 100644 --- a/docs/_markbind/layouts/default.md +++ b/docs/_markbind/layouts/default.md @@ -9,7 +9,7 @@
  • User Guide
  • Developer Guide
  • About Us
    • -
  • :fab-github: +
  • :fab-github:
  • @@ -41,6 +41,8 @@ * [Appendix: Requirements]({{ baseUrl }}/DeveloperGuide.html#appendix-requirements) * [Appendix: Instructions for manual testing]({{ baseUrl }}/DeveloperGuide.html#appendix-instructions-for-manual-testing) * [Appendix: Design Decisions]({{ baseUrl }}/DeveloperGuide.html#appendix-design-decisions) + * [Appendix: Effort]({{ baseUrl }}/DeveloperGuide.html#appendix-effort) + * [Appendix: Planned Enhancements]({{ baseUrl }}/DeveloperGuide.html#appendix-planned-enhancements) * [About Us]({{ baseUrl }}/AboutUs.html) diff --git a/docs/_markbind/variables.md b/docs/_markbind/variables.md index 89ae5318fa4..633712848be 100644 --- a/docs/_markbind/variables.md +++ b/docs/_markbind/variables.md @@ -2,3 +2,13 @@ To inject this HTML segment in your markbind files, use {{ example }} where you want to place it. More generally, surround the segment's id with double curly braces. + + + + + + +--- +
    +
    +     From 6dd948e5e0685043b44082661e55aff58dd27c8e Mon Sep 17 00:00:00 2001 From: Titus Chew <39845485+tituschewxj@users.noreply.github.com> Date: Mon, 8 Apr 2024 13:52:00 +0800 Subject: [PATCH 2/4] Update newPage Let's * Use newPage * Use nn/ * Use E for NUSNet --- docs/DeveloperGuide.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index 8539b3cfdea..ad1bfd57a9f 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -154,9 +154,7 @@ Here are the other classes in `Logic` (omitted from the class diagram above) tha * All `XYZCommandParser` classes (e.g., `AddCommandParser`, `DeleteCommandParser`, ...) inherit from the `Parser` interface so that they can be treated similarly where possible e.g, during testing. * When called upon to parse an autocomplete input, the `AddressBookParser` class checks whether the input contains arguments. If it does not contain arguments, it creates an `AutoCompleteCommand` object which autocompletes Commands. Otherwise, it checks for the last argument in the user input and creates the matching `AutoComplete` object if it exists (e.g. `arbitrary_command arg_a/arbitrary_arg` lead to the `AutoCompleteArgA` object, if it exists). Otherwise, a default `AutoComplete` object that always return an empty string is returned. ---- -
    -
    +{{ newPage }} ### Model component **API** : [`Model.java`](https://github.com/AY2324S2-CS2103T-F13-1/tp/tree/master/src/main/java/seedu/address/model/Model.java) @@ -245,11 +243,11 @@ Given below is an example usage scenario and how the undo/redo mechanism behaves

    -**Step 2.** The user executes `delstu e1234567` command to delete student with nusnet ID as e1234567 from the contact book. +**Step 2.** The user executes `delstu nn/E1234567` command to delete student with NUSNet ID as E1234567 from the contact book. The `delstu` command calls -`Model#commitAddressBook()`, causing the modified state of the contact book after the `delstu e1234567` command +`Model#commitAddressBook()`, causing the modified state of the contact book after the `delstu nn/E1234567` command executes to be saved in the `addressBookStateList`, and the `currentStatePointer` is shifted to the newly inserted contact book state. @@ -344,10 +342,8 @@ _{Explain here how the data archiving feature will be implemented}_ * [Logging guide](Logging.md) * [Configuration guide](Configuration.md) * [DevOps guide](DevOps.md) - ---- -
    -
    + +{{ newPage }} ## **Appendix: Requirements** @@ -608,9 +604,7 @@ For all use cases below, the **System** is the `TAPro` and the **Actor** is the **UI**: User Interface ---- -
    -
    +{{ newPage }} ## **Appendix: Instructions for manual testing** @@ -701,7 +695,7 @@ students. 1. **Marking attendance for a student** - 1. Prerequisites: Contact book contains at least one student with NUSNet ID e0123456. + 1. Prerequisites: Contact book contains at least one student with NUSNet ID E0123456. 1. Test case: `mark nn/E0123456 wk/1`
    Expected: Student with NUSNet ID `E0123456` is marked as 'present' from the contact book, depicted on that student's card. From 699dcb4e0021bda5bd2b4492f03365ee6f79e14a Mon Sep 17 00:00:00 2001 From: Titus Chew <39845485+tituschewxj@users.noreply.github.com> Date: Mon, 8 Apr 2024 15:55:40 +0800 Subject: [PATCH 3/4] Update DG Let's * Use E for NUSNet * Use nn/ * macro for definitions * Refactor instructions for manual testing --- docs/DeveloperGuide.md | 230 +++++++++++++++++++++++--------------- docs/_markbind/_macros.nj | 14 +++ 2 files changed, 153 insertions(+), 91 deletions(-) create mode 100644 docs/_markbind/_macros.nj diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index ad1bfd57a9f..5d8907c757b 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -3,6 +3,7 @@ title: "Developer Guide" pageNav: 3 --- +{% import "_markbind/_macros.nj" as macros %} # TAPro Developer Guide @@ -117,8 +118,7 @@ Here's a (partial) class diagram of the `Logic` component: -The sequence diagram below illustrates the interactions within the `Logic` component, taking `execute("delstu -e1234567")` API +The sequence diagram below illustrates the interactions within the `Logic` component, taking `execute("delstu nn/E1234567")` API call as an example. @@ -374,16 +374,18 @@ _{Explain here how the data archiving feature will be implemented}_ -[//]: # (  is added to force the header row into one line) -| Priority | As a … | I want to … | So that I can… | -|------------------|----------------------------------------------------|-----------------------------------------------------------------------------|------------------------------------------------| -| {{ threeStars }} | TA         | name/rename the CS course that I am tutoring this semester | keep track of the module I am teaching | -| {{ threeStars }} | TA | add a student to the CS course that I am tutoring that semester to my class | keep track of him or her | -| {{ threeStars }} | TA | view all students from my class | view details about all of them | -| {{ threeStars }} | TA | mark attendance for a student in my class | keep track of who's present | -| {{ threeStars }} | TA | unmark attendance for a student in my class | keep track of who is absent | -| {{ threeStars }} | TA | delete a student | remove a student if he or she leaves the class | -| {{ threeStars }} | TA | know all the commands of the contact book | use it effectively | +[//]: # (whitespace is added to force the header row into one line) +{% set whitespace = '        ' %} + +| Priority | As a … | I want to … | So that I can… | +|------------------|---------------------|-----------------------------------------------------------------------------|------------------------------------------------| +| {{ threeStars }} | TA {{ whitespace }} | name/rename the CS course that I am tutoring this semester | keep track of the module I am teaching | +| {{ threeStars }} | TA | add a student to the CS course that I am tutoring that semester to my class | keep track of him or her | +| {{ threeStars }} | TA | view all students from my class | view details about all of them | +| {{ threeStars }} | TA | mark attendance for a student in my class | keep track of who's present | +| {{ threeStars }} | TA | unmark attendance for a student in my class | keep track of who is absent | +| {{ threeStars }} | TA | delete a student | remove a student if he or she leaves the class | +| {{ threeStars }} | TA | know all the commands of TAPro | use it effectively | **TODO: Add more user stories that are applicable** @@ -395,7 +397,7 @@ _{Explain here how the data archiving feature will be implemented}_ -For all use cases below, the **System** is the `TAPro` and the **Actor** is the `user`, unless specified otherwise. +For all use cases below, the **System** is TAPro and the **Actor** is the user, unless specified otherwise.
    @@ -559,82 +561,76 @@ For all use cases below, the **System** is the `TAPro` and the **Actor** is the ### Glossary - - -**TAPro**: The name of our product - +{{ macros.definitionBox('TAPro', 'The name of our product') }} +{{ macros.definitionBox('Mainstream OS', 'Windows, Linux, Unix, MacOS') }} +{{ macros.definitionBox('CS', 'Computer Science') }} +{{ macros.definitionBox('NUS', 'National University of Singapore') }} +{{ macros.definitionBox('TA', 'Teaching Assistant') }} +{{ macros.definitionBox('NUSNet ID', 'A unique identifier for each student in NUS') }} +{{ macros.definitionBox('API', 'Application Programming Interface') }} +{{ macros.definitionBox('CLI', 'Command Line Interface') }} +{{ macros.definitionBox('UI', 'User Interface') }} +{{ macros.definitionBox('GUI', 'Graphical User Interface') }} - - -**Mainstream OS**: Windows, Linux, Unix, MacOS - +{{ newPage }} - +## **Appendix: Instructions for manual testing** -**CS**: Computer Science - +Given below are instructions to test the app manually. - + -**NUS**: National University of Singapore +**Prerequisites:** For all features to test below, TAPro is already downloaded, only single instance of TAPro is already opened, and Java 11 or above is installed, unless specified otherwise. - - -**TA**: Teaching Assistant - + - +**Note:** These instructions only provide a starting point for testers to work on; +testers are expected to do more *exploratory* testing. -**NUSNet ID**: A unique identifier for each student in NUS - - -**API**: Application Programming Interface - +
    - +### Launch and shutdown -**CLI**: Command Line Interface - +1. **Initial launch** - + -**UI**: User Interface +1. Prerequisites: TAPro is not downloaded, and an Internet connection is present. -{{ newPage }} + -## **Appendix: Instructions for manual testing** +2. Download the latest TAPro jar file from [here](https://github.com/AY2324S2-CS2103T-F13-1/tp/releases) and move it into an empty folder. -Given below are instructions to test the app manually. +3. Ensure that the jar file is still named as `TAPro.jar` after moving. - +4. Open a command terminal, and `cd` into that folder. -**Note:** These instructions only provide a starting point for testers to work on; -testers are expected to do more *exploratory* testing. +5. Run `java -jar TAPro.jar`. +Expected: TAPro launches and shows the GUI with a set of sample student contacts. The window size may not be optimal. -
    +2. **Saving window preferences** -### Launch and shutdown - -1. **Initial launch** + - 1. Download the jar file and copy into an empty folder +1. Prerequisites: No prerequisites. + - 1. Double-click the jar file Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum. + -1. **Saving window preferences** +2. Resize the window to an optimum size. Move the window to a different location. Close the window. - 1. Resize the window to an optimum size. Move the window to a different location. Close the window. +3. Re-launch the app by double-clicking the jar file.
    - 1. Re-launch the app by double-clicking the jar file.
    - Expected: The most recent window size and location is retained. +Expected: The most recent window size and location is retained. +     -1. _{ more test cases …​ }_ +3. _{ more test cases …​ }_
    @@ -643,22 +639,34 @@ If TAPro does not have any student contacts, the following commands can be used students. 1. **Adding a student with NUSNet ID E0123456** - - 1. Prerequisites: No student with NUSNet ID E0123456 in the contact book. - - 1. Test case: `addstu n/John Doe p/98765432 e/johndoe@example.com nn/E0123456 m/Computer Science, #02-25 t/friends t/owesMoney` - Expected: Student with NUSNet ID `E0123456` is added to the contact book. Details of the added contact - shown in the status message. + + +1. Prerequisites: No student with NUSNet ID E0123456 in TAPro. + + + + +2. Test case: `addstu n/John Doe p/98765432 e/johndoe@example.com nn/E0123456 m/Computer Science, #02-25 t/friends t/owesMoney` + +Expected: Student with NUSNet ID `E0123456` is added into TAPro. Details of the added student is +shown in the status message. + 1. **Adding a student with NUSNet ID E0123457** - 1. Prerequisites: No student with NUSNet ID E0123457 in the contact book. - - 1. Test case: `addstu n/Mary Jane p/91234911 e/janemary@example.com nn/E0123457 m/Computer Science t/friends t/owesTutorial2` + - Expected: Student with NUSNet ID `E0123457` is added to the contact book. Details of the added contact - shown in the status message. +1. Prerequisites: Prerequisites: No student with NUSNet ID E0123457 in TAPro. + + + + +2. Test case: `addstu n/Mary Jane p/91234911 e/janemary@example.com nn/E0123457 m/Biology t/friends t/owesTutorial2` + +Expected: Student with NUSNet ID `E0123457` is added into TAPro. Details of the added student is +shown in the status message. +
    @@ -672,16 +680,30 @@ students. 1. **Deleting a student** - 1. Prerequisites: Contact book contains at least one student with NUSNet ID e0123456. + - 1. Test case: `delstu nn/E0123456`
    - Expected: Student with NUSNet ID `E0123456` is deleted from the contact book. Details of the deleted contact - shown in the status message. - - 1. Other incorrect delete commands to try: `delstu`, `delstu x`, `...` (where x is not an NUSNet ID of a student - in TAPro)
    +1. Prerequisites: TAPro contains at least one student with NUSNet ID E0123456, and no student with NUSNet ID E6543210. +     -1. _{ more test cases …​ }_ + + +2. Test case: `delstu nn/E0123456` + +Expected: The student with NUSNet ID `E0123456` is deleted from TAPro. Details of the deleted student +shown in the status message. + + + + +3. Other incorrect `delstu` commands to try: + +#r#Examples:## +* `delstu`: Missing parameter and prefix. +* `delstu nn/E6543210`: No student with this NUSNet ID. +* `delstu E0123456`: Missing prefix for the NUSNet ID parameter. + + +2. _{ more test cases …​ }_
    @@ -695,14 +717,27 @@ students. 1. **Marking attendance for a student** - 1. Prerequisites: Contact book contains at least one student with NUSNet ID E0123456. + - 1. Test case: `mark nn/E0123456 wk/1`
    - Expected: Student with NUSNet ID `E0123456` is marked as 'present' from the contact book, depicted on that student's card. - Details of the marked contact shown in the status message. - - 1. Other incorrect mark commands to try: `mark`, `mark x`, `mark nn/E0123456`, `mark wk/1`, `mark E0123456 1`, `...` (where x is not an NUSNet ID of a student - in TAPro)
    +1. Prerequisites: TAPro contains one student with NUSNet ID E0123456, and no student with NUSNet ID E6543210. +     + + + +2. Test case: `mark nn/E0123456 wk/1` + +Expected: Student with NUSNet ID `E0123456` is marked as present for week 1 in TAPro, depicted on that student's card in the panel. +Details of the marked student is shown in the status message. + + + + +3. Examples of incorrect `mark` commands to try: +* `mark`: Missing NUSNet ID and week number parameters. +* `mark nn/E6543210 wk/1`: No student with this NUSNet ID. +* `mark wk/1`: Missing the NUSNet ID parameter. +* `mark E0123456 1`: Missing prefix for the NUSNet ID and week number parameters. +
    @@ -714,12 +749,25 @@ students. ### Setting the course name -1. **Setting a course name** - - 1. Test case: `setcrs CS2103`
    - Enter setcrs followed by a whitespace, followed by a course code in the format `XXYYYYZ`, where `X` and `Z` can be any letter - in upper or lower case, `YYYY` can be any 4-digit number and `Z` is optional. - Expected: The main window's title is set as the course code provided +1. **Setting a course name** + + + +1. Prerequisites: No prerequisites. + + + + +2. Test case: `setcrs CS2103` + + + +Enter `setcrs` followed by a whitespace, followed by a course code in the format `XXYYYYZ`, where `X` and `Z` can be any letter +in upper or lower case, `YYYY` can be any 4-digit number and `Z` is optional. + + +Expected: TAPro's main window's title contains the course code `CS2103` provided. +
    @@ -760,7 +808,7 @@ students. ## **Appendix: Design Decisions** -1. Why does `edit` command use `INDEX` as identifier instead of `NUSNET`? +1. **Why does `edit` command use `INDEX` as identifier instead of `NUSNET`?** 1. For our users, using `edit nn/E0123456 nn/E1234567` is unintuitive to edit the NUSNet ID of a student. 1. `INDEX` is visually easier to reference and requires less effort to type. 1. The alternative solution we considered was to disallow editing of `NUSNET`, but this would be a limitation on diff --git a/docs/_markbind/_macros.nj b/docs/_markbind/_macros.nj new file mode 100644 index 00000000000..f73737ff964 --- /dev/null +++ b/docs/_markbind/_macros.nj @@ -0,0 +1,14 @@ +{# macro allows you to define reusable chunks of content. It is similar to a function in a programming language. #} +{# Macros are useful only when the the text to format is more than one line. #} +{# It takes more time to build the page with macros, but it ensures that things the formatting is more consistent. #} + + + +{# Define something inside a box #} +{% macro definitionBox(name, description) %} + + +**{{ name }}**: {{ description }} + + +{% endmacro %} From 8a1d93f1c6e02ca81714fcf141dbe279488437c8 Mon Sep 17 00:00:00 2001 From: Titus Chew <39845485+tituschewxj@users.noreply.github.com> Date: Mon, 8 Apr 2024 15:59:38 +0800 Subject: [PATCH 4/4] Fix extra example label --- docs/DeveloperGuide.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/DeveloperGuide.md b/docs/DeveloperGuide.md index 5d8907c757b..dda421e186f 100644 --- a/docs/DeveloperGuide.md +++ b/docs/DeveloperGuide.md @@ -696,8 +696,6 @@ shown in the status message. 3. Other incorrect `delstu` commands to try: - -#r#Examples:## * `delstu`: Missing parameter and prefix. * `delstu nn/E6543210`: No student with this NUSNet ID. * `delstu E0123456`: Missing prefix for the NUSNet ID parameter.