small refactoring and add documentation

8 files changed, 48 insertions, 14 deletions

diff --git a/oop2eindopdr/CacheManager.cpp b/oop2eindopdr/CacheManager.cpp
index c335de3..ff996af 100644
--- a/oop2eindopdr/CacheManager.cpp
+++ b/oop2eindopdr/CacheManager.cpp
@@ -8,7 +8,6 @@
 #include <thread>
 #include <chrono>
 
-CacheManager::CacheManager(const char* cache_path) : CacheManager(std::string(cache_path)) { }
 CacheManager::CacheManager(std::string cache_path) {
 	this->cache_path = cache_path;
 	this->verify_cache();
diff --git a/oop2eindopdr/CacheManager.h b/oop2eindopdr/CacheManager.h
index 9bd47e3..2aa8a39 100644
--- a/oop2eindopdr/CacheManager.h
+++ b/oop2eindopdr/CacheManager.h
@@ -13,11 +13,17 @@ private:
 	/** @brief pointers to open file handles */
 	std::vector<std::fstream*> files;
 
+	/** @brief max amount of attempts for `retry` */
 	const unsigned int max_tries = 100;
 
 	/**
 	 * @brief retry `action` as long as `retry_if` returns false, until `max_tries`
 	 *
+	 * this function runs `action` repeatedly until `retry_if` returns true, or
+	 * `action` has been called `max_tries` times. between each try, there is a
+	 * blocking 1ms delay, so this function should ideally only be used in
+	 * threads, or when `action` has a high probability of succeeding.
+	 *
 	 * @param label  this label gets printed if retry_count exceeds max_tries
 	 * @param check_pre  `true` = check `retry_if` before `action`, `false` = check `retry_if` after `action`
 	 * @param action  this gets executed as long as `retry_if` returns false
@@ -30,8 +36,8 @@ private:
 	virtual void retry_if(std::string label, std::function<void()> action, std::function<bool()> retry_if) { retry(label, true, action, retry_if); };
 public:
 	/** @brief initialize CacheManager class at `cache_path` */
-	CacheManager(const char* cache_path);
 	CacheManager(std::string cache_path);
+	CacheManager(const char* cache_path) { CacheManager(std::string(cache_path)); };
 	/** @brief close cache */
 	virtual ~CacheManager();
 	/** @brief create cache folder structure */
diff --git a/oop2eindopdr/DownloadManager.h b/oop2eindopdr/DownloadManager.h
index c98ae67..08cd7d8 100644
--- a/oop2eindopdr/DownloadManager.h
+++ b/oop2eindopdr/DownloadManager.h
@@ -4,11 +4,14 @@
 #include <thread>
 #include <vector>
 
+/** @brief manage threaded downloads */
 class DownloadManager {
 private:
 	const unsigned max_files = 50;
 
+	/** @brief download thread list */
 	std::vector<std::thread*> download_queue = {};
+	/** @brief fstream pointer list for limiting amount of files open at once */
 	std::vector<std::fstream*> file_queue = {};
 
 	/**
diff --git a/oop2eindopdr/Pokedex.h b/oop2eindopdr/Pokedex.h
index ec4ac26..d90bd73 100644
--- a/oop2eindopdr/Pokedex.h
+++ b/oop2eindopdr/Pokedex.h
@@ -24,15 +24,20 @@ private:
 
 	/** @brief cache connection */
 	CacheManager* cache = nullptr;
+	/** @brief api connection */
 	PokemonTCGAPIClient* api = nullptr;
+	/** @brief download manager */
 	DownloadManager* download_manager = nullptr;
 
+	/** @brief allow api access from PokemonCard::fetch_market_value */
 	friend class PokemonCard;
 
+	/** @brief search cache for cards matching query in id or name */
 	virtual std::vector<PokemonCard*> search_cards_local(std::string query);
+	/** @brief search API for cards matching query in id or name */
 	virtual std::vector<PokemonCard*> search_cards_remote(std::string query);
 
-	/** @brief convert std::string to lowercase */
+	/** @brief [utility] convert std::string to lowercase */
 	std::string lower(std::string input);
 
 public:
diff --git a/oop2eindopdr/PokemonCard.h b/oop2eindopdr/PokemonCard.h
index ea1a18f..1bbd3c7 100644
--- a/oop2eindopdr/PokemonCard.h
+++ b/oop2eindopdr/PokemonCard.h
@@ -10,19 +10,26 @@ class Pokedex;
 /** @brief single pokemon card */
 class PokemonCard {
 private:
+	/** @brief raw API card data */
 	nlohmann::json raw_data;
 
+	/** @brief load card data from json data (see named constructor) */
 	virtual void raw_load_json(nlohmann::json raw_data);
+	/** @brief load card data from cache (see named constructor) */
 	virtual void raw_load_cache(const char* cache_path);
 
+	/** @brief pokedex reference (for API access in ::fetch_market_value) */
 	Pokedex* pokedex = nullptr;
 
 	/** @brief add cache path before filename */
 	virtual std::string prefix_cache_path(const char* filename);
 
+	/** @brief thread that creates `complete` file when both images are downloaded */
 	std::thread* image_download_thread = nullptr;
 
+	/** @brief image API url */
 	std::string url_card_normal = "";
+	/** @brief image API url */
 	std::string url_card_hires = "";
 
 public:
@@ -38,6 +45,7 @@ public:
 	double value = 0.f; /** @brief pokemon card current market value */
 	std::vector<std::string> attacks = {}; /** @brief list of possible attacks */
 
+	/** @brief get short card identifier: "Name (ID)" */
 	virtual std::string short_identifier();
 
 	/** @brief use API to fetch `this->hp` */
diff --git a/oop2eindopdr/PokemonTCGAPIClient.cpp b/oop2eindopdr/PokemonTCGAPIClient.cpp
index 3285f6a..087296d 100644
--- a/oop2eindopdr/PokemonTCGAPIClient.cpp
+++ b/oop2eindopdr/PokemonTCGAPIClient.cpp
@@ -3,17 +3,11 @@
 #include <iostream>
 #include <cpr/cpr.h>
 
-PokemonTCGAPIClient::PokemonTCGAPIClient() {
-
-}
-
-PokemonTCGAPIClient::~PokemonTCGAPIClient() {
-
-}
+PokemonTCGAPIClient::PokemonTCGAPIClient() { }
+PokemonTCGAPIClient::~PokemonTCGAPIClient() { }
 
 nlohmann::json PokemonTCGAPIClient::raw_request(const char* endpoint, cpr::Parameters params) {
-	std::string full_url = API_URL;
-	full_url.append(endpoint);
+	std::string full_url = API_URL + std::string(endpoint);
 	cpr::Response res = cpr::Get(cpr::Url{full_url}, params);
 	return nlohmann::json::parse(res.text);
 }
diff --git a/oop2eindopdr/PokemonTCGAPIClient.h b/oop2eindopdr/PokemonTCGAPIClient.h
index cbbcf0d..9910425 100644
--- a/oop2eindopdr/PokemonTCGAPIClient.h
+++ b/oop2eindopdr/PokemonTCGAPIClient.h
@@ -13,15 +13,26 @@ public:
 
 private:
 	const char* API_URL = "https://api.pokemontcg.io/v2";
+	/**
+	 * @brief send http(s) GET request to `endpoint` with `params` and return the
+	 * response as parsed JSON
+	 */
 	virtual nlohmann::json raw_request(const char* endpoint, cpr::Parameters params);
+	/** @brief get minimal card info for parsing into card (no trading value) */
 	virtual nlohmann::json raw_get_cards(const char* query);
+	/** @brief get full card info by card id */
 	virtual nlohmann::json raw_get_card(const char* id);
+	/** @brief get list of valid sets */
 	virtual nlohmann::json raw_get_sets(const char* query);
 
 public:
+	/** @brief get list of cards that contain `query` in name or id field */
 	virtual std::vector<PokemonCard*> get_cards_by_query(const char* query);
+	/** @brief get list of cards in set */
 	virtual std::vector<PokemonCard*> get_set_cards(const char* set_name);
+	/** @brief get full card info by card id */
 	virtual PokemonCard* get_full_card(const char* id);
+	/** @brief get list of valid sets */
 	virtual std::vector<std::string> get_sets();
 };
 
diff --git a/oop2eindopdr/ZipExport.h b/oop2eindopdr/ZipExport.h
index 741ab4e..0800b41 100644
--- a/oop2eindopdr/ZipExport.h
+++ b/oop2eindopdr/ZipExport.h
@@ -5,20 +5,28 @@
 
 class Pokedex;
 
+/** @brief handle csv parsing and zip export */
 class ZipExport {
 private:
+	/** @brief reference to pokedex */
 	Pokedex* pokedex;
 
-	std::string csv_path, zip_path;
-	std::vector<std::string> id_list;
+	std::string csv_path; /** @brief input csv file path */
+	std::string zip_path; /** @brief output zip file path */
+	std::vector<std::string> id_list; /** @brief list of id's in csv file */
 
 public:
+	/** @brief create ZipExport */
 	ZipExport();
+	/** @brief create ZipExport class and immediately start export */
 	ZipExport(Pokedex* pokedex, std::string input_csv, std::string output_zip);
 	virtual ~ZipExport();
 
+	/** @brief set pokedex reference */
 	virtual void set_pokedex(Pokedex* pokedex);
 
+	/** @brief set csv_path and parse csv file */
 	virtual void import_csv(std::string filename);
+	/** @brief generate output export zip file */
 	virtual void export_zip(std::string filename);
 };