diff --git a/docs/DeveloperGuide.adoc b/docs/DeveloperGuide.adoc index a13ec5ba12a..c78469e26f9 100644 --- a/docs/DeveloperGuide.adoc +++ b/docs/DeveloperGuide.adoc @@ -30,6 +30,8 @@ Welcome on-board the Software Development Team for Calgo! Together, we will insp Refer to the guide <>. +<<< + == Design [[Design-Architecture]] @@ -295,6 +297,8 @@ if (!model.hasLogWithSameDate(queryDate) || model.getLogByDate(queryDate).getFoo } ---- +<<< + //tag:: Goal[] [[Implementation-GoalFeature]] === Setting daily calorie goals for motivation @@ -353,6 +357,8 @@ Step 5: `LogicManager` then executes the `GoalCommand`, which in turn invokes `u Step 6: In `Model`, the `updateDailyGoal` method is a static method that generates a new `DailyGoal` object with the corresponding input. This `DailyGoal` object is returned to `Model` , which replaces the existing `DailyGoal` attribute of the `ModelManager` with the newly generated `DailyGoal` object. +<<< + ==== Design Considerations ===== Aspect: Type of user input data that is required for goal command @@ -383,6 +389,8 @@ Refer to the Activity Diagram below for a visual summary of the logic behind the .Activity Diagram for `goal` command. image::GoalActivityDiagram.png[] +<<< + // tag::categoricalsubstringfindsearch[] [[Implementation-FindList]] === Searching for specific `Food` via categories and substrings @@ -402,6 +410,8 @@ For more information on lexicographical ordering, please refer to its relevant s The above commands rely on the `FindCommand` and `ListCommand` objects respectively. Objects of both classes use a `Predicate` object to filter through the current `Food` objects, where `Food` objects will be displayed in the GUI's `Food Record` should they evaluate these predicates to be true. +<<< + ==== Implementation To search via a particular `Food` attribute, we use a `FindCommandParser` to create the corresponding `Predicate` based on which `Food` attribute the `Prefix` entered represents. This predicate is then used to construct a new `FindCommand` object, which changes the GUI display when executed. + @@ -412,6 +422,8 @@ image::FindListCommandPredicateClassDiagram.png[] As seen in the above class diagram, each `Predicate` is indeed representative of either `Name`, `Calorie`, `Protein`, `Carbohydrate`, `Fat`, or `Tag`. Moreover, it should be noted that each of these predicates test against a `Food` object, and therefore have a dependency on `Food`. +<<< + The sequence diagram below demonstrates how the `find` command works, for both categorical and substring search: .Sequence Diagram for `find` command: Categorical Search and Substring Search @@ -450,6 +462,8 @@ Step 2: `LogicManager` then calls the `execute` method of this `ListCommand`, wh Step 3: `LogicManager` then returns a new `CommandResult` object to reflect the status of the execution, in the GUI. The GUI's `Food Record` reflects the above changes to show all `Food` entries once again. +<<< + ==== Design considerations ===== Aspect: Predicate construction source. @@ -504,6 +518,8 @@ The `find` command performs a categorical search if a value from a nutritional c Meanwhile, the `list` command simply uses the predicate already defined in `Model` to display all `Food` objects. + +<<< + The above can be summarised in the activity diagram below: .Activity Diagram for Searching @@ -511,6 +527,9 @@ image::FindListCommandActivityDiagram.png[] // end::categoricalsubstringfindsearch[] + +<<< + // tag::lexicographicalordering[] [[Implementation-LexicographicalOrder]] === Lexicographical `Food` order @@ -626,8 +645,6 @@ model.updateFilteredFoodRecord(Model.PREDICATE_SHOW_ALL_FOODS); - More troublesome as we require self-defined methods, abstracted over the existing ones. If not careful, these self-defined methods can possibly contain violations of certain software engineering principles, which may introduce regression in the future. - May be inefficient in using resources. -<<< - ==== Summary The `UniqueFoodList` facilitates the lexicographical ordering of `Food` objects and hence how their respective entries appear in the GUI `Food Record`. This can be summarised in the activity diagram below: @@ -636,6 +653,8 @@ The `UniqueFoodList` facilitates the lexicographical ordering of `Food` objects image::LexicographicalOrderingActivityDiagram.png[] // end::lexicographicalordering[] +<<< + // tag::exportfoodrecord[] [[Implementation-Export]] === Exporting the current `FoodRecord` into a portable file @@ -681,6 +700,8 @@ Step 3: `ExportCommand` then calls the `generateExport` method of `ExportGenerat Step 4: A new `CommandResult` object indicating the result of the execution is then constructed and reflected in the GUI. +<<< + [[Design-Export]] ==== Design considerations @@ -728,6 +749,8 @@ Step 4: A new `CommandResult` object indicating the result of the execution is t ** Cons: - Unable to reap benefits of the above alternatives. +<<< + ==== Summary In short, this section addresses how users are able to obtain an editable copy of the current `FoodRecord` using the `export` command. @@ -741,6 +764,7 @@ image::ExportActivityDiagram.png[] // end::exportfoodrecord[] +<<< [[Implementation-ConsumptionManagement]] === `Food` consumption management @@ -788,6 +812,12 @@ Here is what happens when different classes call `toModelType`: + Below shows the high level view of the initialization process: + +[NOTE] +For the subsequent sequence diagrams in the section, +the lifelines for objects should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram. + + .Sequence Diagram for loading of Consumption Record image::ConsumptionRecordSequenceDiagram.png[] @@ -806,10 +836,6 @@ It specifically checks if there exists a `DailyFoodLog` with the same `LocalDate they are already present. From all these information, a `DailyFoodLog` object representing the result of consuming a `Food` is created, and supplied to create `NomCommand`. The diagram below shows how this happens: -[NOTE] -For the subsequent sequence diagrams in the section, -the lifelines for objects should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline reaches the end of diagram. - .Sequence Diagram for parsing of Nom command image::NomCommandParserSequenceDiagram.png[] @@ -1147,6 +1173,7 @@ image::RealTimeSuggestionActivityDiagram.png[] [[Implementation-HelpGuide]] //tag:: helpCommand[] === Command guide `help` command +(by Janice) This section addresses how the `help` command works. diff --git a/docs/UserGuide.adoc b/docs/UserGuide.adoc index e11bfc554e6..7dc78efe2a9 100644 --- a/docs/UserGuide.adoc +++ b/docs/UserGuide.adoc @@ -43,12 +43,12 @@ search inputs, produce fast responses and suggestions. * *Performance:* Enjoy a smooth and fast workflow, powered by a combination of a robust Command Line Interface (CLI) and an objectively clear Graphical User Interface (GUI). + -As you can see, Calgo's features are optimised for you to build healthy eating habits and learn how to keep track of your diets. +As you can see, Calgo's features are optimised for you to build healthy eating habits and learn how to keep track of your diet. <<< == Additional Information -Before continuing, it may be helpful to familiarize yourself with a few symbols that you will encounter in this User Guide: +Before continuing, it may be helpful to familiarise yourself with a few symbols that you will encounter in this User Guide: [NOTE] This provides you with additional information that should be taken note of. @@ -58,6 +58,15 @@ This informs you of useful tips about Calgo. Also, as you may be wondering from the previous section, any words that are marked up in this format: `This is an example` refer to technical terms related to Calgo's implementation. +Check out the list below on how to use this User Guide. + +* If you are a first-time user, start from <> for instructions for downloading and setting up Calgo. +* If you are unsure of the GUI of Calgo, start from <> to learn what each component of the App is. +* If you are interested to learn about the various features Calgo has, check out the Commands section <>. +* If you are already familiar with Calgo, but need a slight refresher, check out the Command Summary section <>. + + +<<< == Quick Start . Ensure you have Java `11` or above installed in your Computer. @@ -75,7 +84,7 @@ image::Ui.png[width="790"] + . To verify that Calgo is working for you, type your desired command in the command box and press kbd:[enter] to execute it. + -*Example:* Type *`help`* and press kbd:[enter] to open the `Help Window`, which should look like this: + +*Example:* Type *`help`* and press kbd:[enter] to open the `Help Window`, which should look like the diagram in the next page. + + .A screenshot of Calgo's Help Window @@ -89,9 +98,13 @@ Start experimenting with the commands yourself and experience the convenience Ca - Learn specific details about the various commands Calgo offers by referring to <>. - If you need a complete summary of all commands, refer to <>. +<<< //tag::interpretGUI[] [[GUI]] -== Interpreting Calgo's Graphical User Interface +== Interpreting Calgo's Graphical User Interface + + +(by Janice) + + //placeholder unlabelled image .A labelled illustration of Calgo on startup [reftext="Figure 4.1"] @@ -101,7 +114,7 @@ image::UiLabelled.png[] Calgo's GUI is designed to be sleek and compact, allowing you to use and view all of Calgo's features on a single window. However, that might be a little overwhelming at the start. Hence, this section aims to give a rundown on the GUI's various parts and ease you into using the App, starting from the -top of the GUI. +top of the GUI shown in the above diagram. These sections are labelled from 1 to 8, in the following order: @@ -116,6 +129,7 @@ These sections are labelled from 1 to 8, in the following order: There is a ninth part, the `Help Window`, that is a separate pop up - only appearing when required for your convenience. +<<< === `Menu Bar` The bar has two buttons, `File` and `Help`. The buttons allow you to exit the App by clicking the exit option under `File`, and to access the command guide by clicking the @@ -150,6 +164,7 @@ It has three subsections: . The number of portions of the `Food` you consumed that day. . The average rating as set by you, color-coded from red to green for low to high rating. +<<< === `Graph Display` This section contains a graph that shows a summary of your past seven day's total calorie consumption. It displays data starting from the date of the current `Consumption Record`. @@ -166,6 +181,7 @@ can easily tell one entry apart from its neighbours. This bar shows where Calgo reads system data from. You should not delete or modify these files. //end::interpretGUI[] +<<< [[Commands]] == Commands @@ -197,6 +213,7 @@ Never make spelling mistakes again! The following subsections will elaborate on the specific details of Calgo commands. +<<< === `clear` : Clearing all entries (by Vineeth) @@ -226,6 +243,7 @@ image::ClearCommandAfter.png[] Upon entering the command, all your `Food` entries in the `Food Record` will be deleted. This will result in an empty `Food Record`, as shown above. As mentioned previously, your data in the `Consumption Record` and `Graph Display` is left unchanged. +<<< === `delete` : Deleting a `Food` from current `Food Record` (by Zhang Xian) @@ -263,6 +281,7 @@ exiting Calgo. Format: `exit` +<<< // tag::exportfoodrecord[] === `export` : Exporting the current `Food Record` into a reference sheet (by Eugene) + @@ -294,6 +313,7 @@ Individual entries will also appear on separate lines. Format: `export` + (any parameters entered are ignored) +<<< Example: + Let's suppose you wish to export the current `Food Record` so that you can print a copy for reference while cooking. Here's how you can do it: @@ -357,6 +377,8 @@ image::FindCommandCalorieAfter.png[] Once the command has been entered, the `Result Display` shows the results of your command and the `Food Record` displays the relevant entries with 150 calories. +<<< + Example 2: Say you wish to find entries which contain the keyword `Cheese` in their name, but your hand slipped and the keyboard only typed `Chees`. This is what happens: + @@ -371,6 +393,8 @@ the relevant entries which contain `Chees` in their name. This is not too bad, a be largely relevant to `Cheese`. This shows that the `find` command can search for `Food` entries with incomplete keywords. +<<< + Example 3: Say you are lazy but wish to find entries containing the keyword `sweet` in their tag. Here is how you can do it: + image::FindCommandTagBefore.png[] @@ -386,6 +410,8 @@ Please note that the search is case-insensitive, an example being the resulting as with Example 2, we allow for incomplete words to be used as search keywords. // end::findcommand[] +<<< + [[goal]] === `goal` : Setting a daily calorie target (by Vineeth) @@ -409,16 +435,20 @@ Acceptable values are positive integers, ranging from 1 to 99999. Format: `goal GOAL` +<<< + Example: Let's suppose you are a young adult who is trying to lose weight because your favourite jeans have become too tight. You search online for the ideal number of calorie you should consume daily to lose weight. A credible online source states it should be 1900 calories. Now, you want to reflect that daily calorie goal in Calgo. You can do that by following this simple step: -image::GoalCommandBefore.png] +image::GoalCommandBefore.png[] Type in `goal 1900` and press kbd:[enter], as shown above. + +<<< + image::GoalCommandAfter.png[] As you can see, the `Daily Goal Display` has updated to reflect your daily calorie goal. You can now track your meals @@ -442,6 +472,8 @@ Here are some key pointers: Format: `help [COMMAND_WORD]` +<<< + Example: Let's say you've forgotten how to add `Food` entries to your `Consumption Record`. You know there is a command called `nom`, @@ -463,6 +495,8 @@ As you can see, the `Help Window` popup now only shows the command guide for `no image::HelpCommandWithNomPopup.png[] // end::helpCommand[] +<<< + // tag::listcommand[] [[ListCommand]] === `list` : Listing all `Food` in current `Food Record` @@ -480,13 +514,15 @@ just as the `Food Record` previously appeared: **** [TIP] -You can think of this as the reverse of a `find` command. +You can think of this as the reverse of a <> command. After a `find` command, you are advised to complete your intended actions first, before using the `list` command to reset the display. This allows for a smoother workflow as you will now avoid the need to perform the same `find` command again. Format: `list` + (any parameters entered are ignored) +<<< + Example: Let's say you want to view all entries again after performing a `find n/Chicken` command. You can do the following: @@ -500,6 +536,7 @@ image::ListCommandAfter.png[] The `Result Display` will then indicate the result of your command, and the `Food Record` will now show all `Food` entries once again. // end::listcommand[] +<<< === `nom` : Adding `Food` to `Consumption Record` (by Ruicong) @@ -535,6 +572,8 @@ with a date that comes after today. Format: `nom n/NAME [d/DATE] [portion/PORTION][r/RATING]` +<<< + Example: Suppose you want to have a Cheeseburger today and have already stored its nutritional content @@ -550,8 +589,10 @@ image::NomCommandAfter.png[] Once you enter the command, the `Result Display` will inform you that the food has been consumed. The `Consumption Record` panel and `Graph Display` are updated to reflect your latest consumption. +<<< + [[report]] -=== `report` : Generating insights +=== `report` : Generating key statistics and insights (by Vineeth) Why stop at keeping track of your meals? Go a step further and use your past consumption patterns @@ -582,12 +623,16 @@ Refer to the list below for the various types of insights that you can easily ob * Insights on what your favourite `Food` is and whether it should continue to be in your diet. **** +<<< + Format: `report d/DATE` [NOTE] When entering the `report` command, do note there is a default behaviour for the `DATE` prefix. If you do not provide the date, or if its `Prefix` does not have a value, Calgo will by default take it that you intend to generate a report based on today's date. + + Example: Let's suppose you had a buffet on 27th of April 2020 and you managed to `nom` lots of exciting `Food` into your @@ -597,11 +642,15 @@ image::ReportCommandBefore.png[] First, type `report d/2020-04-27` and press kbd:[enter], as shown above. +<<< + image::SampleReport.png[] Second, go to the `data/reports` folder and open 2020-04-27_report.txt. You will see a report that looks similar to the one in the above screenshot. +<<< + The following steps breakdown what information is included in each section of the report. image::ReportHeader.png[] @@ -619,6 +668,8 @@ The third section is `Food-wise Statistics`. As the name suggests, this section In this case, you can see a variety of `Food` entries that you have tracked from your buffet experience. For each `Food` entry, the report displays the name of the `Food`, the total number of portions you consumed and the total amount of calories from that `Food`. You can use this information to realise what `Food` you may be over-consuming. +<<< + image::ReportAggregateStatistics.png[] The fourth section is `Aggregate Statistics`, which shows you the total amount of calories, protein, carbohydrates and fat that you have consumed on the given day. @@ -630,8 +681,12 @@ The fifth section is called `Insights for You`. In this section, Calgo uses your For you to continually improve your eating habits, Calgo, like any other friend, pushes you with motivating messages and congratulates you if you achieved the goal. In this case, as you exceeded the daily calorie goal by 959 calories, Calgo provides you with some reassurance that you can do better the next day to ensure that you do not give up. +<<< + image::ReportSuggestions.png[] + + The penultimate section is `Suggestions for You`. In this section, Calgo analyses your `Consumption Record` of the past week from the given date to find out what you can do to improve your eating habits. Calgo does this by using a mix of your ratings and quantity consumed of each `Food` to intelligently infer what your favourite `Food` is. It then analyses if you can continue to keep your favourite `Food` in the past week in your diet based on your daily calorie goal. Over time, through Calgo's smart suggestions, you will eventually have a diet consisting of your favourite `Food` entries that are compatible with your goal. How awesome is that! @@ -640,6 +695,8 @@ image::ReportFooter.png[] The final section is the `Report Footer`, which informs you that the report has concluded. This is the part where you realise that Calgo provides you with so many key insights in such a neatly organised and compact document. +<<< + === `stomach` : Showing all `Food` consumed on a particular day (by Ruicong) @@ -661,6 +718,8 @@ Here are some key pointers: Format: `stomach [d/DATE]` +<<< + Example: If you want to see what you have consumed on 12 April 2020, here's how you can do it: image::StomachCommandBefore.png[] @@ -673,6 +732,8 @@ The `Consumption Record` will display all the `Food` you have consumed on 12 Apr You can also see that `Daily Goal Display` has updated to show the amount of calories you have consumed on 12 April 2020, relative to your daily goal. +<<< + === `update` : Updating Calgo's `Food Record` (by Zhang Xian) @@ -695,6 +756,8 @@ Instead of naming your `Food` "Chocolate", perhaps "White Chocolate" or "Dark Ch Format: `update n/NAME cal/CALORIES p/PROTEINS c/CARBOHYDRATES f/FATS [t/TAGS]` +<<< + Examples: Example 1: Suppose you want to create a `Food` entry for Mee Goreng in Calgo. After searching online for the @@ -705,6 +768,8 @@ image::UpdateCommandNewBefore.png[] You should type `update n/Mee Goreng cal/418 p/8 c/58 f/17` and press kbd:[enter]. +<<< + image::UpdateCommandNewAfter.png[] Once the command has been entered, the `Result Display` shows the result of your command and the `Food Record` has been updated with a new `Food`, Mee Goreng. @@ -716,6 +781,8 @@ image::UpdateCommandExistingFoodBefore.png[] Type `update n/Mee Goreng cal/418 p/10 c/58 f/17` as input and press kbd:[enter]. +<<< + image::UpdateCommandExistingFoodAfter.png[] Once the command has been entered, the `Result Display` shows the result of your command and the `Food`, Mee Goreng, in @@ -729,12 +796,16 @@ image::UpdateCommandCapitaliseBefore.png[] You can then type `update n/char KUay TeoW cal/200 p/20 c/22 f/30 t/greasy` and press kbd:[enter]. +<<< + image::UpdateCommandCapitaliseAfter.png[] Calgo automatically formats the name of your `Food` for you to proper case. Hence, you see that instead of a hideous "char KUay TeoW" being updated into the `Food Record`, your new `Food` item is updated as "Char Kuay Teow". +<<< + === `vomit` : Removing portions of `Food` from `Consumption Record` (by Ruicong) @@ -763,6 +834,8 @@ which will be available from version 2.0 onwards. Format: `vomit num/INDEX [d/DATE] [portion/PORTION]` +<<< + Example: Let's say you ordered a glass of Bandung and previously used `nom` with `PORTION` set to 1. However, because the drink was too sweet, you only finished half a glass, you can use `vomit` to adjust your `Consumption Record`. Here's how you can do this: @@ -790,6 +863,8 @@ remove the json files in the `data` folder. These are system files. *Q*: How can I save the data I keyed into Calgo? + *A*: Calgo’s data is automatically saved into the computer after any command that changes the data. Manual saving isn't needed. +<<< + == Glossary *Case-insensitive*: Upper-case letters and lower-case letters are treated in the same manner. @@ -829,6 +904,9 @@ It can also contain optional tags. *Proper Case*: A format where words have all their first letters capitalised. (This Is An Example Of Proper Case). +<<< + +[[CommandSummary]] == Command Summary [width="100%",cols="17%,<18%,<20%,<25%,<20%",options="header",] @@ -867,6 +945,7 @@ It can also contain optional tags. .4+|Generate Document|Report|Generates consumption report for a given date.|`report d/DATE`|`report d/2020-04-20` |Export|Generates a neat and editable file containing the current `Food` entries.|`export`|- |======================================================================= + Please note the following: + * For the `clear`, `export`, and `list` commands, any parameters entered will be ignored. + diff --git a/docs/diagrams/GraphSequenceDiagram b/docs/diagrams/GraphSequenceDiagram.puml similarity index 100% rename from docs/diagrams/GraphSequenceDiagram rename to docs/diagrams/GraphSequenceDiagram.puml diff --git a/docs/images/DeleteActivityDiagram.png b/docs/images/DeleteActivityDiagram.png index cb10ca70c15..824caead7f7 100644 Binary files a/docs/images/DeleteActivityDiagram.png and b/docs/images/DeleteActivityDiagram.png differ diff --git a/docs/images/GoalActivityDiagram.png b/docs/images/GoalActivityDiagram.png new file mode 100644 index 00000000000..f3912a22ee8 Binary files /dev/null and b/docs/images/GoalActivityDiagram.png differ diff --git a/docs/images/NomActiivityDiagram.png b/docs/images/NomActiivityDiagram.png index c325703e6d1..8548af16a53 100644 Binary files a/docs/images/NomActiivityDiagram.png and b/docs/images/NomActiivityDiagram.png differ diff --git a/docs/images/OverallConsumptionActivityDiagram.png b/docs/images/OverallConsumptionActivityDiagram.png index 91eea60631a..b6468164bb8 100644 Binary files a/docs/images/OverallConsumptionActivityDiagram.png and b/docs/images/OverallConsumptionActivityDiagram.png differ diff --git a/docs/images/ReportFeatureSequenceDiagram.png b/docs/images/ReportFeatureSequenceDiagram.png index f51daaae3fb..2ba02a227d8 100644 Binary files a/docs/images/ReportFeatureSequenceDiagram.png and b/docs/images/ReportFeatureSequenceDiagram.png differ diff --git a/docs/images/UpdateActivityDiagram.png b/docs/images/UpdateActivityDiagram.png index 797df23fd7d..be6783d9a9c 100644 Binary files a/docs/images/UpdateActivityDiagram.png and b/docs/images/UpdateActivityDiagram.png differ diff --git a/docs/images/VomitCommandActivityDiagram.png b/docs/images/VomitCommandActivityDiagram.png index 72c7d782bc0..069fc2505e7 100644 Binary files a/docs/images/VomitCommandActivityDiagram.png and b/docs/images/VomitCommandActivityDiagram.png differ diff --git a/src/main/java/life/calgo/storage/ReportGenerator.java b/src/main/java/life/calgo/storage/ReportGenerator.java index d1e9eb75f60..3cda41c9b8b 100644 --- a/src/main/java/life/calgo/storage/ReportGenerator.java +++ b/src/main/java/life/calgo/storage/ReportGenerator.java @@ -75,7 +75,7 @@ public class ReportGenerator extends DocumentGenerator { + "Calgo advices you not to eat %s at all because it has \n way too many calories relative to your goal."; private static final String ADVICE_TO_CONTINUE = "Based on your goal, Calgo has verified that your favourite food," - + " %s,\n is sufficiently healthy! This means that it can continue to be a part of your diet."; + + " %s,\nis sufficiently healthy! This means that it can continue to be a part of your diet."; private static final String ADVICE_TO_EXERCISE = "Calgo has verified that your favourite food is preventing you " + "from reaching your daily goal.\n"