diff --git a/README.adoc b/README.adoc index 36b20c6f8e16..318c5d23a4a8 100644 --- a/README.adoc +++ b/README.adoc @@ -4,8 +4,6 @@ ifdef::env-github,env-browser[:relfileprefix: docs/] https://travis-ci.org/CS2103-AY1819S1-T16-4/main[image:https://travis-ci.org/CS2103-AY1819S1-T16-4/main.svg?branch=master[Build Status]] https://ci.appveyor.com/project/rongjiecomputer/main[image:https://ci.appveyor.com/api/projects/status/bh9l24v9mrpvixel?svg=true[Build status]] https://coveralls.io/github/CS2103-AY1819S1-T16-4/main?branch=master[image:https://coveralls.io/repos/github/CS2103-AY1819S1-T16-4/main/badge.svg?branch=master[Coverage Status]] -https://www.codacy.com/app/damith/addressbook-level4?utm_source=github.com&utm_medium=referral&utm_content=se-edu/addressbook-level4&utm_campaign=Badge_Grade[image:https://api.codacy.com/project/badge/Grade/fc0b7775cf7f4fdeaf08776f3d8e364a[Codacy Badge]] -https://gitter.im/se-edu/Lobby[image:https://badges.gitter.im/se-edu/Lobby.svg[Gitter chat]] ifdef::env-github[] image::docs/images/Ui.png[width="750"] @@ -24,7 +22,7 @@ endif::[] * It allows a user to keep track of past modules, and list possible future modules based on the user’s academic requirements (for graduation, a minor etc). -* The target users for this product are Computer Science undergraduate students +* The target users for this product are Computer Science and Computer Engineering undergraduate students in the National University of Singapore (NUS). * What this product does is to simplify the module planning process that every NUS student has to go through. @@ -39,11 +37,11 @@ endif::[] 3. Choose some of those modules. 4. Start planning for the next semester. 5. Repeat (1) - (4) for any number of semesters. -6. Wishes to remove some modules +6. Wishes to remove some modules. 7. Some modules planned now have their pre-requisites unfulfilled. -8. Sighs in frustration -9. Repeat (8) -**** +8. Sighs in frustration. +9. Repeat (8). +---- So *tedious*. @@ -51,10 +49,10 @@ So *tedious*. **** 1. Input academic requirements. -2. Application lists possible modules to take based on academic comitments and module pre-requisites. +2. Application lists possible modules to take based on academic commitments and module prerequisites. 3. Choose some of those modules. 4. Repeat (1) - (3) for any number of semesters. -5. Wishes to remove some modules +5. Wishes to remove some modules. 6. Application removes modules which pre-requisites are not fulfilled and suggests new modules to take. **** @@ -62,10 +60,10 @@ Much better! == Site Map -* <> -* <> * <> * <> +* <> +* <> == Acknowledgements diff --git a/docs/DeveloperGuide.adoc b/docs/DeveloperGuide.adoc index 4ae2353fc1aa..3e701a68bb59 100644 --- a/docs/DeveloperGuide.adoc +++ b/docs/DeveloperGuide.adoc @@ -679,22 +679,27 @@ support years beyond the 4th. // end::goto[] +// tag::list[] === List feature ==== Current Implementation -The list mechanism is facilitated by `ModulePlanner`. `ModulePlanner` stores a list of all `Semester`s and each `Semester` stores a list `modulesTaken` containing modules that the user has taken or is planning to take. +The list mechanism displays either a list of modules that the user has added to a specified year or a list of all modules that the user has added to every year. + +This mechanism is facilitated by `ModulePlanner`. The `ModulePlanner` stores a list of all `Semester`-s and each `Semester` stores a list `modulesTaken` containing modules that the user has added to that `Semester`. It implements the following operation: * `ModulePlanner#getTakenModules()` -- Retrieves the list `takenModules`. * `ModulePlanner#listTakenModulesAll()` -- Updates `takenModules` to contain a list of modules retrieved from the list `modulesTaken` in every `Semester`. -* `ModulePlanner#listTakenModulesForYear(int year)` -- Updates `takenModules` to contain a list of modules retrieved from the list `modulesTaken` in the `Semester`s that belongs to the specified year. +* `ModulePlanner#listTakenModulesForYear(int year)` -- Updates `takenModules` to contain a list of modules retrieved from the list `modulesTaken` in the `Semester`-s that belong to the specified year. + +The operations are exposed in `Model` interface as `Model#getTakenModules()`, `Model#listTakenModulesAll()`, and `Model#listTakenModulesForYear(int year)`. -The operation is exposed in `Model` interface as `Model#getTakenModules()`, `Model#listTakenModulesAll()`, and `Model#listTakenModulesForYear(int year)`. +If a valid year is specified by the user, the `list` command will call `Model#listTakenModulesForYear(year)`, where `year` is the argument supplied by user. If no year is specified, the `list` command will call `Model#listTakenModulesAll()`. [NOTE] -A valid index should be an integer between 0 to 7 inclusive, where index 0 represents year 1 semester 1, index 1 represents year 1 semester 2, index 2 represents year 2 semester 1, and so on. +A valid year should be an integer between 1 to 4 inclusive. -Below is an example usage scenario and how the list mechanism works. +*Below is an example usage scenario and how the list mechanism works.* Step 1. User launches the application. `ModulePlanner` is initialised with 8 `Semester` objects in a list `semesters`. @@ -718,13 +723,14 @@ image::ListSequenceDiagram_2.png[width="800"] ==== Design Considerations -===== Aspect: How list of modules is retrieved for list command -* **Alternative 1 (current choice):** Updates list of modules whenever it is modified by a command (e.g. `add`) and immediately retrieves the list upon `list` command. +===== Aspect: How list of modules taken is retrieved for list command +* **Alternative 1 (current choice):** Updates list of modules taken whenever it is modified by a command (e.g. `add`) and immediately retrieves the list upon `list` command. ** Pros: Easy to implement. ** Cons: May have performance issue in terms of running time if commands that modify the list are called frequently. -* **Alternative 2:** Saves all commands that modify list of modules without applying it and updates the list based on the commands only when it is retrieved upon `list` command. +* **Alternative 2:** Saves all commands that modify list of modules taken without applying it and updates the list based on the commands only when it is retrieved upon `list` command. ** Pros: May be more effective in terms of running time because it only modifies the list when needed. -** Cons: Implementation will be more complicated as we have to store all commands that modify the list. +** Cons: Implementation will be more complicated as it required storing all commands that modify the list. +// end::list[] // tag::status[] === Status feature @@ -785,30 +791,37 @@ Below are the summary of pros and cons of the current implementation and the alt ** Cons: Much more tedious to implement // end::status[] + +// tag::suggest[] === Suggest feature ==== Current Implementation The suggest mechanism displays a list of modules available in the specified index to the user, where index represents the year and semester that the user is asking suggestions for. -It is supported by an internal list `availableModules` in `ModulePlanner`, which is regenerated after every successful execution of commands that modify `ModulePlanner` (`add`, `delete`, `clear`, etc.) and `suggest` command. -The list `availableModules` can be retrieved through `Model#getAvailableList()` using `suggest` command, which (`suggest` command) takes in one argument: a valid index that corresponds to a specific year and semester. + +This mechanism is supported by an internal list `availableModules` in `ModulePlanner`, which is regenerated after every successful execution of commands that modify `ModulePlanner` (`add`, `delete`, `clear`, etc.) and `suggest` command. +The list `availableModules` can be retrieved through `Model#getAvailableList()` using `suggest` command, which (`suggest` command) takes in two arguments: a valid year and a valid semester. [NOTE] -A valid index should be an integer between 0 to 7 inclusive, where index 0 represents year 1 semester 1, index 1 represents year 1 semester 2, index 2 represents year 2 semester 1, and so on. +==== +* A valid year should be an integer between 1 to 4 inclusive. +* A valid semester should be wither 1 or 2. +==== -Below is an example usage scenario and how the suggest mechanism works. +*Below is an example usage scenario and how the suggest mechanism works.* *Step 1.* User launches the application and `ModulePlanner` is initialized. -*Step 2.* User executes `suggest y/1 s/1`. The `suggest` command updates `availableModules` to a newly generated list of available modules for index 0 an stores index 0 as `availableIndex` in `ModulePlanner`. It then retrieves `availableModules` and displays it to user. +*Step 2.* User executes `suggest y/1 s/1`. The `suggest` command parser converts year 1 and semester 1 to index 0. +The `suggest` command updates `availableModules` to a newly generated list of available modules for index 0 and stores index 0 as `availableIndex` in `ModulePlanner`. It then retrieves `availableModules` and displays it to user. *Step 3.* User executes `add y/1 s/2 c/CS1010`. The `add` command performs adding a module and updates `availableModules` to a newly generated list of available modules for the stored index 0. The suggested modules list shows an updated list of available modules in year 1 semester 1 to the user. Only `suggest` command will change the index (year and semester) to be displayed by the suggested modules list, other commands will only show an updated list for the last index displayed by `suggest`. -*Step 4.* User executes `suggest y/1 s/2`. The `suggest` command updates `availableModules` to a newly generated list of available modules for index 1 an stores index 1 as `availableIndex` in `ModulePlanner`. It then retrieves `availableModules` and displays list of available modules in year 1 semester 2 to user. +*Step 4.* User executes `suggest y/1 s/2`. The `suggest` command parser converts year 1 and semester 2 to index 1. The `suggest` command updates `availableModules` to a newly generated list of available modules for index 1 and stores index 1 as `availableIndex` in `ModulePlanner`. It then retrieves `availableModules` and displays list of available modules in year 1 semester 2 to user. -Below is how the list of available modules is generated. +*Below is an explanation on how the list of available modules is generated.* -The method `ModulePlanner#generateAvailableModules(int index)` is called by `ModulePlanner#updateModulesAvailable()`, which sets the content of `availableModules` to be the list of modules returned by `generateAvailableModules(index)`, with `index` being the stored `availableIndex`. +The method `ModulePlanner#generateAvailableModules(int index)` is called by `ModulePlanner#updateModulesAvailable()`, which sets the content of `availableModules` to the list of modules returned by `generateAvailableModules(index)`, with `index` being the stored `availableIndex`. The implementation of `ModulePlanner#generateAvailableModules(int index)` is given below: [source,java] ---- @@ -835,11 +848,12 @@ The method `ModulePlanner#generateAvailableModules(int index)` retrieves all mod ** in a lexicographical order if user has specified a major other than *Computer Science* through `setup` command, or ** such that core modules for *Computer Science* major are put on top, followed by general education modules and unrestricted electives. -The availability checking is done by the following method. +The availability checking is done by the following method: [source,java] ---- -public static boolean isModuleAvailableToTake(List modulesTaken, List modulesTakenBeforeIndex, Module module) { +public static boolean isModuleAvailable(List modulesTaken, + List modulesTakenBeforeIndex, Module module) { return hasNotTakenModule(modulesTaken, module) && hasFulfilledAllPrerequisites(modulesTakenBeforeIndex, module) && hasNotFulfilledAnyPreclusions(modulesTaken, module); @@ -847,6 +861,7 @@ public static boolean isModuleAvailableToTake(List modulesTaken, List> to get started. Enjoy! +Module Planner is for National University of Singapore (NUS) Computer Science and Computer Engineering undergraduate students who *prefer to use a desktop app* to keep track of past modules and list possible future modules based on the academic requirements. More importantly, Module Planner is optimized for those who prefer to work with a *Command Line Interface (CLI)* while still having the benefits of a Graphical User Interface (GUI). If you can type fast, Module Planner can get your module planning tasks done faster than traditional GUI apps. Interested? Jump to the <> to get started. Enjoy! == Quick Start @@ -219,20 +219,21 @@ The change can be seen in Taken Modules Panel in the before and after images. |==== // end::goto[] +// tag::list[] === Listing modules : `list` -If a valid year is supplied, shows a list of all modules that you have added to that year. Otherwise, shows a list of all modules that you have added to every year. + +If a valid year is supplied, shows a list of all modules that you have added to that year. If no year is supplied, shows a list of all modules that you have added to every year. + Format: `list [y/YEAR]` [TIP] ==== -* This command is NOT undoable. * The list of modules will be automatically updated upon adding or deleting module(s). ==== [NOTE] ==== -* If no modules have been added to the specified year or no modules have been added to any year, will show an empty list. +* If a valid year is supplied but no modules have been added to the specified year, will show an empty list. +* If no year is supplied and no modules have been added to any year, will show an empty list. ==== Examples: @@ -242,6 +243,7 @@ Lists all modules taken in year 1, both semester 1 and 2 (if they exist). * `list` + Lists all modules taken in every year, from year 1 semester 1 to year 4 semester 2 (if they exist). +// end::list[] // tag::status[] @@ -253,16 +255,16 @@ Format: `status` You could see the status displayed on MultiPurpose Panel as shown below: image::StatusIllustration.png[width="790"] - // end::status[] +// tag::suggest[] === Suggesting modules : `suggest` If a valid year and semester are supplied, suggests a list of modules that you are available to take in the specified year and semester, based on modules that you have added. A module is available for you if: * You have fulfilled (added to ModulePlanner) all the prerequisites of the module in the semester(s) prior to the one you specified. -* You have not fulfilled (added to ModulePlanner) any preclusions to the module in any semester (including semester after the one you specified). -* You have not fulfilled (added to ModulePlanner) the module in any semester (including semester after the one you specified). +* You have not fulfilled (added to ModulePlanner) any preclusions to the module in any semester (including semester(s) after the one you specified). +* You have not fulfilled (added to ModulePlanner) the module in any semester (including semester(s) after the one you specified). The list of modules is sorted, with core modules being on top, followed by general education modules and unrestricted electives modules. @@ -270,21 +272,22 @@ Format: `suggest y/YEAR s/SEMESTER` [TIP] ==== -* This command is NOT undoable. * The list of suggested modules will be automatically updated upon adding or deleting module(s). ==== [NOTE] ==== -* This feature currently only supports *Computer Science* major. If user profile is set to other major in <> command, -this feature will only give you generic module suggestion sorted in lexicographical order. +* This feature currently only supports *Computer Science* major. If user profile is set to other major through <> command, +this feature will only give you generic module suggestion sorted in a lexicographical order. * The list of suggested modules will not be automatically updated after changing major through `setup`. You have to re-execute `suggest` to update the list. -* Support for other majors will come beyond v2.0. +* Support for other majors will come in v2.0. ==== Examples: * `suggest y/1 s/1` +* `suggest y/4 s/2` +// end::suggest[] // tag::undoredo[] === Undoing previous command : `undo` @@ -374,8 +377,8 @@ e.g. `goto y/1 s/1` * *List* : `list [y/YEAR]` + e.g. `list y/1` -* *Setup* : `setup y/YEAR s/SEMESTER m/MAJOR [f/FOCUS_AREA]` + -e.g. `setup y/1 s/1 m/computer science f/machine learning` +* *Setup* : `setup m/MAJOR [f/FOCUS_AREA]` + +e.g. `setup m/computer science f/machine learning` * *Status* : `status` diff --git a/docs/diagrams/ListSequenceDiagram_1.pptx b/docs/diagrams/ListSequenceDiagram_1.pptx index 736d1510a5ab..e800e9cafcf8 100644 Binary files a/docs/diagrams/ListSequenceDiagram_1.pptx and b/docs/diagrams/ListSequenceDiagram_1.pptx differ diff --git a/docs/diagrams/ListSequenceDiagram_2.pptx b/docs/diagrams/ListSequenceDiagram_2.pptx index 1c369e59af19..cef66ffefed1 100644 Binary files a/docs/diagrams/ListSequenceDiagram_2.pptx and b/docs/diagrams/ListSequenceDiagram_2.pptx differ diff --git a/docs/diagrams/SuggestSequenceDiagram.pptx b/docs/diagrams/SuggestSequenceDiagram.pptx index 3ada2ef2f389..fe44d7e82984 100644 Binary files a/docs/diagrams/SuggestSequenceDiagram.pptx and b/docs/diagrams/SuggestSequenceDiagram.pptx differ diff --git a/docs/images/ListSequenceDiagram_1.png b/docs/images/ListSequenceDiagram_1.png index b34dcbc4b6be..e21d1384ae78 100644 Binary files a/docs/images/ListSequenceDiagram_1.png and b/docs/images/ListSequenceDiagram_1.png differ diff --git a/docs/images/ListSequenceDiagram_2.png b/docs/images/ListSequenceDiagram_2.png index a1302aed0130..fae21917912a 100644 Binary files a/docs/images/ListSequenceDiagram_2.png and b/docs/images/ListSequenceDiagram_2.png differ diff --git a/docs/images/SuggestSequenceDiagram.png b/docs/images/SuggestSequenceDiagram.png index 1d7937512593..dca2654076e3 100644 Binary files a/docs/images/SuggestSequenceDiagram.png and b/docs/images/SuggestSequenceDiagram.png differ diff --git a/docs/team/hilda-ang.adoc b/docs/team/hilda-ang.adoc index af4e3429ca42..322219878bb8 100644 --- a/docs/team/hilda-ang.adoc +++ b/docs/team/hilda-ang.adoc @@ -7,36 +7,53 @@ == Overview -This project portfolio summarizes the contributions I have made in developing a product called ModulePlanner as a team project under CS2103T Software Engineering. ModulePlanner is a desktop application made to help NUS Computer Science undergraduate students plan their modules. It is designed to be used through a Command Line Interface (CLI), although it also provides a Graphical User Interface (GUI). Main features include suggesting available modules based on major requirements and module prerequisites and planning modules for each semester by adding or deleting modules to or from the planner. +This project portfolio showcases the contributions I have made in a team project under the module *CS2103T: Software Engineering*. I worked in a team of four Computer Science students to develop a product named *ModulePlanner*, which is built on top of an existing software (AddressBook - Level 4). -The next few sections will describe my contributions to the project. +*ModulePlanner* is a desktop application made to help Computer Science and Computer Engineering students in National University of Singapore plan their modules for their entire candidature periods. It is designed to be used mainly through a Command Line Interface (CLI), although it also provides a Graphical User Interface (GUI). + +The main features include: + +** Suggesting available modules based on major requirements and modules' prerequisites. +** Adding and deleting modules to or from the planner. == Summary of contributions -* *Major enhancement*: added *the ability to suggest modules available to take* -** What it does: allows the user to see the modules he/she is available to take in each semester, based on the modules he/she has taken. -** Justification: This feature helps the user plan modules by checking and listing available modules for him/her. -** Highlights: This is the main feature of our application. It required an analysis of several design alternatives and implementation choices. +|=== +|_Given below are enhancements I implemented for the product and other contributions I made to the team. They showcase my abilities in software engineering and in working with a team._ +|=== -* *Minor enhancement*: added a list command that allows user to see all modules he/she has added to a specific year or to all years. +* *Major enhancement*: added the ability to *suggest available modules to the user* +** What it does: allows the user to see the modules he/she is available to take in each semester, based on the modules he/she has added to the planner. +** Justification: This feature helps the user plan modules by generating and listing available modules. +** Highlights: This is the main feature of our application. It required a careful consideration of several design alternatives and implementation choices. The implementation was challenging as it interacted with various components and other commands. +** Pull requests: https://github.com/CS2103-AY1819S1-T16-4/main/pull/78[#78], https://github.com/CS2103-AY1819S1-T16-4/main/pull/81[#81], https://github.com/CS2103-AY1819S1-T16-4/main/pull/125[#125], https://github.com/CS2103-AY1819S1-T16-4/main/pull/146[#146], https://github.com/CS2103-AY1819S1-T16-4/main/pull/160[#160], https://github.com/CS2103-AY1819S1-T16-4/main/pull/191[#191] + +* *Minor enhancement*: added the ability to *list modules that the user has taken* +** What it does: allows user to see the modules he/she has added to all years or to a specific year. +** Justifications: This feature helps the user to quickly check what module(s) he/she has added to the planner. +** Pull requests: https://github.com/CS2103-AY1819S1-T16-4/main/pull/33[#33], https://github.com/CS2103-AY1819S1-T16-4/main/pull/68[#68], https://github.com/CS2103-AY1819S1-T16-4/main/pull/114[#114], https://github.com/CS2103-AY1819S1-T16-4/main/pull/143[#143], https://github.com/CS2103-AY1819S1-T16-4/main/pull/189[#189], https://github.com/CS2103-AY1819S1-T16-4/main/pull/195[#195] * *Code contributed*: [https://nus-cs2103-ay1819s1.github.io/cs2103-dashboard/#=undefined&search=hilda-ang] * *Other contributions*: ** Project management: -*** Managed release `v1.1` on GitHub -*** Recorded each of the user stories as an issue and assigned team members to issues -*** Assigned issues to milestones and set a deadline for each milestone on Github +*** Recorded each of the user stories as an issue (examples: https://github.com/CS2103-AY1819S1-T16-4/main/issues/11[1], https://github.com/CS2103-AY1819S1-T16-4/main/issues/12[2], https://github.com/CS2103-AY1819S1-T16-4/main/issues/13[3]) +*** Assigned team members to issues and issues to milestones (examples: https://github.com/CS2103-AY1819S1-T16-4/main/issues/39[1], https://github.com/CS2103-AY1819S1-T16-4/main/issues/73[2], https://github.com/CS2103-AY1819S1-T16-4/main/issues/74[3]) +*** Set a deadline for each milestone on Github ** Enhancements to existing features: -*** Refactored AddressBook to ModulePlanner and rewrote tests for shared classes +*** Refactored AddressBook to ModulePlanner (Pull requests https://github.com/CS2103-AY1819S1-T16-4/main/pull/113[#113], https://github.com/CS2103-AY1819S1-T16-4/main/pull/129[#129]) +*** Rewrote tests for shared classes (Pull requests https://github.com/CS2103-AY1819S1-T16-4/main/pull/147[#147], https://github.com/CS2103-AY1819S1-T16-4/main/pull/201[#201]) +*** Removed year and semester parameters from setup command (Pull request https://github.com/CS2103-AY1819S1-T16-4/main/pull/161[#161]) ** Documentation: -*** Modify User Guide to be relevant to current project +*** Modified User Guide to be relevant to current project (Pull requests https://github.com/CS2103-AY1819S1-T16-4/main/pull/6[#6], https://github.com/CS2103-AY1819S1-T16-4/main/pull/67[#67]) +*** Added description about the implementation of `suggest` and `list` commands in Developer Guide (Pull requests https://github.com/CS2103-AY1819S1-T16-4/main/pull/82[#82], https://github.com/CS2103-AY1819S1-T16-4/main/pull/210[#210]) ** Community: -*** PRs reviewed with non-trivial review comments -*** Reported bugs for other teams in the class +*** PRs reviewed with non-trivial review comments (Pull requests https://github.com/CS2103-AY1819S1-T16-4/main/pull/65[#65], https://github.com/CS2103-AY1819S1-T16-4/main/pull/136[#136], https://github.com/CS2103-AY1819S1-T16-4/main/pull/202[#202]) +*** Reported bugs for other team in the class (examples: https://github.com/CS2103-AY1819S1-W14-1/main/issues/193[1], https://github.com/CS2103-AY1819S1-W14-1/main/issues/200[2], https://github.com/CS2103-AY1819S1-W14-1/main/issues/223[3]) ** Tools: -*** Integrated a Github plugin (Coveralls) for code coverage checking to the team repo +*** Integrated a Github plugin (Coveralls) for code coverage checking to the team repo (Pull request https://github.com/CS2103-AY1819S1-T16-4/main/pull/144[#144]) +*** Configured repo to be compatible with RepoSense by adding a config file (Pull request https://github.com/CS2103-AY1819S1-T16-4/main/pull/124[#124]) == Contributions to the User Guide @@ -44,51 +61,9 @@ The next few sections will describe my contributions to the project. |_Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users._ |=== -=== Listing modules : `list` - -If a valid year is supplied, shows a list of all modules that you have added to that year. Otherwise, shows a list of all modules that you have added to every year. + -Format: `list [y/YEAR]` - -[TIP] -==== -* This command is NOT undoable. -* The list of modules will be automatically updated upon adding or deleting module(s). -==== - -[NOTE] -==== -* If no modules have been added to the specified year or no modules have been added to any year, will show an empty list. -==== - -Examples: - -* `list y/1` + -Lists all modules taken in year 1, both semester 1 and 2 (if they exist). - -* `list` + -Lists all modules taken in every year, from year 1 semester 1 to year 4 semester 2 (if they exist). - -=== Suggesting modules : `suggest` - -If a valid year and semester are supplied, suggests a list of modules that you are available to take in the specified year and semester, based on modules that you have added. A module is available for you if: - -* You have fulfilled (added to ModulePlanner) all the prerequisites of the module in the semester(s) prior to the one you specified. -* You have not fulfilled (added to ModulePlanner) any preclusions to the module in any semester (including semester after the one you specified). -* You have not fulfilled (added to ModulePlanner) the module in any semester (including semester after the one you specified). +include::../UserGuide.adoc[tag=suggest] -The list of modules is sorted, with core modules being on top, followed by general education modules and unrestricted electives modules. - -Format: `suggest y/YEAR s/SEMESTER` - -[TIP] -==== -* This command is NOT undoable. -* The list of suggested modules will be automatically updated upon adding or deleting module(s). -==== - -Examples: - -* `suggest y/1 s/1` +include::../UserGuide.adoc[tag=list] == Contributions to the Developer Guide @@ -96,128 +71,7 @@ Examples: |_Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project._ |=== -=== List feature -==== Current Implementation - -The list mechanism is facilitated by `ModulePlanner`. `ModulePlanner` stores a list of all `Semester`s and each `Semester` stores a list `modulesTaken` containing modules that the user has taken or is planning to take. -It implements the following operation: - -* `ModulePlanner#getTakenModules()` -- Retrieves the list `takenModules`. -* `ModulePlanner#listTakenModulesAll()` -- Updates `takenModules` to contain a list of modules retrieved from the list `modulesTaken` in every `Semester`. -* `ModulePlanner#listTakenModulesForYear(int year)` -- Updates `takenModules` to contain a list of modules retrieved from the list `modulesTaken` in the `Semester`s that belongs to the specified year. - -The operation is exposed in `Model` interface as `Model#getTakenModules()`, `Model#listTakenModulesAll()`, and `Model#listTakenModulesForYear(int year)`. - -[NOTE] -A valid index should be an integer between 0 to 7 inclusive, where index 0 represents year 1 semester 1, index 1 represents year 1 semester 2, index 2 represents year 2 semester 1, and so on. - -Below is an example usage scenario and how the list mechanism works. - -Step 1. User launches the application. `ModulePlanner` is initialised with 8 `Semester` objects in a list `semesters`. - -Step 2. User executes `add y/1 s/1 c/CS1231`. The `add` command inserts `Module` CS1231 to the list `modulesTaken` for `Semester` object with index 0. - -Step 3. User executes `add y/2 s/1 c/CS1010`. The `add` command inserts `Module` CS1010 to the list `modulesTaken` for `Semester` object with index 2. - -Step 4. User wants to see the list of modules taken for year 1 by executing `list y/1`. The `list` command updates `takenModules` to contain list of modules taken in year 1 and retrieves it. -A list containing CS1231 will be displayed to the user. - -Step 5. User wants to see the list of modules taken for all years by executing `list`. The `list` command updates `takenModules` to contain list of modules taken in all years and retrieves it. -A list containing CS1231 and CS1010 will be displayed to the user. - -The following sequence diagram shows how the list operation when a valid year is specified: - -image::ListSequenceDiagram_1.png[width="800"] - -The following sequence diagram shows how the list operation when no year is specified: - -image::ListSequenceDiagram_2.png[width="800"] - -==== Design Considerations - -===== Aspect: How list of modules is retrieved for list command -* **Alternative 1 (current choice):** Updates list of modules whenever it is modified by a command (e.g. `add`) and immediately retrieves the list upon `list` command. -** Pros: Easy to implement. -** Cons: May have performance issue in terms of running time if commands that modify the list are called frequently. -* **Alternative 2:** Saves all commands that modify list of modules without applying it and updates the list based on the commands only when it is retrieved upon `list` command. -** Pros: May be more effective in terms of running time because it only modifies the list when needed. -** Cons: Implementation will be more complicated as we have to store all commands that modify the list. - -=== Suggest feature -==== Current Implementation - -The suggest mechanism displays a list of modules available in the specified index to the user, where index represents the year and semester that the user is asking suggestions for. -It is supported by an internal list `availableModules` in `ModulePlanner`, which is regenerated after every successful execution of commands that modify `ModulePlanner` (`add`, `delete`, `clear`, etc.) and `suggest` command. -The list `availableModules` can be retrieved through `Model#getAvailableList()` using `suggest` command, which (`suggest` command) takes in one argument: a valid index that corresponds to a specific year and semester. - -[NOTE] -A valid index should be an integer between 0 to 7 inclusive, where index 0 represents year 1 semester 1, index 1 represents year 1 semester 2, index 2 represents year 2 semester 1, and so on. - -Below is an example usage scenario and how the suggest mechanism works. - -*Step 1.* User launches the application and `ModulePlanner` is initialized. - -*Step 2.* User executes `suggest y/1 s/1`. The `suggest` command updates `availableModules` to a newly generated list of available modules for index 0 an stores index 0 as `availableIndex` in `ModulePlanner`. It then retrieves `availableModules` and displays it to user. - -*Step 3.* User executes `add y/1 s/2 c/CS1010`. The `add` command performs adding a module and updates `availableModules` to a newly generated list of available modules for the stored index 0. The suggested modules list shows an updated list of available modules in year 1 semester 1 to the user. -Only `suggest` command will change the index (year and semester) to be displayed by the suggested modules list, other commands will only show an updated list for the last index displayed by `suggest`. - -*Step 4.* User executes `suggest y/1 s/2`. The `suggest` command updates `availableModules` to a newly generated list of available modules for index 1 an stores index 1 as `availableIndex` in `ModulePlanner`. It then retrieves `availableModules` and displays list of available modules in year 1 semester 2 to user. - -Below is how the list of available modules is generated. - -The method `ModulePlanner#generateAvailableModules(int index)` is called by `ModulePlanner#updateModulesAvailable()`, which sets the content of `availableModules` to be the list of modules returned by `generateAvailableModules(index)`, with `index` being the stored `availableIndex`. - ----- -private List generateAvailableModules(int index) { - List modulesAvailable = new ArrayList<>(); - List modulesTaken = getAllModulesTaken(); - List modulesTakenBeforeIndex = getAllModulesTakenBeforeIndex(index); - List allModules = getAllModulesFromStorage(); - - for (Module m : allModules) { - if (ModuleUtil.isModuleAvailable(modulesTaken, modulesTakenBeforeIndex, m)) { - modulesAvailable.add(m); - } - } - - sortAvailableModules(modulesAvailable, userProfile); - - return modulesAvailable; -} ----- - -The method `ModulePlanner#generateAvailableModules(int index)` retrieves all modules from the storage and performs availability checking on each of them. The available modules are put into a list which is then sorted: - -** in a lexicographical order if user has specified a major other than *Computer Science* through `setup` command, or -** such that core modules for *Computer Science* major are put on top, followed by general education modules and unrestricted electives. - -The availability checking is done by the following method. - ----- -public static boolean isModuleAvailableToTake(List modulesTaken, List modulesTakenBeforeIndex, Module module) { - return hasNotTakenModule(modulesTaken, module) - && hasFulfilledAllPrerequisites(modulesTakenBeforeIndex, module) - && hasNotFulfilledAnyPreclusions(modulesTaken, module); -} ----- - -A sample scenario: -Module CS2030 has a prerequisite CS1010 and a preclusion CS1020. User has taken CS1010 in year 1 semester 2 and has not taken CS1020 or CS2030. - -* Executing `suggest y/2 s/1` will display CS2030 as one of the available modules, as user has fulfilled all prerequisites of CS2030 before year 2 semester 1 and has not taken any preclusion or the module itself. -* Executing `suggest y/1 s/1` will *not* display CS2030 in the list of available modules, as user has not fulfilled all the prerequisites before year 1 semester 1 (user has only fulfilled CS1010 in the semester after). - -The following sequence diagram shows how the suggest operation works: - -image::SuggestSequenceDiagram.png[width="800"] +include::../DeveloperGuide.adoc[tag=suggest] -==== Design Considerations +include::../DeveloperGuide.adoc[tag=list] -===== Aspect: How list of available modules is regenerated -* **Alternative 1 (current choice):** Regenerates list of available modules after every successful execution of commands that modify `ModulePlanner` and `suggest` command. -** Pros: Easy to implement. -** Cons: May have performance issue in terms of running time because list is regenerated even if there is no change to the content. -* **Alternative 2:** Regenerates list of available module only after successful execution of commands that modify the content of the list of available modules. -** Pros: May be more effective in terms of running time because it only regenerates the list when needed. -** Cons: Implementation will be more complicated as we have to check whether a command modifies the list.