Document the datagram net driver interface.

include/net_dgrm.h

@@ -32,17 +32,98 @@
 */
 //@{
 
+/** Initialize the Datagram net driver.
+
+	Also initializes the underlying lan drivers.
+
+	\return			0 if successful, otherwise -1.
+*/
 int			Datagram_Init (void);
+
+/** Control the listen status of the underlying lan drivers.
+
+	\param state	True to enable, false to disable.
+*/
 void		Datagram_Listen (qboolean state);
+
+/** Search for hosts (servers) on the local network.
+
+	If \p xmit is true, broadcast a CCREQ_SERVER_INFO packet via all
+	underlying lan drivers using their control ports.
+
+	Check for any CCREP_SERVER_INFO responses. Ignore all other packets.
+
+	\param xmit		True to send the broadcast, falst to only listen.
+*/
 void		Datagram_SearchForHosts (qboolean xmit);
+
+/** Connect to the specified host.
+
+	\param host		The host to which the connection will be made.
+	\return			A pointer to the socket representing the connection, or
+					null if unsuccessful.
+*/
 qsocket_t	*Datagram_Connect (const char *host);
+
+/** Check for a new incoming connection.
+
+	\return			A pointer to the socekt representing the new connection,
+					or null if none found.
+*/
 qsocket_t 	*Datagram_CheckNewConnections (void);
+
+/** Check for and process an incoming packet on the socket.
+
+	\param sock		The socket to check.
+	\return			-1 if there is an error
+	\return			0 if the packet is stale
+	\return			1 if the packet is reliable
+	\return			2 if the packet is unreliable
+*/
 int			Datagram_GetMessage (qsocket_t *sock);
+
+/** Send a reliable packet to the socket.
+
+	\param sock		The socket to which the packet will be sent.
+	\param data		The packet to be sent.
+	\return			-1 If there is an error
+	\return			1 if everything is ok.
+*/
 int			Datagram_SendMessage (qsocket_t *sock, sizebuf_t *data);
+
+/** Send an unreliable packet to the socket.
+
+	\param sock		The socket to which the packet will be sent.
+	\param data		The packet to be sent.
+	\return			-1 If there is an error
+	\return			1 if everything is ok.
+*/
 int			Datagram_SendUnreliableMessage (qsocket_t *sock, sizebuf_t *data);
+
+/** Check if a reliable message can be sent to the socket.
+
+	\param sock		The socket to check.
+	\return			True if the packet can be sent.
+*/
 qboolean	Datagram_CanSendMessage (qsocket_t *sock);
+
+/** Check if an unreliable message can be sent to the socket.
+
+	Always true.
+
+	\param sock		The socket to check.
+	\return			True if the packet can be sent.
+*/
 qboolean	Datagram_CanSendUnreliableMessage (qsocket_t *sock);
+
+/** Close the socket.
+
+	\param sock		The socket to close.
+*/
 void		Datagram_Close (qsocket_t *sock);
+
+/** Shutdown the Datagram net driver.
+*/
 void		Datagram_Shutdown (void);
 
 //@}

include/net_udp.h

@@ -52,6 +52,7 @@ void UDP_Shutdown (void);
 /** Open or close the accept socket.
 
 	Sets net_acceptsocket to the socket number or -1.
+	The accept socket is stored in net_hostport.
 
 	\param state	True to open the socket, false to close it.
 */
@@ -169,7 +170,10 @@ int UDP_GetAddrFromName (const char *name, struct qsockaddr *addr);
 
 	\param addr1	The first address to compare.
 	\param addr2	The second address to compare.
-	\return			True of the addresses match, otherwise false.
+	\return			-1 if the family or address are different.
+	\return			1 if the family and address are the same, but the port
+					is different.
+	\return			0 if everything is the same.
 */
 int UDP_AddrCompare (struct qsockaddr *addr1, struct qsockaddr *addr2);
 

libs/net/nm/net_dgrm.c

@@ -157,7 +157,7 @@ NET_Ban_f (void)
 
 
 int
-Datagram_SendMessage (qsocket_t * sock, sizebuf_t *data)
+Datagram_SendMessage (qsocket_t *sock, sizebuf_t *data)
 {
 	unsigned int packetLen;
 	unsigned int dataLen;
@@ -193,7 +193,7 @@ Datagram_SendMessage (qsocket_t * sock, sizebuf_t *data)
 
 
 static int
-SendMessageNext (qsocket_t * sock)
+SendMessageNext (qsocket_t *sock)
 {
 	unsigned int packetLen;
 	unsigned int dataLen;
@@ -225,7 +225,7 @@ SendMessageNext (qsocket_t * sock)
 
 
 static int
-ReSendMessage (qsocket_t * sock)
+ReSendMessage (qsocket_t *sock)
 {
 	unsigned int packetLen;
 	unsigned int dataLen;
@@ -257,7 +257,7 @@ ReSendMessage (qsocket_t * sock)
 
 
 qboolean
-Datagram_CanSendMessage (qsocket_t * sock)
+Datagram_CanSendMessage (qsocket_t *sock)
 {
 	if (sock->sendNext)
 		SendMessageNext (sock);
@@ -267,14 +267,14 @@ Datagram_CanSendMessage (qsocket_t * sock)
 
 
 qboolean
-Datagram_CanSendUnreliableMessage (qsocket_t * sock)
+Datagram_CanSendUnreliableMessage (qsocket_t *sock)
 {
 	return true;
 }
 
 
 int
-Datagram_SendUnreliableMessage (qsocket_t * sock, sizebuf_t *data)
+Datagram_SendUnreliableMessage (qsocket_t *sock, sizebuf_t *data)
 {
 	int         packetLen;
 
@@ -294,7 +294,7 @@ Datagram_SendUnreliableMessage (qsocket_t * sock, sizebuf_t *data)
 
 
 int
-Datagram_GetMessage (qsocket_t * sock)
+Datagram_GetMessage (qsocket_t *sock)
 {
 	unsigned int length;
 	unsigned int flags;
@@ -303,6 +303,8 @@ Datagram_GetMessage (qsocket_t * sock)
 	unsigned int sequence;
 	unsigned int count;
 
+	/// If there is an outstanding reliable packet and more than 1 second has
+	/// passed, resend the packet.
 	if (!sock->canSend)
 		if ((net_time - sock->lastSendTime) > 1.0)
 			ReSendMessage (sock);
@@ -357,6 +359,7 @@ Datagram_GetMessage (qsocket_t * sock)
 
 			length -= NET_HEADERSIZE;
 
+			/// Copy unreliable data to net_message
 			SZ_Clear (net_message->message);
 			SZ_Write (net_message->message, packetBuffer.data, length);
 
@@ -414,6 +417,7 @@ Datagram_GetMessage (qsocket_t * sock)
 				break;
 			}
 
+			/// Append reliable data to sock->receiveMessage.
 			memcpy (sock->receiveMessage + sock->receiveMessageLength,
 					packetBuffer.data, length);
 			sock->receiveMessageLength += length;
@@ -429,7 +433,7 @@ Datagram_GetMessage (qsocket_t * sock)
 
 
 static void
-PrintStats (qsocket_t * s)
+PrintStats (qsocket_t *s)
 {
 	Sys_Printf ("canSend = %4u   \n", s->canSend);
 	Sys_Printf ("sendSeq = %4u   ", s->sendSequence);
@@ -790,7 +794,7 @@ Datagram_Shutdown (void)
 
 
 void
-Datagram_Close (qsocket_t * sock)
+Datagram_Close (qsocket_t *sock)
 {
 	sfunc.CloseSocket (sock->socket);
 }