docstring and code cleanup

not sure how to test "game"...

include/caravan/core/training.h

@@ -36,9 +36,6 @@ typedef struct TrainConfig {
     uint32_t episode{0};
 } TrainConfig;
 
-std::uniform_int_distribution<uint8_t> dist_first_player(NUM_PLAYER_ABC, NUM_PLAYER_DEF);
-std::uniform_int_distribution<uint16_t> dist_action(0, SIZE_ACTION_SPACE - 1);
-std::uniform_real_distribution<float> dist_explore(0, 1);
 
 /*
  * FUNCTIONS

include/caravan/model/caravan.h

@@ -11,48 +11,132 @@
 #include "caravan/core/common.h"
 
 
+/**
+ * A caravan that contains all of the information for a given track of numeral
+ * cards and any face cards attached to them, including: the total caravan bid,
+ * its direction, and its suit.
+ */
 class Caravan {
 
 protected:
     CaravanName name;
     Track track;
     uint8_t i_track;
 
+    /**
+     * @param rank A numeral rank.
+     * @return An integer equivalent of the numeral, range: 1-10.
+     *
+     * @throws CaravanFatalException If a non-numeral rank is provided.
+     */
     static uint8_t numeral_rank_to_uint8_t(Rank rank);
 
+    /**
+     * @param index The index of the numeral card to remove from the caravan.
+     */
     void remove_numeral_card(uint8_t index);
 
 public:
     /**
-     * A caravan that contains all of the information for a given track of numeral
-     * cards and any face cards attached to them, including: the total caravan bid,
-     * its direction, and its suit.
-     *
-     * @param cvname The caravan name.
+     * @param cvname Caravan name.
      */
     explicit Caravan(CaravanName cvname) :
         name(cvname), track({}), i_track(0) {};
 
+    /**
+     * @return Caravan bid.
+     */
     uint16_t get_bid();
 
-    Slot get_slot(uint8_t pos);
-
+    /**
+     * @return Current caravan direction.
+     */
     Direction get_direction();
 
+    /**
+    * @return Caravan name.
+    */
     CaravanName get_name();
 
+    /**
+     * @return Current number of numeral cards in caravan.
+     */
     uint8_t get_size();
 
+    /**
+     * @param pos Caravan position.
+     * @return Slot at position.
+     * @throws CaravanGameException Chosen card position is out of range.
+     */
+    Slot get_slot(uint8_t pos);
+
+    /**
+     * @return Current caravan suit.
+     */
     Suit get_suit();
 
+    /**
+     * Remove all cards from the caravan.
+     * @param check_only If true, only check whether operation is valid;
+     *        if false, actually perform the operation.
+     * @return True if operation or check was successful; false otherwise.
+     * @throws CaravanGameException Caravan track is empty.
+     */
     bool clear(bool check_only = false);
 
-    bool put_numeral_card(Card card, bool check_only = false);
-
+    /**
+     * @param card Face card to put into caravan.
+     * @param pos Position of numeral card on which to put the face card.
+     * @param *target Stores a copy of the numeral card on which the face
+     *        card was placed into this pointer.
+     * @param check_only If true, only check whether operation is valid;
+     *        if false, actually perform the operation.
+     * @return True if operation or check was successful; false otherwise.
+     *
+     * @throws CaravanGameException Caravan position not entered.
+     * @throws CaravanGameException No numeral card at chosen position.
+     * @throws CaravanGameException Chosen card is not a face card.
+     * @throws CaravanGameException Numeral card at maximum face card capacity.
+     */
     bool put_face_card(Card card, uint8_t pos, Card *target = nullptr, bool check_only = false);
 
+    /**
+     * @param card Numeral card to put into caravan.
+     * @param check_only If true, only check whether operation is valid;
+     *        if false, actually perform the operation.
+     * @return True if operation or check was successful; false otherwise.
+     * @throws CaravanGameException Card is not a numeral.
+     * @throws CaravanGameException Caravan is at maximum numeral card capacity.
+     * @throws CaravanGameException Numeral card has same rank as most recent
+     *         card in caravan.
+     * @throws CaravanGameException Numeral does not follow caravan direction.
+     */
+    bool put_numeral_card(Card card, bool check_only = false);
+
+    /**
+     * Remove all numeral cards of a given rank.
+     *
+     * @param rank The rank to remove.
+     * @param pos_exclude The numeral card at the position will be excluded from
+     *                    removal. If 0, no card is excluded.
+     * @param check_only If true, only check whether operation is valid;
+     *        if false, actually perform the operation.
+     * @return True if operation or check was successful; false otherwise.
+     * @throws CaravanFatalException Exclude position is out of range.
+     */
     bool remove_rank(Rank rank, uint8_t pos_exclude, bool check_only = false);
 
+    /**
+     * Remove all numeral cards of a given suit.
+     *
+     * @param suit The suit to remove.
+     * @param pos_exclude The numeral card at the position will be excluded from
+     *                    removal. If 0, no card is excluded.
+     * @param check_only If true, only check whether operation is valid;
+     *        if false, actually perform the operation.
+     * @return True if operation or check was successful; false otherwise.
+     * @throws CaravanFatalException Exclude position is out of range.
+     */
     bool remove_suit(Suit suit, uint8_t pos_exclude, bool check_only = false);
 };
 

include/caravan/model/deck.h

@@ -9,13 +9,42 @@
 
 class DeckBuilder {
 protected:
+    /**
+     * @param shuffle If true, the deck is shuffled. If false, the deck is in
+     *        numeral order.
+     * @return A traditional deck: standard 52 cards + 2 JOKERs.
+     */
     static Deck build_traditional_deck(bool shuffle);
 
+    /**
+     * @param d The deck to shuffle.
+     * @return A deck with shuffled cards.
+     */
     static Deck shuffle_deck(Deck d);
 
 public:
     DeckBuilder() = delete;
 
+    /**
+     * @param num_cards The number of cards to have in the caravan deck,
+     *        must be between 30 and 162 cards (inclusive).
+     * @param num_sample_decks The number of standard card decks
+     *        (52 cards + 2 Jokers) from which to sample cards for the caravan
+     *        deck, must be between 1 and 3 (inclusive).
+     * @param balanced_sample If true, standard decks are sampled in a
+     *        round-robin fashion e.g. a random card from deck 1, then deck 2,
+     *        then 3, then 1, 2, 3, and so on. If false, then standard decks are
+     *        sampled randomly.
+     *
+     * @return A caravan deck.
+     *
+     * @throws CaravanFatalException Requested number of cards outside of
+     *         acceptable range.
+     * @throws CaravanFatalException Requested number of sample decks outside of
+     *         acceptable range.
+     * @throws CaravanFatalException Insufficient cards to sample in order to
+     *         build deck.
+     */
     static Deck *build_caravan_deck(
         uint8_t num_cards,
         uint8_t num_sample_decks,

include/caravan/model/game.h

@@ -23,13 +23,18 @@ class Game {
 
     bool has_sold(CaravanName cvname);
 
-    bool option_clear(Player *pptr, GameCommand *command, bool check_only);
+    bool option_clear(GameCommand *command, bool check_only);
 
-    bool option_discard(Player *pptr, GameCommand *command, bool check_only);
+    bool option_discard(GameCommand *command, bool check_only);
 
-    bool option_play(Player *pptr, GameCommand *command, bool check_only);
+    bool option_play(GameCommand *command, bool check_only);
 
 public:
+    /**
+     * @param config Game configuration.
+     *
+     * @throws CaravanFatalException Invalid player names.
+     */
     explicit Game(GameConfig *gc);
 
     ~Game();
@@ -40,19 +45,19 @@ class Game {
 
     PlayerCaravanNames get_player_caravan_names(PlayerName pname);
 
-    bool is_caravan_winning(CaravanName cvname);
-
-    bool is_caravan_bust(CaravanName cvname);
-
     PlayerName get_player_turn();
 
     Table *get_table();
 
     PlayerName get_winner();
 
+    bool is_caravan_bust(CaravanName cvname);
+
+    bool is_caravan_winning(CaravanName cvname);
+
     void play_option(GameCommand *command);
 
-    bool check_option(GameCommand *command);  // TODO
+    bool check_option(GameCommand *command);
 };
 
 #endif //CARAVAN_MODEL_GAME_H

include/caravan/model/table.h

@@ -25,12 +25,39 @@ class Table {
 
     ~Table();
 
+    /**
+     * @param cvname The caravan to get.
+     * @return Pointer to the caravan.
+     * @throws CaravanFatalException Invalid caravan name.
+     */
     Caravan *get_caravan(CaravanName cvname);
 
+    /**
+     * Remove all cards from the caravan.
+     * @param check_only If true, only check whether operation is valid;
+     *        if false, actually perform the operation.
+     * @return True if operation or check was successful; false otherwise.
+     */
     bool clear_caravan(CaravanName cvname, bool check_only = false);
 
+    /**
+     * @param cvname A caravan name.
+     * @param card A face card.
+     * @param pos The position of the numeral card on which to place the face card.
+     * @param check_only If true, only check whether operation is valid;
+     *        if false, actually perform the operation.
+     * @return True if operation or check was successful; false otherwise.
+     * @throws CaravanGameException QUEEN not played on latest numeral card in caravan.
+     */
     bool play_face_card(CaravanName cvname, Card card, uint8_t pos, bool check_only = false);
 
+    /**
+     * @param cvname A caravan name.
+     * @param card A numeral card to place in the caravan.
+     * @param check_only If true, only check whether operation is valid;
+     *        if false, actually perform the operation.
+     * @return True if operation or check was successful; false otherwise.
+     */
     bool play_numeral_card(CaravanName cvname, Card card, bool check_only = false);
 };
 

src/caravan/core/training.cpp

@@ -2,16 +2,9 @@
 // The following code can be redistributed and/or
 // modified under the terms of the GPL-3.0 License.
 
-#include <string>
-#include <array>
 #include <map>
-#include <iostream>
-#include <chrono>
-#include <vector>
 #include <random>
 #include <algorithm>
-#include "caravan/core/exceptions.h"
-#include "caravan/core/common.h"
 #include "caravan/model/game.h"
 #include "caravan/core/training.h"
 
@@ -146,6 +139,9 @@ void train_on_game(Game *game, QTable &q_table, ActionSpace &action_space, Train
     std::string action;
     GameCommand command;
     std::vector<std::string> invalid;
+
+    std::uniform_int_distribution<uint16_t> dist_action(0, SIZE_ACTION_SPACE - 1);
+    std::uniform_real_distribution<float> dist_explore(0, 1);
     bool explore = dist_explore(gen) < tc.explore;
 
     while (true) {

src/caravan/main.cpp

@@ -32,6 +32,7 @@ const std::string KEY_IMBALANCED = "imbalanced";
 const uint8_t FIRST_ABC = 1;
 const uint8_t FIRST_DEF = 2;
 
+// TODO docstrings in .h for all files
 
 int main(int argc, char *argv[]) {
     User *user_abc;