Merge branch 'master' of ssh://icarus-git/~git/oxen

5 files changed, 61 insertions, 25 deletions

diff --git a/src/card_stack.c b/src/card_stack.c
index 13b14dd..f3bd217 100644
--- a/src/card_stack.c
+++ b/src/card_stack.c
@@ -2,6 +2,10 @@
 #include <assert.h>
 #include <stdlib.h>
 
+/**
+ * Calculates the points of a card stack. This will be the sum of the points of all cards contained in the card stack.
+ * @param[in] cs The card stack fir which the points will be calculated
+*/
 uint32_t card_stack_get_points(const card_stack_t *cs)
 {
 	assert(cs != NULL);
@@ -17,11 +21,15 @@ uint32_t card_stack_get_points(const card_stack_t *cs)
 	return points;
 }
 
-const card card_stack_upper_card(const card_stack_t *cs)
+/**
+ * Determines the uppermost card on a card stack. The card will not be removed from the stack.
+ * @param[in] cs The card stack from which the uppermost card will be retrieved
+*/
+const card card_stack_top(const card_stack_t *cs)
 {
 	assert(cs != NULL);
 
-	for(int i=0; i<MAX_CARD_STACK_SIZE; i++)
+	for(int i = 0; i < MAX_CARD_STACK_SIZE; i++)
 	{
 		card cur = cs->cards[MAX_CARD_STACK_SIZE-1-i];
 		if(cur != 0)
@@ -31,13 +39,35 @@ const card card_stack_upper_card(const card_stack_t *cs)
 	return 0;
 }
 
-void card_stack_clear(card_stack_t *cs, const card new_card)
+/**
+ * Places a card on top of a card stack.
+ * @param[in] cs The card stack to place the card on
+ * @param[in] c The card to place
+*/
+void card_stack_push(card_stack_t *cs, const card c)
 {
 	assert(cs != NULL);
 
-	for(int i=0; i<MAX_CARD_STACK_SIZE; i++)
+	for(int i = 0; i < MAX_CARD_STACK_SIZE; i++)
+	{
+		if(cs->cards[i] != 0)
+			continue;
+		cs->cards[i] = c;
+		break;
+	}
+}
+
+/**
+ * Replaces a card stack with a single card. All cards within the card stack will be removed adn the first card will be set to a given card.
+ * @param[in] cs The card stack to replace
+ * @param[in] new_card The new first card
+*/
+void card_stack_replace(card_stack_t *cs, const card new_card)
+{
+	assert(cs != NULL);
+
+	for(int i = 0; i < MAX_CARD_STACK_SIZE; i++)
 		cs->cards[i] = 0;
 
 	cs->cards[0] = new_card;
 }
-
diff --git a/src/card_stack.h b/src/card_stack.h
index 61d2bf2..7e1d976 100644
--- a/src/card_stack.h
+++ b/src/card_stack.h
@@ -12,7 +12,8 @@ typedef struct
 } card_stack_t;
 
 uint32_t card_stack_get_points(const card_stack_t *cs);
-const card card_stack_upper_card(const card_stack_t *cs);
-void card_stack_clear(card_stack_t *cs, const card new_card);
+const card card_stack_top(const card_stack_t *cs);
+void card_stack_push(card_stack_t *cs, const card c);
+void card_stack_replace(card_stack_t *cs, const card new_card);
 
 #endif // OXEN_CARD_STACK_H
diff --git a/src/client_game_states.c b/src/client_game_states.c
index 4fa4266..686acb6 100644
--- a/src/client_game_states.c
+++ b/src/client_game_states.c
@@ -80,7 +80,7 @@ game_state_t state_client_play_cards(const int sock)
 
 			net_recv(sock, msg_type_selected_stack_s);
 			ds->player_list.players[i].score += card_stack_get_points(&ds->table_stacks.stacks[ds->stack_index]);
-			card_stack_clear(&ds->table_stacks.stacks[ds->stack_index], c);
+			card_stack_replace(&ds->table_stacks.stacks[ds->stack_index], c);
 		}
 		else // card fits on a stack -> place it
 		{
@@ -88,19 +88,10 @@ game_state_t state_client_play_cards(const int sock)
 			if(cs->cards[MAX_CARD_STACK_SIZE-1] != 0) // stack is full
 			{
 				ds->player_list.players[i].score += card_stack_get_points(cs);
-				card_stack_clear(cs, c);
+				card_stack_replace(cs, c);
 			}
 			else
-			{
-				// put open card on top of stack
-				for(int j=0; j<MAX_CARD_STACK_SIZE; j++)
-				{
-					if(cs->cards[j] != 0)
-						continue;
-					cs->cards[j] = c;
-					break;
-				}
-			}
+				card_stack_push(cs, c);
 		}
 	}
 
diff --git a/src/net/server.c b/src/net/server.c
index 335cea6..c45c796 100644
--- a/src/net/server.c
+++ b/src/net/server.c
@@ -25,7 +25,7 @@ int socket_for_player_id(const socket_list_t *client_socks, const player_id_t pi
 }
 
 /**
- * Server side function; start server on specified port
+ * Starts the server. The server will listen on a specified port.
  * @param[in] port Port on which server should listen
  * @return Listening socket
  */
@@ -89,7 +89,7 @@ int server_start(const char* port)
 }
 
 /**
- * Server side function; accepts connections from clients
+ * Waits for and accepts connections from clients. Each client connection is represented by a socket that will be stored in a list for further communication.
  * @param[in] serversock Socket on which server is listening
  * @param[out] client_socks Socket list in which to store open client connections
  * @param[in] count Number of clients that should connect
@@ -118,9 +118,9 @@ void server_get_players(int serversock, socket_list_t* client_socks, const uint8
 }
 
 /**
-  * Server side function; receive hello message from client and read username
-  * @param[in] sock Socket to use
-  * @return Username of client
+  * Parses hello message from client and store username in the global data store.
+  * @param[in] msg The message to parse
+  * @return true
   */
 bool server_parse_hello(const msg_t *m)
 {
@@ -141,6 +141,11 @@ bool server_parse_hello(const msg_t *m)
 	return true;
 }
 
+/**
+  * Parses open card message from client and stores the selected card in the global data store.
+  * @param[in] msg The message to parse
+  * @return true
+  */
 bool server_parse_selected_card(const msg_t *m)
 {
 	assert(m != NULL);
@@ -152,6 +157,11 @@ bool server_parse_selected_card(const msg_t *m)
 	return true;
 }
 
+/**
+  * Parses selected stack message from client and stores the stack index in the global data store.
+  * @param[in] msg The message to parse
+  * @return true
+  */
 bool server_parse_selected_stack(const msg_t *m)
 {
 	assert(m != NULL);
@@ -165,6 +175,10 @@ bool server_parse_selected_stack(const msg_t *m)
 	return true;
 }
 
+/**
+  * Prepares start game message. All player IDs, player names and name lengths will be saved in the message payload.
+  * @param[out] msg A preallocated message object to store header and payload information
+  */
 void server_prep_start_game(msg_t *m)
 {
 	uint16_t pos = 0;
diff --git a/src/table_stacks.c b/src/table_stacks.c
index 9a32977..7f76edd 100644
--- a/src/table_stacks.c
+++ b/src/table_stacks.c
@@ -14,7 +14,7 @@ const uint8_t get_stack_idx_for_card(const table_stacks_t* stack_list, const car
 
 	for(int i=0; i<NUM_TABLE_STACKS; i++)
 	{
-		card stackcard = card_stack_upper_card(&stack_list->stacks[i]);
+		card stackcard = card_stack_top(&stack_list->stacks[i]);
 		uint8_t new_diff = c - stackcard;
 		assert(new_diff != 0);