From 74cd2a8db997d10cd9f89cf6c8683b4f5c0c443c Mon Sep 17 00:00:00 2001 From: "Cheng Ho Ming, Eric" Date: Wed, 17 Apr 2024 23:00:50 +0800 Subject: [PATCH] Docs: Various improvements on documentations and comments (#24) * Improve in-code documentations * Docs: Add doxygen configuration file --- .github/workflows/static.yml | 2 +- Doxyfile | 20 ++++++++++ graph.h | 10 +++-- main.cpp | 9 +++-- stock.cpp | 16 ++++---- stock.h | 71 ++++++++++++++++++++---------------- 6 files changed, 79 insertions(+), 49 deletions(-) create mode 100644 Doxyfile diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml index fa1fa105..4a62e778 100644 --- a/.github/workflows/static.yml +++ b/.github/workflows/static.yml @@ -37,7 +37,7 @@ jobs: run: | sudo apt-get update -y sudo apt-get install doxygen graphviz -y - doxygen main.cpp + doxygen Doxyfile - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 00000000..09c62c56 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,20 @@ +# Doxygen configuration file for Stock Market Simulator +PROJECT_NAME = "Stock Market Simulator" +BUILTIN_STL_SUPPORT = YES +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +QUIET = YES +USE_MDFILE_AS_MAINPAGE = README.md +# SOURCE_BROWSER = YES +VERBATIM_HEADERS = NO +# INLINE_SOURCES = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +HTML_TIMESTAMP = YES +GENERATE_TREEVIEW = YES +TREEVIEW_WIDTH = 200 +COMPACT_LATEX = YES +LATEX_TIMESTAMP = YES +CALL_GRAPH = YES +CALLER_GRAPH = YES +INTERACTIVE_SVG = YES diff --git a/graph.h b/graph.h index 5b770052..38455409 100644 --- a/graph.h +++ b/graph.h @@ -1,8 +1,10 @@ #ifndef GRAPH_H #define GRAPH_H #include + +/** Prints the graph of the stock price history to `std::cout`. + * @param stockname Name of the stock. + */ void graph_plotting(std::string stockname); -// input: stockname + stockname.log file -// return none -// output: print the graph of the stock price history -#endif \ No newline at end of file + +#endif diff --git a/main.cpp b/main.cpp index 94b2c163..238ddbcc 100644 --- a/main.cpp +++ b/main.cpp @@ -18,8 +18,8 @@ const float trading_fees_percent = 0.01; const int initial_stock_count = 20; /** Print the table of stocks. We put it in a function so we can call it multiple times. - * @param stocks_list The list of stocks to print. - * @param player The player object, for retrieving the player balance. + * @param stocks_list A vector of stocks. The stocks to be printed. + * @param balance How much money the player has. */ void print_table(std::vector stocks_list, float balance) { // Create a table @@ -53,15 +53,16 @@ void print_table(std::vector stocks_list, float balance) { std::cout << std::fixed << std::setprecision(2); } +/** Player's balance */ float balance = 1000; +/** Number of rounds played */ unsigned int rounds_played = 1; -// Main function +/** Main function, the entry point of the program */ int main(void) { std::vector stocks_list; // Create a vector of stocks for (int i = 0; i < initial_stock_count; i++) { Stock stock; - stock.init(); // Initialize the stock stocks_list.push_back(stock); // Add the stock to the vector } diff --git a/stock.cpp b/stock.cpp index 6f40af50..96faad7c 100644 --- a/stock.cpp +++ b/stock.cpp @@ -37,7 +37,7 @@ std::string Stock::category_name(void) { } unsigned int Stock::num_stocks_affordable(float balance, float trading_fees_percent) { - float value = balance / price * (1 + trading_fees_percent); + float value = balance / (price * (1 + trading_fees_percent)); return value < 0 ? 0 : (unsigned int)value; } @@ -104,28 +104,26 @@ float Stock::sum_attribute(stock_modifiers attribute) { return sum; } -void Stock::init(void) { +Stock::Stock(void) { /** @todo Follow-up */ category = random_integer(category_list_size); name = generate_name(category, 1)[0]; - // The distribution of initial stock price will be consistent across same categories + /** The distribution of initial stock price will be consistent across same categories + * Note that the value '3' is because currently init_stock_price has 3 possible input values. + */ price = init_stock_price(category % 3 + 1); quantity = 0; money_spent = 0; - /** @todo Move these attribute initialization to random_price.h - * Now we have to hardcode them here - */ + /** @todo Update the attributes via the functions provided by Jeremy in random_price.cpp */ attributes[standard_deviation] = 0.1; attributes[mean] = 0.1; - attributes[lower_limit] = 0; attributes[upper_limit] = 0; update_history(); } void Stock::next_round(void) { - /** @todo Follow-up */ - /** Update the stock price */ + /** @todo Use the functions provided by Jeremy in random_price.cpp to update the stock price. */ price += 0.1; /** Remove the obselete events */ remove_obselete_event(); diff --git a/stock.h b/stock.h index 2c3e816c..62e7efc5 100644 --- a/stock.h +++ b/stock.h @@ -1,7 +1,6 @@ /** * @headerfile stock.h * @author eric15342335 - * @brief Header file for the Stock class. */ #ifndef STOCK_H #define STOCK_H @@ -13,17 +12,21 @@ #include "events.h" /** - * A class that represents a stock object in the game. + * @class Stock + * @brief A class that represents a stock object in the game. * The stock has a name, price, quantity, category, money spent, events, attributes, and history. * The stock can be purchased, sold, and updated. */ class Stock { public: + /** Constructor of the Stock object. */ + Stock(void); + /** - * Purchase a given number of stocks - * @param balance The balance ($) of the player. Pass-by-reference + * Purchase a given number of stocks. + * @param balance The balance ($) of the player. Pass-by-reference. * @param amount The number of stocks to purchase. - * @param trading_fees_percent The trading fees percentage we charge the player + * @param trading_fees_percent The trading fees percentage we charge the player. * @return Successful: Total cost of the purchase. * Failed: -1 if the player does not have enough balance to buy the stock. */ @@ -31,7 +34,7 @@ class Stock { /** * Sell a given number of stocks. - * @param balance The balance ($) of the player. Pass-by-reference + * @param balance The balance ($) of the player. Pass-by-reference. * @param amount The number of stocks to sell. * @param trading_fees_percent The trading fees percentage we charge the player. * @return Successful: Amount of money the player receive. @@ -46,14 +49,6 @@ class Stock { */ unsigned int num_stocks_affordable(float balance, float trading_fees_percent); - /** - * Call this function to create a new stock. - * It assigns a random price, stock_attributes and category to it. - * Calls generate_name() from names.h to generate a name for the stock. - * Should be called only once. - */ - void init(void); - /** * Return the name of the caategory the stock belongs to. * @return Name of the category as a string. @@ -72,8 +67,11 @@ class Stock { float delta_price_percentage(void); /** - * Get the total change of attribute of the stock due to events only. Getter function. - * Example usage: stock.get_attribute(stock_modifiers::offset); + * Get the total change of attribute of the stock due to events only. Getter function. \n + * Example usage: + * ``` + * stock.get_attribute(stock_modifiers::offset); + * ``` * @param attribute The attribute to get. * @return Total change of attribute due to Stock_event. Does not include the base value. */ @@ -179,21 +177,32 @@ class Stock { } private: - std::string name; /** name of the stock */ - float price; /** current price of the stock */ - unsigned int quantity; /** number of stocks player has */ - unsigned int category; /** stores category numbers, where the names are stored in names.h */ - float money_spent; /** total money spent on purchasing the stock */ - - std::list events; /** List of events that will modify the stock */ - std::map attributes; /** The attributes of the stock */ - std::vector history; /** The history of stock prices */ - - void update_history(void); /** Update the history array with the current price */ - - /** - * Remove obselete events that has duration <= 0 - * Internal use after the "next_round" function is called + /** Name of the stock that we assigned to it. */ + std::string name; + /** Current price of the stock. */ + float price; + /** Number of stocks the player has purchased. */ + unsigned int quantity; + /** Use numbers to represent the category of the stock. The range of the numbers + * should be `[0, category_list_size - 1]`. See names.cpp for more information. + */ + unsigned int category; + /** Amount of money the player has spent on buying this stock. */ + float money_spent; + + /** Stores all the events that will apply to this stock specifically. */ + std::list events; + /** Stores the initial value of the stock_modifiers (e.g. standard deviation, mean and limits). */ + std::map attributes; + /** Contains the stock price history. First element (index 0) is the oldest. */ + std::vector history; + + /** Update the history array with the current price */ + void update_history(void); + + /** Remove obselete events from the list `events` that durations are + * less than/equal to 0 (In other words, expired). + * For internal use after the `Stock::next_round` function is called. */ void remove_obselete_event(void); };