Skip to content

Commit

Permalink
Update documentation (#223)
Browse files Browse the repository at this point in the history 
* Add project portfolio page

* Rename portfolio and update User Guide

* Update portfolio

* Update Developer Guide

* Update portfolio and User Guide

* Remove duplicated ListSequenceDiagram_1

* Fix inconsistencies in DEveloper Guide and add information on suggestion sorting

* Update DG section in portfolio

* Fix inconsistencies in User Guide and update UG section in portfolio

* Change -s for plural forms to s

* Update method names

* Change wording in UG and update portfolio

* Trim portfolio and add syntax highlighting for DG

* Add styling

* Update documentations

* Fix typos and add preface

* Fix formatting in portfolio

* Add project description

* Update images

* Update README to include Computer Engineering

* Add instructions for testing

* Update portfolio
  • Loading branch information
@Hilda-Ang
Hilda-Ang authored Nov 12, 2018
1 parent b489189 commit 548eb3f
Show file tree
Hide file tree
Showing 10 changed files with 130 additions and 232 deletions.
20 changes: 9 additions & 11 deletions README.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand All @@ -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.
Expand All @@ -39,33 +37,33 @@ 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*.
==== New way of planning modules
****
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.
****
Much better!
== Site Map
* <<UserGuide#, User Guide>>
* <<DeveloperGuide#, Developer Guide>>
* <<AboutUs#, About Us>>
* <<ContactUs#, Contact Us>>
* <<DeveloperGuide#, Developer Guide>>
* <<UserGuide#, User Guide>>
== Acknowledgements
Expand Down
95 changes: 69 additions & 26 deletions docs/DeveloperGuide.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand All @@ -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
Expand Down Expand Up @@ -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]
----
Expand All @@ -835,18 +848,20 @@ 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<Module> modulesTaken, List<Module> modulesTakenBeforeIndex, Module module) {
public static boolean isModuleAvailable(List<Module> modulesTaken,
List<Module> 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.
Expand All @@ -859,13 +874,13 @@ image::SuggestSequenceDiagram.png[width="800"]
==== Design Considerations

===== 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.
* **Alternative 1 (current choice):** Regenerates list of available modules after every successful execution of commands that *may* modify the list of available modules.
** 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.
* **Alternative 2:** Regenerates list of available modules only if a command modifies 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.

** Cons: Implementation will be more complicated as it requires additional checking on whether a command modifies the list.
// end::suggest[]

// tag::undoredo[]
=== Undo/Redo feature
Expand Down Expand Up @@ -1186,9 +1201,8 @@ b. Require developers to download those libraries manually (this creates extra w

*Target user profile*:

* NUS Computer Science students who :
+
[none]
NUS Computer Science and Computer Engineering students who :

** need to manage their modules
** is familiar with CLI apps
** prefer typing over using mouse
Expand Down Expand Up @@ -1487,6 +1501,34 @@ semester after.

image::CorruptedDataFile.png[width="300"]

=== Suggesting modules

. Suggesting modules for a specific year and semester
.. Test case: `suggest y/1 s/1` +
Expected: The panel for *Modules Suggested* is updated to show *Year 1 | Semester 1* and list of suggested modules for year 1 semester 1. A success message is shown in the status message.
.. Test case: `suggest` +
Expected: The panel for *Modules Suggested* remained the same as before executing the command. Error message is shown in the status message.
.. Other incorrect suggest commands to try: `suggest y/a s/b` (where a is not an integer between 1 to 4 inclusive or b is neither 1 or 2) +
Expected: Similar to previous.

=== Listing modules

. Listing modules for all years
.. Prerequisites: Add some modules to ModulePlanner using `add` command.
.. Test case: `list` +
Expected: The panel for *Modules Taken* is updated to show *All years* and list of all modules that have been added. A success message is shown in the status message.
.. Test case: `list 1` +
Expected: The panel for *Modules Taken* remained the same as before executing the command. Error message is shown in the status message.

. Listing modules for a year
.. Prerequisites: Add some modules to year 1 using `add` command.
.. Test case: `list y/1` +
Expected: The panel for *Modules Taken* is updated to show *Year 1* and all modules that have been added to year 1. A success message is shown in the status message.
.. Test case: `list y/0` +
Expected: The panel for *Modules Taken* remained the same as before executing the command. Error message is shown in the status message.
.. Other incorrect list commands to try: `list y/a` (where a is not an integer between 1 to 4) +
Expected: Similar to previous.

=== Set up user profile

. Set up user profile
Expand Down Expand Up @@ -1533,3 +1575,4 @@ and "Artificial Intelligence" as focus areas.
*** Command: `setup m/Information Security f/Computer Graphics`
*** Expected: Fail to set up user profile with error messages `Invalid major (Information Security)`
and `All focus area(s) are invalid`.

Loading

0 comments on commit 548eb3f

Please sign in to comment.