From 0c85158f6e149728ad8d7c164c5839856bd655f9 Mon Sep 17 00:00:00 2001
From: Reiner Herrmann <reiner@reiner-h.de>
Date: Sat, 29 Jan 2011 17:21:16 +0100
Subject: added further net/ documentation (including payload formats)

---
 src/net/server.c | 46 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 34 insertions(+), 12 deletions(-)

(limited to 'src/net/server.c')

diff --git a/src/net/server.c b/src/net/server.c
index 8113c11..cc6c438 100644
--- a/src/net/server.c
+++ b/src/net/server.c
@@ -12,6 +12,9 @@
 
 /**
  * Return socket with connection to player with specified player id
+ * @param[in] client_socks Pointer to socket_list with connection to clients
+ * @param[in] pid Player ID to search in socket list
+ * @return Socket corresponding to specified player id
  */
 int socket_for_player_id(const socket_list_t *client_socks, const player_id_t pid)
 {
@@ -120,7 +123,7 @@ void server_get_players(int serversock, socket_list_t* client_socks, const uint8
 
 /**
   * Parses hello message from client and store username in the global data store.
-  * @param[in] msg The message to parse
+  * @param[in] m The message to parse
   * @return true
   */
 bool server_parse_hello(const msg_t *m)
@@ -145,7 +148,7 @@ bool server_parse_hello(const msg_t *m)
 
 /**
   * Parses open card message from client and stores the selected card in the global data store.
-  * @param[in] msg The message to parse
+  * @param[in] m The message to parse
   * @return true
   */
 bool server_parse_selected_card(const msg_t *m)
@@ -161,7 +164,7 @@ bool server_parse_selected_card(const msg_t *m)
 
 /**
   * Parses selected stack message from client and stores the stack index in the global data store.
-  * @param[in] msg The message to parse
+  * @param[in] m The message to parse
   * @return true
   */
 bool server_parse_selected_stack(const msg_t *m)
@@ -178,9 +181,11 @@ bool server_parse_selected_stack(const msg_t *m)
 }
 
 /**
-  * 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
-  */
+ * Prepares start game message. All player IDs, player names and name lengths will be saved in the message payload.\n
+ * Payload format:\n
+ * [ count:1 | pid1:1 | namelen1:1 | name1:namelen1 | ... | pidN:1 | namelenN:1 | nameN:namelenN ]
+ * @param[out] m A preallocated message object to store header and payload information
+ */
 void server_prep_start_game(msg_t *m)
 {
 	uint16_t pos = 0;
@@ -205,7 +210,9 @@ void server_prep_start_game(msg_t *m)
 }
 
 /**
- * Prepares hello message to notify client of its assigned id
+ * Prepares hello message to notify client of its assigned id\n
+ * Payload format:\n
+ * [ playerid:1 ]
  * @param[out] m A preallocated message object to store header and payload information
  * @param[in] player The player_list_entry_t belonging to the destined client
  */
@@ -217,7 +224,10 @@ void server_prep_hello(msg_t *m, const player_list_entry_t* player)
 }
 
 /**
- * Send selected stack by current player to client
+ * Send selected stack by current player to client\n
+ * Payload format:\n
+ * [ stack_index:1 ]
+ * @param[out] m A preallocated message object to store header and payload information
  */
 void server_prep_selected_stack(msg_t *m)
 {
@@ -229,7 +239,10 @@ void server_prep_selected_stack(msg_t *m)
 }
 
 /**
- * Send a hand to a client
+ * Send a hand to a client\n
+ * Payload format:\n
+ * [ card1:1 | ... | cardN:1 ]
+ * @param[out] m A preallocated message object to store header and payload information
  * @param[in] h The hand for the client
  */
 void server_prep_deal_hand(msg_t *m, const hand_t *h)
@@ -245,7 +258,10 @@ void server_prep_deal_hand(msg_t *m, const hand_t *h)
 }
 
 /**
- * Send cards of initial stacks to client at beginning of game.
+ * Send cards of initial stacks to client at beginning of game.\n
+ * Payload format:\n
+ * [ stack_card1:1 | ... stack_cardN:1 ]
+ * @param[out] m A preallocated message object to store header and payload information
  */
 void server_prep_initial_stacks(msg_t *m)
 {
@@ -260,7 +276,10 @@ void server_prep_initial_stacks(msg_t *m)
 }
 
 /**
- * Send all open cards to client
+ * Send all open cards to client\n
+ * Payload format:\n
+ * [ player_id1:1 | open_card1:1 | ... | player_idN:1 | open_cardN:1 ]
+ * @param[out] m A preallocated message object to store header and payload information
  */
 void server_prep_selected_card_all(msg_t *m)
 {
@@ -282,7 +301,10 @@ void server_prep_selected_card_all(msg_t *m)
 }
 
 /**
- * Notify client whether the game will continue or end
+ * Notify client whether the game will continue or end\n
+ * Payload format:\n
+ * [ next_action:1 ]
+ * @param[out] m A preallocated message object to store header and payload information
  */
 void server_prep_next_action(msg_t *m)
 {
-- 
cgit v1.2.3