Added documentation for client_game_states.c.

1 files changed, 27 insertions, 1 deletions

diff --git a/src/client_game_states.c b/src/client_game_states.c
index cf5710b..a60fc52 100644
--- a/src/client_game_states.c
+++ b/src/client_game_states.c
@@ -4,6 +4,12 @@
 #include "data_store.h"
 #include <unistd.h>
 
+/**
+ * Game state handler. Handles the client, that waits for dealed hand cards from server. A message showing the waiting client is displayed. If it is the first round, the initial table stacks are received. The table stacks and stack points are displayed. The function blocks, until the initial stacks (only round 1) and the hand cards are received. On returning from the function, a state transition occurs.
+ * @param[in] sock The server socket that is read from
+ * @param[in] round Specifies the current round the game is in
+ * @return STATE_CLIENT_SELECT_OPEN_CARD The next state after receiving hand cards
+*/
 game_state_t state_client_wait_for_hand_cards(const int sock, const uint8_t round)
 {
 	data_store_t *d = data_store();
@@ -26,6 +32,11 @@ game_state_t state_client_wait_for_hand_cards(const int sock, const uint8_t roun
 	return STATE_CLIENT_SELECT_OPEN_CARD;
 }
 
+/**
+ * Game state handler. Handles the client, that has to pick an open card. The card chooser will be run and the selected card will be sent to the server. Afterwards, the selected card will be removed from the hand and the UI will update the hand cards. The function will block until the selected card is sent to the server. On returning from the function, a state transition occurs.
+ * @param[in] sock The server socket that the selected card is sent to
+ * @return STATE_CLIENT_WAIT_FOR_OPEN_CARDS The next state after choosing an open card
+*/
 game_state_t state_client_select_open_card(const int sock)
 {
 	data_store_t *d = data_store();
@@ -46,6 +57,11 @@ game_state_t state_client_select_open_card(const int sock)
 	return STATE_CLIENT_WAIT_FOR_OPEN_CARDS;
 }
 
+/**
+ * Game state handler. Handles the client, that waits for the open card list from server. Before receiving the open cards list, a message that the client is waiting for the other players is displayed. After receiving the list of open cards, the player list is sorted by the open cards in ascending order. On returning from the function, a state transition occurs.
+ * @param[in] sock The server socket that is read from
+ * @return STATE_CLIENT_PLAY_CARDS The next state after waiting for open card list
+*/
 game_state_t state_client_wait_for_open_cards(const int sock)
 {
 	data_store_t *d = data_store();
@@ -62,6 +78,13 @@ game_state_t state_client_wait_for_open_cards(const int sock)
 	return STATE_CLIENT_PLAY_CARDS;
 }
 
+/**
+ * Game state handler. In this state, the client tries to play all received open cards. If a card is smaller than the stacks and it is the player's turn, display the stack selection window. If it is not the player's turn, receive another player's selected stack from the server. If a card from a player fits on a stack, but the stack is already full, then replace the stack with the card, and add the stack points to the player's points.
+ * @param[in] sock The server socket that is read/written to
+ * @return STATE_CLIENT_SELECT_OPEN_CARD The next state, if the player still has hand cards
+ * @return STATE_CLIENT_WAIT_FOR_HAND_CARDS The next state, if the main stack is not empty. The server will deal us new hand cards
+ * @return STATE_CLIENT_GAME_FINISHED The next state, if the main stack is empty
+*/
 game_state_t state_client_play_cards(const int sock)
 {
 	data_store_t *ds = data_store();
@@ -78,7 +101,7 @@ game_state_t state_client_play_cards(const int sock)
 		ui_display_wnd_current_state(&ds->player_list, ds->player_list.count, true, i, ple->score);
 		ui_update();
 
-		if(stack_idx >= NUM_TABLE_STACKS) // card does not fit on any stack
+		if(stack_idx >= NUM_TABLE_STACKS) // Card is smaller than any stack -> Stack has to be picked
 		{
 			if(our_turn) // our turn to select stack
 			{
@@ -146,6 +169,9 @@ game_state_t state_client_play_cards(const int sock)
 	return 1337;
 }
 
+/**
+ * Game state handler. Handles the client, after the game has finished. The player list will be sorted by score in ascending order and the final scores window will be displayed. As the game has finished, no state transition takes place before returning from this function.
+*/
 void state_client_game_finished(void)
 {
 	data_store_t *d = data_store();