added more documentation

6 files changed, 95 insertions, 5 deletions

diff --git a/src/hand.c b/src/hand.c
index 24e9a9d..d6a047d 100644
--- a/src/hand.c
+++ b/src/hand.c
@@ -16,7 +16,7 @@ static int hand_comparator(const void *a, const void *b)
 
 /**
  * Sord the cards in a hand
- * @param[inout] h Pointer to hand that should be sorted
+ * @param[in,out] h Pointer to hand that should be sorted
  */
 void hand_sort(hand_t *h)
 {
@@ -27,7 +27,7 @@ void hand_sort(hand_t *h)
 
 /**
  * Removes a card from a hand by setting it to invalid value 0
- * @param[inout] h Hand to remove card from
+ * @param[in,out] 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)
diff --git a/src/main_stack.c b/src/main_stack.c
index 0e9639a..0482371 100644
--- a/src/main_stack.c
+++ b/src/main_stack.c
@@ -2,8 +2,8 @@
 #include <stdlib.h>
 
 /**
- * Initialize main stack: Assign valid cards and shuffle if
- * @param[inout] m Pointer to main stack
+ * Initialize main stack: Assign valid cards and shuffle it
+ * @param[in,out] m Pointer to main stack
  */
 void main_stack_init(main_stack_t *m)
 {
@@ -26,7 +26,7 @@ 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
+ * @param[in,out] m Pointer to main stack
  * @return Card on top of stack
  */
 card main_stack_remove_card(main_stack_t *m)
diff --git a/src/net/client.c b/src/net/client.c
index 409de6a..72d7322 100644
--- a/src/net/client.c
+++ b/src/net/client.c
@@ -59,6 +59,11 @@ int client_connect_server(const char* host, const char* port)
 	return sock;
 }
 
+/**
+ * Parse received list of players and fill global player list
+ * @param[in] m Received message
+ * @return Indicates success
+ */
 bool client_parse_player_list(const msg_t *m)
 {
 	assert(m != NULL);
@@ -83,6 +88,11 @@ bool client_parse_player_list(const msg_t *m)
 	return true;
 }
 
+/**
+ * Parse received hand and store it
+ * @param[in] m Received message
+ * @return Indicates success
+ */
 bool client_parse_deal_hand(const msg_t *m)
 {
 	assert(m != NULL);
@@ -96,6 +106,11 @@ bool client_parse_deal_hand(const msg_t *m)
 	return true;
 }
 
+/**
+ * Parse received index of a selected stack and store it
+ * @param[in] m Received message
+ * @return Indicates success
+ */
 bool client_parse_selected_stack(const msg_t *m)
 {
 	assert(m != NULL);
@@ -109,6 +124,11 @@ bool client_parse_selected_stack(const msg_t *m)
 	return true;
 }
 
+/**
+ * Parse received cards for initial stacks at beginning of game
+ * @param[in] m Received message
+ * @return Indicates success
+ */
 bool client_parse_initial_stacks(const msg_t *m)
 {
 	assert(m != NULL);
@@ -121,6 +141,11 @@ bool client_parse_initial_stacks(const msg_t *m)
 	return true;
 }
 
+/**
+ * Parse received open cards of all players
+ * @param[in] m Received message
+ * @return Indicates success
+ */
 bool client_parse_selected_card_all(const msg_t *m)
 {
 	assert(m != NULL);
@@ -137,6 +162,11 @@ bool client_parse_selected_card_all(const msg_t *m)
 	return true;
 }
 
+/**
+ * Parse received action for next round (whether new cards will be dealt ot the game is ending)
+ * @param[in] m Received message
+ * @return Indicates success
+ */
 bool client_parse_next_action(const msg_t *m)
 {
 	assert(m != NULL);
@@ -148,6 +178,11 @@ bool client_parse_next_action(const msg_t *m)
 	return true;
 }
 
+/**
+ * Parse received hello answer from server with assigned player id
+ * @param[in] m Received message
+ * @return Indicates success
+ */
 bool client_parse_hello(const msg_t *m)
 {
 	assert(m != NULL);
@@ -159,6 +194,10 @@ bool client_parse_hello(const msg_t *m)
 	return true;
 }
 
+/**
+ * Prepare hello message with client's nickname
+ * @param[out] m Pointer to message that should be filled
+ */
 void client_prep_hello(msg_t *m)
 {
 	data_store_t *ds = data_store();
@@ -168,6 +207,10 @@ void client_prep_hello(msg_t *m)
 	m->hdr.payload_length = namelen;
 }
 
+/**
+ * Prepare message with selected card
+ * @param[out] m Pointer to message that should be filled
+ */
 void client_prep_selected_card(msg_t *m)
 {
 	data_store_t *ds = data_store();
@@ -179,6 +222,10 @@ void client_prep_selected_card(msg_t *m)
 	m->hdr.payload_length = 1;
 }
 
+/**
+ * Prepare message with selected stack
+ * @param[out] m Pointer to message that should be filled
+ */
 void client_prep_selected_stack(msg_t *m)
 {
 	data_store_t *ds = data_store();
diff --git a/src/net/comm.c b/src/net/comm.c
index 7a67c27..0079a81 100644
--- a/src/net/comm.c
+++ b/src/net/comm.c
@@ -7,6 +7,13 @@
 #include "client.h"
 #include "server.h"
 
+/**
+ * Generic receive function.\n
+ * Receives specified message type from socket. Blocks until message is fully received.
+ * @param[in] Socket on which to receive
+ * @param[in] type Message type to receive
+ * @return Indicates success of receiving
+ */
 bool net_recv(const int sock, const msg_type_t type)
 {
 	msg_t m;
@@ -70,6 +77,14 @@ bool net_recv(const int sock, const msg_type_t type)
 	return result;
 }
 
+/**
+ * Generic send function.\n
+ * Transmits specified message type on socket.
+ * @param[in] Socket on which to send
+ * @param[in] type Message type to send
+ * @param[in] data Optional pointer to extra data needed by some message types
+ * @return Indicates success of sending
+ */
 bool net_send(const int sock, const msg_type_t type, const void *data)
 {
 	bool result = true;
diff --git a/src/player.c b/src/player.c
index cf587fc..4e7d5e9 100644
--- a/src/player.c
+++ b/src/player.c
@@ -2,6 +2,12 @@
 #include <stdlib.h>
 #include <assert.h>
 
+/**
+ * Search for a player in the player list
+ * @param[in] pl Pointer to player list to search
+ * @param[in] pid Player ID of searched player
+ * @return Pointer to player_list_entry_t; NULL if none found for specified player id
+ */
 player_list_entry_t *get_player_list_entry_by_player_id(player_list_t *pl, const player_id_t pid)
 {
 	assert(pl != NULL);
@@ -16,6 +22,9 @@ player_list_entry_t *get_player_list_entry_by_player_id(player_list_t *pl, const
 	return NULL;
 }
 
+/**
+ * Compare player list entries via open_card
+ */
 static int ple_open_card_comparator(const void *a, const void *b)
 {
 	player_list_entry_t ple1 = *(player_list_entry_t *)a;
@@ -24,6 +33,9 @@ static int ple_open_card_comparator(const void *a, const void *b)
 	return ple1.open_card - ple2.open_card;
 }
 
+/**
+ * Compare player list entries via score
+ */
 static int ple_score_comparator(const void *a, const void *b)
 {
 	player_list_entry_t ple1 = *(player_list_entry_t *)a;
@@ -32,6 +44,11 @@ static int ple_score_comparator(const void *a, const void *b)
 	return ple1.score - ple2.score;
 }
 
+/**
+ * Sort a player list in ascending order by open card values
+ * @param[in,out] pl Pointer to layer list to sort
+ * @param[in] num_entries Number of player list entries in list
+ */
 void player_list_sort_by_open_card(player_list_t *pl, const uint8_t num_entries)
 {
 	assert(pl != NULL);
@@ -39,6 +56,11 @@ void player_list_sort_by_open_card(player_list_t *pl, const uint8_t num_entries)
 	qsort(pl->players, num_entries, sizeof(player_list_entry_t), ple_open_card_comparator);
 }
 
+/**
+ * Sort a player list in ascending order by scores
+ * @param[in,out] pl Pointer to layer list to sort
+ * @param[in] num_entries Number of player list entries in list
+ */
 void player_list_sort_by_score(player_list_t *pl, const uint8_t num_entries)
 {
 	assert(pl != NULL);
diff --git a/src/table_stacks.c b/src/table_stacks.c
index c93d44a..6230a1f 100644
--- a/src/table_stacks.c
+++ b/src/table_stacks.c
@@ -5,6 +5,12 @@
 #include "card.h"
 #include "game.h"
 
+/**
+ * Search index of table stack in which specified card is in
+ * @param[in] stack_list Pointer to list of stacks to search
+ * @param[in] c Card to search
+ * @return Index of table stack with specified card; invalid index (NUM_TABLE_STACKS) if none found
+ */
 const uint8_t get_stack_idx_for_card(const table_stacks_t* stack_list, const card c)
 {
 	assert(stack_list != NULL);