From 947669f063f3df9fc93a4afb2d7c9e6d3d13813a Mon Sep 17 00:00:00 2001 From: Reiner Herrmann Date: Sat, 29 Jan 2011 15:34:18 +0100 Subject: added documentation --- src/card.c | 8 ++++++++ src/data_store.c | 8 ++++++++ src/game.c | 18 ++++++++++++++++++ src/hand.c | 17 +++++++++++++++++ src/main.c | 4 ++++ src/main_stack.c | 14 ++++++++++++++ 6 files changed, 69 insertions(+) (limited to 'src') diff --git a/src/card.c b/src/card.c index 25db247..5132be6 100644 --- a/src/card.c +++ b/src/card.c @@ -1,6 +1,14 @@ #include "card.h" #include +/** + * Calculate the score of a single card + * Cards divisible by 5: 2 points + * Cards divisible by 10: 3 points + * Cards divisible by 11: 5 points + * Card 55 (divisible by 5 and 11): 7 points + * @return Score of the card + */ uint32_t card_get_points(const card c) { assert(c > 0 && c <= 105); diff --git a/src/data_store.c b/src/data_store.c index eb8cb86..3d5d440 100644 --- a/src/data_store.c +++ b/src/data_store.c @@ -6,6 +6,11 @@ static data_store_t *d = NULL; // returns global data store +/** + * Returns pointer to global data_store object. + * Creates it at first call. + * @return Pointer to global data_store + */ data_store_t* data_store(void) { if(!d) @@ -17,6 +22,9 @@ data_store_t* data_store(void) return d; } +/** + * Free memory of global data_store + */ void destroy_data_store(void) { free(d); diff --git a/src/game.c b/src/game.c index 5cb947d..f714567 100644 --- a/src/game.c +++ b/src/game.c @@ -17,6 +17,11 @@ #include "game_states.h" #include "main_stack.h" +/** + * Game loop for clients. + * Runs from game start to its end + * @param[in] sock Socket with connection to server + */ static void main_loop_client(int sock) { bool running = true; @@ -56,6 +61,11 @@ static void main_loop_client(int sock) } } +/** + * Game loop for server. + * Runs from game start to its end + * @param[in] client_socks Sockets with connection to connected clients + */ static void main_loop_server(socket_list_t* client_socks) { bool running = true; @@ -93,6 +103,14 @@ static void main_loop_server(socket_list_t* client_socks) } } +/** + * Prepares the start of a game. Clients connect to server and in servermode a server + * is started which accepts connections + * @param[in] servermode True if a server should be started to where the local client will connect + * @param[in] addr Hostname/address where a client should try to connect (if NULL, default is "localhost"); in servermode address to which server will bind + * @param[in] port Port to connect to / listen on + * @param[in] num_players Only required on server; number of connections that are accepted before game is starting + */ void start_game(const bool servermode, const char* addr, const char* port, const uint8_t num_players) { assert(port != NULL); // addr can be NULL for server -> listen on every address diff --git a/src/hand.c b/src/hand.c index 359ed08..24e9a9d 100644 --- a/src/hand.c +++ b/src/hand.c @@ -3,6 +3,9 @@ #include #include "card.h" +/** + * Compares two hands; used for sorting them in hand_sort + */ static int hand_comparator(const void *a, const void *b) { card c1 = *(card *)a; @@ -11,6 +14,10 @@ static int hand_comparator(const void *a, const void *b) return c1 - c2; } +/** + * Sord the cards in a hand + * @param[inout] h Pointer to hand that should be sorted + */ void hand_sort(hand_t *h) { assert(h != NULL); @@ -18,6 +25,11 @@ void hand_sort(hand_t *h) qsort(h->cards, MAX_HAND_CARDS, sizeof(card), hand_comparator); } +/** + * Removes a card from a hand by setting it to invalid value 0 + * @param[inout] h Hand to remove card from + * @param[in] card_index Index of card to remove + */ void hand_remove_card(hand_t *h, const uint8_t card_index) { assert(h != NULL); @@ -25,6 +37,11 @@ void hand_remove_card(hand_t *h, const uint8_t card_index) h->cards[card_index] = 0; } +/** + * Count number of valid cards in hand + * @param[in] h Hand to count + * @return Number of valid cards in hand + */ const uint8_t hand_count_cards(const hand_t* h) { uint8_t count = 0; diff --git a/src/main.c b/src/main.c index cda9f29..1828e60 100644 --- a/src/main.c +++ b/src/main.c @@ -8,6 +8,10 @@ #define DEFAULT_PORT "12345" +/** + * Print usage information + * @param[in] name The name of the program (normally argv[0]) + */ static void print_usage(const char* name) { const char* usage = "Usage: %s [-u username] [-s address] [-n num_players] [-l] [-p port] [-m]\n" diff --git a/src/main_stack.c b/src/main_stack.c index bae4a88..0e9639a 100644 --- a/src/main_stack.c +++ b/src/main_stack.c @@ -1,6 +1,10 @@ #include "main_stack.h" #include +/** + * Initialize main stack: Assign valid cards and shuffle if + * @param[inout] m Pointer to main stack + */ void main_stack_init(main_stack_t *m) { assert(m != NULL); @@ -20,6 +24,11 @@ void main_stack_init(main_stack_t *m) } } +/** + * Draw card on top of main stack and mark it as removed + * @param[inout] m Pointer to main stack + * @return Card on top of stack + */ card main_stack_remove_card(main_stack_t *m) { assert(m != NULL); @@ -35,6 +44,11 @@ card main_stack_remove_card(main_stack_t *m) return 0; // stack empty } +/** + * Returns number of cards remaining in main stack + * @param[in] m Pointer to main stack + * @return Number of cards in stack + */ uint8_t main_stack_size(const main_stack_t *m) { assert(m != NULL); -- cgit v1.2.3