Docs: Various improvements on documentations and comments (#24)

* Improve in-code documentations

* Docs: Add doxygen configuration file

.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:

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

graph.h

@@ -1,8 +1,10 @@
 #ifndef GRAPH_H
 #define GRAPH_H
 #include <string>
+
+/** 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
+
+#endif

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<Stock> stocks_list, float balance) {
     // Create a table
@@ -53,15 +53,16 @@ void print_table(std::vector<Stock> 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<Stock> 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
     }
 

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();

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,25 +12,29 @@
 #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.
          */
         float purchase(float & balance, unsigned int amount, float trading_fees_percent);
 
         /**
          * 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<Stock_event> events;               /** List of events that will modify the stock */
-        std::map<stock_modifiers, float> attributes; /** The attributes of the stock */
-        std::vector<float> 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<Stock_event> events;
+        /** Stores the initial value of the stock_modifiers (e.g. standard deviation, mean and limits). */
+        std::map<stock_modifiers, float> attributes;
+        /** Contains the stock price history. First element (index 0) is the oldest. */
+        std::vector<float> 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);
 };