Added documentation for ui.c.

1 files changed, 38 insertions, 6 deletions

diff --git a/src/ui.c b/src/ui.c
index 0c14ed0..f7b9b08 100644
--- a/src/ui.c
+++ b/src/ui.c
@@ -10,7 +10,7 @@
 #define CP_RED_ON_BLACK		5
 
 #define KEY_ESCAPE	27
-#define KEY_RETURN	10
+#define KEY_RETURN	10 // Is needed, because the KEY_ENTER defined by ncurses does not work
 
 #define KEY_VI_LEFT	'h'
 #define KEY_VI_RIGHT	'l'
@@ -26,6 +26,14 @@ static WINDOW *w_hand_cards;
 
 static WINDOW *w_final_scores;
 
+/**
+ * Draws a card in a given window at a specified position. The card can also be highlighted (this is used for visualization of a selected card).
+ * @param[in] w The window to draw the card in
+ * @param[in] row The row at which the card will be drawn
+ * @param[in] col The column at which the card will be drawn
+ * @param[in] highlight If true, the card will be highlighted
+ * @param[in] c The card, that will be drawn
+*/
 static void draw_card(WINDOW *w, const uint8_t row, const uint8_t col, const bool highlight, const card c)
 {
 	assert(w != NULL);
@@ -129,6 +137,14 @@ static void draw_card(WINDOW *w, const uint8_t row, const uint8_t col, const boo
 		wattroff(w, A_BOLD);
 }
 
+/**
+ * Draws a card stack in a given window at a specified position. The card stack can also be highlighted (this is used for visualization of a selected card stack).
+ * @param[in] w The window to draw the card stack in
+ * @param[in] row The row at which the card stack will be drawn
+ * @param[in] col The column at which the card stack will be drawn
+ * @param[in] highlight If true, the card stack will be highlighted
+ * @param[in] cs The card stack, that will be drawn
+*/
 static void draw_card_stack(WINDOW *w, const uint8_t row, const uint8_t col, const bool highlight, const card_stack_t *cs)
 {
 	assert(w != NULL);
@@ -179,7 +195,7 @@ void ui_display_wnd_table_cards(const table_stacks_t *ts, const bool highlight,
 }
 
 /**
- * Displays the stack points window.
+ * Displays the stack points window. One stack points entry can be highlighted (this is used for visualization of a selected stack).
  * @param[in] ts The table stacks used for calculation of stack points
  * @param[in] highlight If true, stack points will be highlighted
  * @param[in] highlighted_points The stack points to highlight. Only used, if highlight is true
@@ -209,7 +225,7 @@ void ui_display_wnd_stack_points(const table_stacks_t *ts, const bool highlight,
 }
 
 /**
- * Displays the current state window, showing all player names and their open cards and the client player's score.
+ * Displays the current state window, showing all player names and their open cards and the client player's score. A player from the player list can be highlighted (used to display the player whose turn it is).
  * @param[in] pl Player list. List has to be sorted by open card, in ascending order
  * @param[in] num_players The number of players to show a player name and open card for
  * @param[in] highlight If true, a player in the player table will be highlighted
@@ -265,7 +281,7 @@ void ui_display_wnd_current_state(const player_list_t *pl, const uint8_t num_pla
 }
 
 /**
- * Displays the message window.
+ * Displays the message window. The displayed message can be highlighted.
  * @param[in] message The message to display
  * @param[in] highlight If true, the message will be highlighted
 */
@@ -285,7 +301,7 @@ void ui_display_wnd_messages(const char *message, const bool highlight)
 }
 
 /**
- * Displays the hand cards window.
+ * Displays the hand cards window. A single card from the hand can be highlighted (used for visualization of a selected card).
  * @param[in] h The hand that will be displayed. h must be sorted in ascending order
  * @param[in] highlight If true, a card will be highlighted
  * @param[in] highlighted_card The card to highlight. Only used, if highlight is true
@@ -337,7 +353,10 @@ void ui_display_wnd_hand_cards(const hand_t *h, const bool highlight, const uint
 }
 
 /**
- * Displays the final scores window and highlights the player.
+ * Displays the final scores window and highlights a given player's name and score. The players that finish the game on the first place will be highlighted in a distinct way.
+ * @param[in] pl Player list. List has to be sorted by score, in ascending order
+ * @param[in] num_players The number of players to show a player name and score for
+ * @param[in] highlighted_player The player to highlight
 */
 void ui_display_wnd_final_scores(const player_list_t *pl, const uint8_t num_players, const player_id_t highlighted_player)
 {
@@ -396,6 +415,11 @@ void ui_display_wnd_final_scores(const player_list_t *pl, const uint8_t num_play
 	} while (KEY_RETURN != key && KEY_ESCAPE != key);
 }
 
+/**
+ * Starts the card chooser. The player has to pick a card from a given hand. The hand and a message that the player has to pick a card will be displayed. The function blocks until the player has made his choice. The index of the picked card within the hand will be returned.
+ * @param[in] h The hand to pick a card from
+ * @return The index of the chosen card
+*/
 uint8_t ui_choose_card(hand_t *h)
 {
 	assert(h != NULL);
@@ -454,6 +478,11 @@ uint8_t ui_choose_card(hand_t *h)
 	return chosen_card_idx;
 }
 
+/**
+ * Starts the card stack chooser. The player has to pick a card stack from given table stacks. The table stacks, stack points and a message that the player has to pick a card stack will be displayed. The function blocks until the player has made his choice. The index of the picked card stack within the table stacks will be returned.
+ * @param[in] ts The table stacks to pick a card stack from
+ * @return The index of the chosen card stack
+*/
 uint8_t ui_choose_stack(const table_stacks_t *ts)
 {
 	assert(ts != NULL);
@@ -505,6 +534,9 @@ uint8_t ui_choose_stack(const table_stacks_t *ts)
 	return chosen_stack_idx;
 }
 
+/**
+ * Updates the screen.
+*/
 void ui_update(void)
 {
 	doupdate();