added further net/ documentation (including payload formats)

3 files changed, 45 insertions, 17 deletions

diff --git a/src/net/client.c b/src/net/client.c
index 72d7322..eec83a5 100644
--- a/src/net/client.c
+++ b/src/net/client.c
@@ -195,7 +195,9 @@ bool client_parse_hello(const msg_t *m)
 }
 
 /**
- * Prepare hello message with client's nickname
+ * Prepare hello message with client's nickname\n
+ * Payload format:\n
+ * [ nickname:strlen(nickname) ]
  * @param[out] m Pointer to message that should be filled
  */
 void client_prep_hello(msg_t *m)
@@ -208,7 +210,9 @@ void client_prep_hello(msg_t *m)
 }
 
 /**
- * Prepare message with selected card
+ * Prepare message with selected card\n
+ * Payload format:\n
+ * [ selected_card:1 ]
  * @param[out] m Pointer to message that should be filled
  */
 void client_prep_selected_card(msg_t *m)
@@ -223,7 +227,9 @@ void client_prep_selected_card(msg_t *m)
 }
 
 /**
- * Prepare message with selected stack
+ * Prepare message with selected stack\n
+ * Payload format:\n
+ * [ stack_index:1 ]
  * @param[out] m Pointer to message that should be filled
  */
 void client_prep_selected_stack(msg_t *m)
diff --git a/src/net/comm.c b/src/net/comm.c
index 0079a81..2bfacfa 100644
--- a/src/net/comm.c
+++ b/src/net/comm.c
@@ -10,7 +10,7 @@
 /**
  * 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] sock Socket on which to receive
  * @param[in] type Message type to receive
  * @return Indicates success of receiving
  */
@@ -80,7 +80,7 @@ bool net_recv(const int sock, const msg_type_t type)
 /**
  * Generic send function.\n
  * Transmits specified message type on socket.
- * @param[in] Socket on which to send
+ * @param[in] sock 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
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)
 {