PROJECT: LearnVocabulary

Overview

LearnVocabulary is a desktop application for people who prefer to use an offline version of the dictionary for learning purposes.

Summary of contributions

  • Major enhancement: Added the learn feature command

    • What it does: Searches for the given word on LearnVocabulary and extracts the definition of the word. It then attaches a default tag, which is all stored inside LearnVocabulary.

    • Justification: This feature is the backbone of LearnVocabulary because it saves the user a lot of time by querying and storing the word with its meaning. It then saves all of that into a personalized storage area for the user to review (display and show) at a later time.

    • Highlights: This enhancement had to be properly integrated by carefully navigating around the different existing commands.

  • Minor enhancements: Added the show command, which displays the filtered word(s) unto the Ui, making the Ui appear more engaging and interactive.

  • Code contributed: RepoSense collated code

  • Other contributions:

    • Project management:

      • Team-lead, testing and integration

      • Managed releases v1.0 - v1.4 (3 releases) on GitHub

      • Refactored AB4 into LearnVocabulary Pull request #49

      • Managed RepoSense, Coveralls, Travis, co-managed Netlify

    • Enhancements:

      • Enhanced the add command, which adds a default tag should no tags be attached. Enhanced the edit command, which prevents user from deleting all tags, must have at least one tag attached to a word. Pull request #151

    • Documentation:

      • Proper format of Developer and User Guide: #157 #158

    • Community:

      • Reported bugs and suggestions for other teams in the class 1, 2, 3

      • Bug fixes in various PRs 1, 2, 3

      • Added documentation for features implemented.

    • Tools:

      • Integrated a third party library (Jsoup) to the project

Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Learning a word: learn

With the access of an internet connection, the user can enter learn [word] and the application will query the word’s definition.

Format: learn happy

It will then be attached to a default tag called toLearn, for easier reference for the user.

Examples:

  • learn happy

Queries the meaning on dictionary.com and attaches a default tag (toLearn) to the word.

This function does not accept multiple entries.

Adding a word: add

Adds a word to the vocabulary list
Format: add n/WORD m/MEANING [t/TAG]…​

A word can have any number of tags provided the groups of the tags are already created. Words that are added without tags will be added to the toLearn group by default

Examples:

  • add n/levitate m/to float or fly t/Test

  • add n/levitate m/to float or fly t/Test t/RealTest (Each tag is contained in their own prefix t/)

  • add n/levitate m/to float or fly (toLearn tag will be attached to word by default)

Group (tag) must already exist (been created) by user. The only default tag that has no need to be created is the "toLearn" tag.

Editing a word : edit

Edits an existing word in the vocabulary list.
Format: edit INDEX [n/NAME] [m/MEANING] [t/TAG]…​

  • Edits the word at the specified INDEX. The index refers to the index number shown in the displayed vocabulary list. The index must be a positive integer 1, 2, 3, …​

  • Name and Meaning class must have their fields filled in eg: add n/hello m/a greeting.

  • Existing values will be updated to the input values.

  • When editing tags, the existing tags of the word will be removed i.e adding of tags is not cumulative.

  • There will be at least one tag to each word, so it is enforced that no edits allow for 0 tags per word.

Examples:

  • edit 1 m/diabolic magic or art
    Edits the meaning of the first word to diabloic magic or art.

  • edit 1 t/darkarts
    Edits the tag of the first word to darkarts, replacing every other tag.

  • edit 1 t/darkarts t/magical
    Edits the tag of the first word to darkarts and magical, replacing every other tag.

  • edit 1 t/
    Fails to remove all tags as there must be at least one tag attached to every word.

Group (tag) must already exist (been created) by user. The only default tag that has no need to be created is the "toLearn" tag.

Showing a word : show

Shows the word identified by the word itself.

Format show WORD or show WORD WORD or show WORD WORD WORD…​

  • Finds the word (or multiple words and shows the word with its meaning and tags in the command box.

Examples:

  • show levitate

Outputs the meaning and tags of levitate in the command box.

  • show levitate fly

Outputs the meaning and tags of levitate and fly in the command box.

This will output a list of words that follows the sequence of the already established list.

For example:

List contains 1. hi 2. bye 3. try 4. neigh

Typing in 'show bye hi neigh' will output the result of 1, 2 and 4 in sequence following the established list.

Moreover, the first sequence number will be selected automatically. If there are no existing words that are found, the default display would be the last displayed placeholder page.

However, user should note that showing a word not present would not result in any changes to the Ui as it is not intended, it will still continue to display the previous word being selected in the panel on the right.

Contributions to the Developer Guide

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.

Learn feature

Current Implementation

The learn mechanism is facilitated by the Dictionary class. The backbone of LearnVocabulary would have to be the Learn command, because it allows the user to query words from the internet and parse their meanings into readable format for storage. The learn command is indicated as Learn in commands, and inherits the Command class. It enables the user to "learn" a word from the world wide web. This command is requires the use of Internet, should there be an absence of Internet connection, it has already been taken care of via throwing an Exception. Additionally, it implements the following operations:

  • Dictionary#invoke() — calls the main function of Dictionary which links it to LearnVocabulary

  • Dictionary#isConnectedToInternet() — checks to see if there is an Internet connection established.

  • Dictionary#isWordInOnlineDictionary(Word) — checks to see if it is a valid word and if it exists in Dictionary.com

  • Dictionary#convertWord(Word) — converts word into first letter is in big caps, whilst the others are in small caps.

  • Dictionary#isValidWord(Word) — checks to see if it word contains any illegal characters.

Dictionary#invoke() is exposed in the LearnCommandParser class as LearnCommandParser#parse(), while all the other operations are self-contained within the Dictionary#invoke() operation.

Given below is an example usage scenario and how the learn mechanism behaves at each step.

Step 1. The user launches the application for the first time. The user types in learn magic into the CLI.

Step 2. learn magic will be parsed by LearnVocabularyParser, where the learn command will be triggered, calling LearnCommandParser#parse().

Step 3. This in turn calls Dictionary class and all of its relevant operations, starting with Dictionary#invoke().

Step 4. The word magic will be checked against the model and the current LearnVocabulary to see if they hold the same exact word.

Step 4a. The word does not exist and will be stored, together with the meaning that was queried as a result of Dictionary#invoke().

Step 4b. The word already exists and the command will throw a Duplicate Word Exception.

The newly queried word would be attached with a "toLearn" tag, which allows the user to know that he/she just queried the word and can leave it for the future to learn it.

Step 5. The word, meaning will be assigned a default tag and be displayed in the Command Box.

The following sequence diagram shows how the learn command works:

LearnSequenceDiagram

Design Considerations

Aspect: How Words are queried in Dictionary

  • Alternative 1 (current choice): Online querying of every word being learned.

    • Pros: Easy to implement and change (in the future) to accommodate extra meanings.

    • Cons: Requires the use of Internet Connection.

  • Alternative 2: Offline querying of every word being learned.

    • Pros: Does not require Internet to query word.

    • Cons: Untested, but a corrupt xml file would be disastrous causing corrupt findings, memory space will be an issue as well.

Aspect: How Words are stored in Dictionary

  • Alternative 1 (current choice): Offline storage of every word being learned.

    • Pros: Easy to implement and does not require the use of a cloud storage.

    • Cons: Not mobile and accessible to the user

  • Alternative 2: Online storage of every word being learned.

    • Pros: Mobile access by the user on the go.

    • Cons: Will consume a lot of resources. Might not be necessary.

Rejected/Put off implementations

Idea: Multiple words to be learned at the same time

  • learn fire ice will simultaneously pull data of 2 words fire and ice into LearnVocabulary

  • This was put off in terms of implementations because:

    • Firstly, loading speed will be slow, affecting performance

    • Secondly, it causes the command box to freeze

A simple fix was thought of, which was to run threads in LearnVocabulary to pull data simultaneously to reduce time and improve overall performance. That will be explored in later versions.

Idea: Synonyms of the same word to be learned at the same time

  • learn hot 10 will simultaneously pull data of hot and 10 of its synonyms. Effectively querying and storing 11 words in total.

  • This was rejected terms of implementations because:

    • Firstly, it does not serve the intended target audience well. Words can be fetched at random without bearing resemblance to the original queried word.

    • Secondly, Speed and performance issue as mentioned in the first idea.

A simple fix for the speed and performance issue was mentioned above.

Learning a word (Manual Testing)

  1. Learning a word from Dictionary.com

    1. Prerequisites: Ensure Internet Connection is established.

    2. Test case: learn potato
      Expected: The word potato is added to LearnVocabulary, with its definition and a default tag. Details of the learnt word shown in the status message. Timestamp in the status bar is updated.

    3. Test case: learn !potato
      Expected: No word is learnt. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect learn commands to try: learn, learn x, learn 1, learn notarealword
      Expected: Similar to previous.

Basic features

Current Implementation

Improved from the previous versions, the Add and Edit commands have been refined in LearnVocabulary. There is also a minor feature added Show, which displays a filtered word list on the Ui.

Each tag being added follows AB4’s implementation, separate tags are considered via t/
So, t/happy, t/emotions, t/sad is considered 3 tags and they MUST have already been added via groupadd. Tags will not be added as a whole if any of them do not exist.
Add command improvements

When adding a new word to LearnVocabulary, only the Name and Meaning fields must be entered as follows: add n/fire m/something hot. As can be seen from the example given, there is no Tag being entered at all. However, LearnVocabulary will enforce that every word would require at least one tag. As such, the default tag "toLearn" will be given to words without any tags at the start.

Given below is an example usage scenario and how the add mechanism behaves at each step.

Step 1. The user types in add n/fire m/something hot into the CLI.

Step 2. add n/fire m/something hot will be parsed by LearnVocabularyParser, where the add command will be triggered, calling AddCommandParser#parse().

Step 3a. Illegal characters will cause the command to throw an exception and await a new command.

Step 3b. Word with letters being parsed will be checked against LearnVocabulary to ensure no duplicate words.

Step 4. Word will have a default tag attached, be added to LearnVocabulary after ensuring no duplicates.

Edit command improvements

When editing an existing word in LearnVocabulary, there cannot be empty tags for any words provided.

Given below is an example usage scenario and how the edit mechanism behaves at each step.

Step 1. The user types in edit 1 t/ which shows the user wanting to clear all tags from existing word.

Step 2. The command box outputs that it is not possible, at least one tag must be attached to the word.

Show feature

The show command is an improvement in leaps and bounds ahead of the find command, but it exists as a separate command on its own due to its nature. Simply put, when entering show fire magic life, it will display the 3 words on the Ui and automatically outputs the word, meaning and tags onto the Command Box. The first word from the list will also be automatically selected.

As such, Show was implemented with a more Ui state of mind, to ensure the user’s ease of use when finding the words for display of their meanings as AddressBook level 4 did not cater to this particular arrangement.

Given below is an example usage scenario and how the show mechanism behaves at each step.

Step 1. The user types in show fire magic life, it will display the 3 words in order as it was in the list.

Multiple words are allowed to be queried. Allows for more flexibility compared to the Ui option.

Step 2. From the filtered list of words, the program automatically selects and displays first word from list.

Step 3. The 3 words will appear in the Command Box as well.

Showing a word (Manual Testing)

  1. Showing a word from LearnVocabulary’s list.

    1. Prerequisites: List all words using the list command. Multiple words in the list.

    2. Test case: show potato
      Expected: The word potato is filtered and returned inside LearnVocabulary, together with its definition and tags attached to it. Details of the word is shown in the status message. Timestamp in the status bar is updated.

    3. Test case: show potato gravy happy
      Expected: The words potato, gravy, happy are filtered and returned inside LearnVocabulary, together with their definitions and tags attached to it. Details of the words are shown in the status message. Timestamp in the status bar is updated.

    4. Test case: show
      Expected: No word is shown. Error details shown in the status message. Status bar remains the same. Display remains the same.

    5. Other incorrect learn commands to try: show 1, show x, show !potato, show notarealword
      Expected: Similar to previous. Except now, filtered list is empty.

Adding a word (Manual Testing)

  1. Adding a word to LearnVocabulary’s list.

    1. Prerequisites: Word must not have been added to LearnVocabulary.

    2. Test case: add n/potato m/type of starch
      Expected: The word potato is added inside LearnVocabulary, together with its definition and default tag toLearn attached to it. Details of the word is shown in the status message. Timestamp in the status bar is updated.

    3. Test case: add n/potato
      Expected: The word potato will not be added inside LearnVocabulary, because meaning field is missing. Error details shown in the status message. Status bar remains the same. Display remains the same.

Editing a word (Manual Testing)

  1. Editing a word in LearnVocabulary’s list.

    1. Prerequisites: List must be non-empty.

    2. Test case: edit 1 m/something lightweight
      Expected: The word potato in index 1 will have its meaning changed from its existing meaning to its new definition "something lightweight". Details of the word is shown in the status message. Timestamp in the status bar is updated.

    3. Test case: edit 1 m/something lightweight t/light t/weight
      Expected: The word potato in index 1 will have its meaning changed from its existing meaning to its new definition "something lightweight". It’s tags (should they already been created in groupadd), will attach 2 tags light and weight to the word. Details of the word is shown in the status message. Timestamp in the status bar is updated.

    4. Test case: edit n/potato t/
      Expected: The word potato will not be edited inside LearnVocabulary, because tag field is missing, it is enforced that there can no longer be any words that have 1 tag. Error details shown in the status message. Status bar remains the same. Display remains the same.