Rewrote api and info header documentation

2 files changed, 140 insertions, 65 deletions

diff --git a/api.h b/api.h
index a8ac36745fe3..9ad31595b9a9 100644
--- a/api.h
+++ b/api.h
@@ -1,12 +1,12 @@
 /**
- * API data is taken from IEX Trading, Morningstar, Coinmarketcap.
+ * API data is taken from IEX Trading, Morningstar, and Coinmarketcap.
  * https://iextrading.com/developer/docs/
  * http://www.morningstar.com/
- * https://coinmarketcap.com/api/
+ * https://coinmarketcap.com/api/documentation/v1
  */
 
-#ifndef API_H
-#define API_H
+#ifndef TICK_API_H
+#define TICK_API_H
 
 #define QUARTERS 4
 #define DATE_MAX_LENGTH 16
@@ -23,42 +23,54 @@
 
 typedef struct info {
     /* Company */
-    char symbol[SYMBOL_MAX_LENGTH]; // Symbol of security (ex. AAPL)
-    char name[INFO_TEXT_MAX]; // Name of security (ex. Apple Inc.)
-    char industry[INFO_TEXT_MAX];
-    char website[URL_MAX_LENGTH];
-    char description[INFO_TEXT_MAX]; // Description of company
-    char ceo[INFO_TEXT_MAX];
-    char issue_type[3];
-    char sector[INFO_TEXT_MAX];
+    char symbol[SYMBOL_MAX_LENGTH];     // ex. AAPL
+    char name[INFO_TEXT_MAX];           // ex. Apple Inc.
+    char industry[INFO_TEXT_MAX];       // ex. Computer Hardware
+    char website[URL_MAX_LENGTH];       // ex. apple.com
+    char description[INFO_TEXT_MAX];    // Paragraph description of company
+    char ceo[INFO_TEXT_MAX];            // ex. Timothy D. Cook
+    char issue_type[3];                 /* ad – American Depository Receipt (ADR’s)
+                                           re – Real Estate Investment Trust (REIT’s)
+                                           ce – Closed end fund (Stock and Bond Fund)
+                                           si – Secondary Issue
+                                           lp – Limited Partnerships
+                                           cs – Common Stock
+                                           et – Exchange Traded Fund (ETF)
+                                           (blank) = Not Available, i.e., Warrant, Note, or (non-filing)
+                                           Closed Ended Funds
+                                            */
+    char sector[INFO_TEXT_MAX];         // ex. Technology
 
     /* Quote */
-    int64_t intraday_time; // unix time
-    double price; // Current price of security in USD (ex. 174.54)
-    int64_t marketcap; // Market cap in USD (ex. 890489000000)
-    int64_t volume_1d; // Volume in shares of security (ex. 33812360)
-    double pe_ratio;
+    int64_t intraday_time;              // Unix timestamp of current price
+    double price;                       // Current price of security in USD (ex. 174.54)
+    int64_t marketcap;                  // Market cap in USD (ex. 890489000000)
+    int64_t volume_1d;                  // Volume in shares of security (ex. 33812360)
+    double pe_ratio;                    // Price per earnings ratio
 
     /* Stats */
-    double div_yield; // Percent dividend yield (ex. 1.46)
-    int64_t revenue;
-    int64_t gross_profit;
-    int64_t cash;
-    int64_t debt;
+    double div_yield;                   // Percent dividend yield (ex. 1.46)
+    int64_t revenue;                    // Revenue in dollars
+    int64_t gross_profit;               // Gross Profit in dollars
+    int64_t cash;                       // Cash in dollars
+    int64_t debt;                       // Debt in dollars
 
     /* Earnings */
-    double eps[QUARTERS];
-    char fiscal_period[QUARTERS][DATE_MAX_LENGTH];
-    double eps_year_ago[QUARTERS];
+    double eps[QUARTERS];               // Earnings per share per quarter for past four quarters
+    char fiscal_period[QUARTERS][DATE_MAX_LENGTH];  // Quarter and Year of past four quarters (ex. Q1 2018)
+    double eps_year_ago[QUARTERS];      // Earnings per share per quarter for the previous year
 
     /* Chart */
-    double change_1d, change_7d, change_30d; // Percent change in the past x days (ex. -7.49)
-    double* points; // 5y
+    double change_1d;                   // Percent change since last close
+    double change_7d;                   // Percent change since 7 days ago
+    double change_30d;                  // Percent change since 30 days ago
+    double* points;                     // Array of one price per day, startings five years previously
 } Info;
 
 /**
- * Creates and returns an Info object. name and symbol are allocated 64 bytes. the doubles and long are set to EMPTY
- * @return Info object
+ * Allocates an Info struct and returns a pointer to it. All numbers are set to EMPTY, all strings are NULL
+ * terminated at length 0, and all pointers are set to NULL.
+ * @return Info*
  */
 Info* api_info_init(void);
 
@@ -69,65 +81,127 @@ Info* api_info_init(void);
 size_t api_string_writefunc(void* ptr, size_t size, size_t nmemb, String* pString);
 
 /**
- * If post_field is not NULL, performs a HTTP POST with the given parameters. Otherwise, performs a HTTP GET. Response
- * data is stored and returned in a String.
- * @param url API url to GET/POST
- * @return NULL if no response from server. Otherwise, String containing data.
+ * Performs a HTTP GET. Response data is stored and returned in an allocated String*.
+ * @param url API url to GET
+ * @return NULL if error or no response from server. Otherwise, String* containing data.
  */
 String* api_curl_data(const char* url);
 
+/**
+ * Designed for threading
+ *
+ * Queries IEX's company endpoint and stores the data in the Info object pointed to by vpInfo. symbol, name,
+ * industry, website, description, ceo, issue_type, and sector are stored.
+ * @param vpInfo Info*
+ * @return NULL
+ */
 void* iex_store_company(void* vpInfo);
 
+/**
+ * Designed for threading
+ *
+ * Queries IEX's quote endpoint and stores the data in the Info object pointed to by vpInfo. intraday_time, price,
+ * marketcap, volume_1d, and pe_ratio are stored.
+ * @param vpInfo Info*
+ * @return NULL
+ */
 void* iex_store_quote(void* vpInfo);
 
+/**
+ * Designed for threading
+ *
+ * Queries IEX's stats endpoint and stores the data in the Info object pointed to by vpInfo. div_yield, revenue,
+ * gross_profit, cash, and debt are stored.
+ * @param vpInfo Info*
+ * @return NULL
+ */
 void* iex_store_stats(void* vpInfo);
 
+/**
+ * Designed for threading
+ *
+ * Queries IEX's stats earnings and stores the data in the Info object pointed to by vpInfo. eps, fiscal_period, and
+ * eps_year_ago are stored.
+ * @param vpInfo Info*
+ * @return NULL
+ */
 void* iex_store_earnings(void* vpInfo);
 
+/**
+ * Designed for threading
+ *
+ * Queries IEX's chart endpoint and stores the data in the Info object pointed to by vpInfo. change_1d, change_7d,
+ * change_30d, and points are stored.
+ * @param vpInfo Info*
+ * @return NULL
+ */
 void* iex_store_chart(void* vpInfo);
 
+/**
+ * Designed for threading
+ *
+ * Queries Morningstar's API and stores the data in the Info object pointed to by vpInfo. price, change_1d,
+ * change_7d, change_30d, points, and volume_1d are stored.
+ * @param vpInfo Info*
+ * @return NULL
+ */
 void* morningstar_store_info(void* vpInfo);
 
+/**
+ * Designed for threading
+ *
+ * Queries Coinmarketcaps's API and stores the data in the Info object pointed to by vpInfo. name, symbol, price,
+ * change_1d, change_7d, marketcap, and volume_1d are stored.
+ * @param vpInfo Info*
+ * @return NULL
+ */
 void* coinmarketcap_store_info(void* vpInfo);
 
 /**
- * Returns a pointer to an Info object containing info pertaining
- * to the given symbol with data from IEX.
+ * Returns a pointer to an Info object containing info pertaining to the given symbol with data from IEX.
  * @param symbol stock/etf symbol
- * @return Info object
+ * @return Info* if valid stock/etf or NULL otherwise
  */
 Info* iex_get_info(const char* symbol);
 
 /**
- * Returns a pointer to an Info object containing info pertaining
- * to the given symbol with data from Morningstar
+ * Returns a pointer to an Info object containing info pertaining to the given symbol with data from Morningstar.
  * @param symbol mutf/otc symbol
- * @return Info object
+ * @return Info* if valid mutf/otc or NULL otherwise
  */
 Info* morningstar_get_info(const char* symbol);
 
 /**
- * Returns a pointer to an Info object containing info pertaining to the given cryptocurrency from Coinmarketcap.
- * @param symbol the crypto's name
- * @return Info object
+ * Returns a pointer to an Info object containing info pertaining to the given symbol with data from Coinmarketcap.
+ * @param symbol name of cryptocurrency
+ * @return Info* if valid name of cryptocurrency or NULL otherwise
  */
 Info* coinmarketcap_get_info(const char* symbol);
 
 /**
- * Returns a double* containing the current price and yesterday's price of a stock or cryptocurrency.
- * [0] = current intraday price
- * [1] = last close price
- * [2] = close price 5 trading days previously
+ * Returns an Info* populated with information pertaining to the given symbol.
  * The function will first query IEX. If no response, it will query Morningstar. If no response, it will query
  * Coinmarketcap. If Coinmarketcap returns NULL, the function returns NULL.
  * 1. IEX -- NASDAQ/NYSE/NYSEARCA
  * 2. Morningstar -- MUTF/OTCMKTS
  * 3. Coinmarketcap -- CRYPTO
- * @param symbol security symbol or name to get prices of
- * @return price data or NULL if invalid symbol
+ *
+ * In the case of using IEX, only the Quote and Chart sections will be populated.
+ * @param symbol
+ * @return Info* or NULL if invalid symbol
  */
 Info* api_get_check_info(const char* symbol);
 
+/**
+ * Returns an Info* populated with information pertaining to the given symbol.
+ * The function will first query IEX. If no response, it will query Morningstar. If no response, it will query
+ * Coinmarketcap. If Coinmarketcap returns NULL, the function returns NULL.
+ * 1. IEX -- NASDAQ/NYSE/NYSEARCA
+ * 2. Morningstar -- MUTF/OTCMKTS
+ * 3. Coinmarketcap -- CRYPTO
+ * @param symbol
+ * @return Info* or NULL if invalid symbol
+ */
 Info* api_get_info(const char* symbol);
 
 /**
diff --git a/info.h b/info.h
index abc0372a99b4..17679ca7500d 100644
--- a/info.h
+++ b/info.h
@@ -36,28 +36,29 @@
 
 extern int zoom_months[9], zoom_change_x_months[9];
 
-
 /**
- * Prints information about the symbol ticker_name_string by calling the function json_print_news.
+ * Prints information about the given symbol and the graph of it in an NCurses window.
  * @param symbol
  */
 void symbol_print_info(const char* symbol);
 
-
 /**
- * Prints the top three news articles by popularity pertaining to the given string, ticker_name_string. Spaces and
- * underscores will be url-encoded (replaced by "%20"). News API will be used for data.
- * @param symbol the string to query
+ * Prints num_articles articles relating to the given symbol. Currently on works for stocks/etfs
+ * @param symbol stock/etf symbol
+ * @param num_articles number of articles to print (max 50)
  */
 void symbol_print_news(const char* symbol, int num_articles);
 
+/**
+ * Graphs a security in stdscr. If symbol2 is not NULL, also graphs that security.
+ * @param symbol security to graph
+ * @param symbol2 optional second security
+ */
 void symbol_graph(const char* symbol, const char* symbol2);
 
 /**
  * -- Main input loop for graphing --
- *
- * Gets the five year history of the given security(s) and calls graph_print to initially display a graph of it/them.
- * If symbol2 is NULL, only displays the graph for symbol.
+ * Graphs a secuturity or securities in the given window.
  * The user may input keystrokes to manipulate the graph(s).
  * Valid keystrokes:
  * q: Quits program
@@ -65,22 +66,22 @@ void symbol_graph(const char* symbol, const char* symbol2);
  * DOWN: decreases zoom level by one and moves start date backward by one year, three months, or two months.
  * LEFT: moves start date backward by one year, three months, or one month.
  * RIGHT: moves start date forward by one year, three months, or one month.
- * @param symbol first symbol
- * @param symbol2 second symbol
+ * @param window the window to print to
+ * @param symbol_info Info* containing points
+ * @param symbol_info2 optional Info* containing points
  */
 void graph_printw(WINDOW* window, Info* symbol_info, Info* symbol_info2);
 
 /**
- * Prints out a NCurses based graph given an array of daily close prices.
- * If points2 if not NULL, also prints a graph of its data in a different color.
+ * Prints out a NCurses based graph given an Info*.
+ * If symbol_info2 if not NULL, also prints a graph of its data in a different color.
  * x-axis -- date
  * y-axis -- close price
- * @param points daily close prices of past five years of first security
- * @param points2 daily close prices of past five years of second security
+ * @param window the window to print to
+ * @param symbol_info Info* containing points
+ * @param symbol_info2 optional Info* containing points
  * @param start_time the starting date of prices to print
  * @param zoom the zoom level
- * @param symbol first symbol
- * @param symbol2 second symbol
  */
 void graph_draw(WINDOW* window, Info* symbol_info, Info* symbol_info2, struct tm* start_time, int zoom);