* "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

@@ -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).
+ * @NOTE \c game is being sent to the master server (if hosting)
-// Be advised that if you change GAMESTRUCT, then you must also modify the master server code.
+ *       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).
+ * @NOTE \c game is being retrieved from the master server (if browsing the
-// Be advised that if you change GAMESTRUCT, then you must also modify the master server code.
+ *       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

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;