From ef72bf0a43445129a2b5734055702cf908c6c392 Mon Sep 17 00:00:00 2001
From: Giel van Schijndel <giel@wz2100.net>
Date: Sun, 3 Aug 2008 21:34:18 +0000
Subject: [PATCH]  * "Upgrade" the function comments for NETsendGAMESTRUCT and
 NETrecvGAMESTRUCT to Doxygen comments  * Restore the empty lines removed in
 r5732  * Add a note to GAMESTRUCT containing a list of elements that need to
 be updated when GAMESTRUCT's definition changes

git-svn-id: svn+ssh://svn.gna.org/svn/warzone/trunk@5770 4a71c877-e1ca-e34f-864e-861f7616d084
---
 lib/netplay/netplay.c | 24 ++++++++++++++++--------
 lib/netplay/netplay.h |  5 ++++-
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/lib/netplay/netplay.c b/lib/netplay/netplay.c
index 6a7b0c0b8..28a04320e 100644
--- a/lib/netplay/netplay.c
+++ b/lib/netplay/netplay.c
@@ -397,10 +397,14 @@ BOOL NETsetGameFlags(UDWORD flag, SDWORD value)
 
 	return true;
 }
-// NETsendGAMESTRUCT(TCPsocket socket, const GAMESTRUCT* game)
-// NOTE! The GAMESTRUCT is being sent to the master server (if user is hosting).
-// It must be packed in network byte order. (Big-endian).
-// Be advised that if you change GAMESTRUCT, then you must also modify the master server code.
+
+/**
+ * @NOTE \c game is being sent to the master server (if hosting)
+ *       The implementation of NETsendGAMESTRUCT <em>must</em> guarantee to
+ *       pack it in network byte order (big-endian).
+ *
+ * @see GAMESTRUCT,NETrecvGAMESTRUCT
+ */
 static void NETsendGAMESTRUCT(TCPsocket socket, const GAMESTRUCT* game)
 {
 	// A buffer that's guaranteed to have the correct size (i.e. it
@@ -445,10 +449,14 @@ static void NETsendGAMESTRUCT(TCPsocket socket, const GAMESTRUCT* game)
 		debug(LOG_NET, "Failed to send: %s", SDLNet_GetError());
 	}
 }
-// NETrecvGAMESTRUCT(GAMESTRUCT* game)
-// NOTE! The GAMESTRUCT is being received from the master server (if user is using lobby).
-// It must be packed in network byte order. (Big-endian).
-// Be advised that if you change GAMESTRUCT, then you must also modify the master server code.
+
+/**
+ * @NOTE \c game is being retrieved from the master server (if browsing the
+ *       lobby). The implementation of NETrecvGAMESTRUCT should assume the data
+ *       to be packed in network byte order (big-endian).
+ *
+ * @see GAMESTRUCT,NETsendGAMESTRUCT
+ */
 static bool NETrecvGAMESTRUCT(GAMESTRUCT* game)
 {
 	// A buffer that's guaranteed to have the correct size (i.e. it
diff --git a/lib/netplay/netplay.h b/lib/netplay/netplay.h
index 25a91ac89..1498c91dc 100644
--- a/lib/netplay/netplay.h
+++ b/lib/netplay/netplay.h
@@ -111,7 +111,10 @@ typedef struct {					//Available game storage... JUST FOR REFERENCE!
 	int32_t dwUser4;
 } SESSIONDESC;
 
-// Games Storage Structures
+/**
+ * @NOTE when changing this structure, NETsendGAMESTRUCT, NETrecvGAMESTRUCT and
+ *       the lobby server should be changed accordingly.
+ */
 typedef struct {
 	char		name[StringSize];
 	SESSIONDESC	desc;