Finish the docs for netchan.

Also clean out some unnecessary declarations.

include/netchan.h

@@ -41,8 +41,8 @@
 	\ingroup network
 */
 //{
-#define MAX_MSGLEN		1450		// max length of a reliable message
+#define MAX_MSGLEN		1450		///< max length of a reliable message
-#define MAX_DATAGRAM	1450		// max length of unreliable message
+#define MAX_DATAGRAM	1450		///< max length of unreliable message
 
 #define	PORT_ANY	-1
 
@@ -54,19 +54,17 @@ typedef struct
 	byte	ip[4];
 #endif
 	unsigned short	port;
-	unsigned short	family;	// used to be pad, before IPV6
+	unsigned short	family;
 } netadr_t;
 
+extern	int		net_socket;
 extern	netadr_t	net_local_adr;
 extern	netadr_t	net_loopback_adr;
 extern	netadr_t	net_from;		// address of who sent the packet
 extern	struct msg_s *net_message;
 
-extern	struct cvar_s	*hostname;
 extern	struct cvar_s	*qport;
 
-extern	int		net_socket;
-
 int Net_Log_Init (const char **sound_precache);
 void Net_LogPrintf (const char *fmt, ...) __attribute__ ((format (printf, 1, 2)));
 void Log_Incoming_Packet (const byte *p, int len, int has_sequence);
@@ -78,7 +76,6 @@ void Analyze_Server_Packet (const byte * data, int len, int has_sequence);
 extern struct cvar_s *net_packetlog;
 
 extern qboolean is_server;
-qboolean ServerPaused (void);
 //@}
 
 /** \defgroup qw-udp QuakeWorld udp support.
@@ -194,7 +191,8 @@ qboolean NET_StringToAdr (const char *s, netadr_t *a);
 	after the retransmit has been acknowledged and the reliable still failed
 	to get there.
 
-	If the sequence number is -1, the packet should be handled without a
+	If the sequence number and reliable payload bits are all 1 (32bit -1),
+	the packet is an out-of-band packet and should be handled without a
 	netcon.
 
 	The reliable message can be added to at any time by doing
@@ -292,30 +290,96 @@ typedef struct netchan_s {
 
 /** Disable packet choking.
 */
-extern	int net_nochoke;	// don't choke packets
+extern	int net_nochoke;
 
 /** Disable packet sending.
 
 	Used by clients in demo playback mode.
 */
-extern	int net_blocksend;	// don't send packets (used by client for demos)
+extern	int net_blocksend;
 
 /** Pointer to variable holding the current time in seconds.
 */
 extern	double *net_realtime;
 
+/** Initialize the netchan system.
+
+	Currently only sets the qport cvar default to a random value.
+*/
 void Netchan_Init (void);
+
+/** Initialize the netchan cvars.
+*/
 void Netchan_Init_Cvars (void);
+
+/** Try to send an unreliable packet to a connection.
+
+	Handles transmission or retransmission of the reliable packet.
+
+	0 length will still generate a packet and deal with the reliable messages.
+
+	\param chan		The netchan representing the connection.
+	\param length	The size of the unreliable packet.
+	\param data		The data of the unreliable packet.
+*/
 void Netchan_Transmit (netchan_t *chan, int length, byte *data);
+
+/** Send an out-of-band packet.
+
+	\param adr		The address to which the data will be sent.
+	\param length	The length of the data to be sent.
+	\param data		The data to be sent.
+*/
 void Netchan_OutOfBand (netadr_t adr, int length, byte *data);
+/** Send a formatted string as an out-of-band packet.
+
+	\param adr		The address to which the data will be sent.
+	\param format	The printf style format string.
+*/
 void Netchan_OutOfBandPrint (netadr_t adr, const char *format, ...)
 	__attribute__ ((format (printf,2,3)));
+
+/** Process a packet for the specifiied connection.
+
+	Called when the current net_message is from remote_address.
+	Modifies net_message so that it points to the packet payload.
+
+	\param chan		The netchan representing the connection.
+*/
 qboolean Netchan_Process (netchan_t *chan);
+
+/** Initialize a new connection.
+
+	\param chan		The netchan representing the connection.
+	\param adr		The address of the remote end of the connection.
+	\param qport	The qport associated with the connection.
+	\param flags	Control of the sending/reading of the qport on this
+					connection.
+*/
 void Netchan_Setup (netchan_t *chan, netadr_t adr, int qport, ncqport_e flags);
 
+/** Check if a packet can be sent to the connection.
+
+	\param chan     The netchan representing the connection.
+	\return			True if the connection isn't chocked.
+*/
 qboolean Netchan_CanPacket (netchan_t *chan);
+
+/** Check if a reliable packet can be sent to the connection.
+
+	\param chan     The netchan representing the connection.
+	\return			True if there is no outstanding reliable packet and the
+					connection isn't chocked.
+*/
 qboolean Netchan_CanReliable (netchan_t *chan);
 
+/** Send a packet.
+
+	Very raw. Just calls NET_SendPacket().
+	\param length	The length of the data to be sent.
+	\param data		The data to be sent.
+	\param to		The address to which the data will be sent.
+*/
 void Netchan_SendPacket (int length, const void *data, netadr_t to);
 
 //@}

libs/net/net_chan.c

@@ -187,14 +187,6 @@ Netchan_CanReliable (netchan_t *chan)
 	return Netchan_CanPacket (chan);
 }
 
-/*
-	Netchan_Transmit
-
-	tries to send an unreliable message to a connection, and handles the
-	transmition / retransmition of the reliable messages.
-
-	0 length will still generate a packet and deal with the reliable messages.
-*/
 void
 Netchan_Transmit (netchan_t *chan, int length, byte *data)
 {
@@ -239,20 +231,20 @@ Netchan_Transmit (netchan_t *chan, int length, byte *data)
 	MSG_WriteLong (&send, w1);
 	MSG_WriteLong (&send, w2);
 
-	// send the qport if we are a client
+	/// Send the qport if appropriate (we are a client).
 	if (chan->flags & NC_QPORT_SEND)
 		MSG_WriteShort (&send, chan->qport);
 
-	// copy the reliable message to the packet first
+	/// First copy the reliable message to the packet.
 	if (send_reliable) {
 		SZ_Write (&send, chan->reliable_buf, chan->reliable_length);
 		chan->last_reliable_sequence = chan->outgoing_sequence;
 	}
-	// add the unreliable part if space is available
+	/// Then add the unreliable part if space is available.
 	if (send.maxsize - send.cursize >= length)
 		SZ_Write (&send, data, length);
 
-	// send the datagram
+	/// Send the datagram if not blocked (in demo playback mode)
 	i = chan->outgoing_sequence & (MAX_LATENT - 1);
 	chan->outgoing_size[i] = send.cursize;
 	chan->outgoing_time[i] = *net_realtime;
@@ -276,12 +268,6 @@ Netchan_Transmit (netchan_t *chan, int length, byte *data)
 					chan->outgoing_sequence - chan->incoming_sequence);
 }
 
-/*
-	Netchan_Process
-
-	called when the current net_message is from remote_address
-	modifies net_message so that it points to the packet payload
-*/
 qboolean
 Netchan_Process (netchan_t *chan)
 {
@@ -291,12 +277,12 @@ Netchan_Process (netchan_t *chan)
 		if (!NET_CompareAdr (net_from, chan->remote_address))
 			return false;
 
-	// get sequence numbers     
+	/// Get the sequence numbers.
 	MSG_BeginReading (net_message);
 	sequence = MSG_ReadLong (net_message);
 	sequence_ack = MSG_ReadLong (net_message);
 
-	// read the qport if we are a server, but drop it
+	/// Read the qport if appropriate (we are a server), but ignore it.
 	if (chan->flags & NC_QPORT_READ)
 		MSG_ReadShort (net_message);
 
@@ -337,7 +323,7 @@ Netchan_Process (netchan_t *chan)
 	}
 #endif
 
-	// discard stale or duplicated packets
+	/// Discard stale or duplicated packets.
 	if (sequence < (unsigned int) chan->incoming_sequence + 1) {
 		if (showdrop->int_val)
 			Sys_Printf ("%s:Out of order packet %i at %i\n",
@@ -346,7 +332,7 @@ Netchan_Process (netchan_t *chan)
 		return false;
 	}
 
-	// dropped packets don't keep the message from being used
+	/// Dropped packets don't keep the message from being used.
 	chan->net_drop = sequence - (chan->incoming_sequence + 1);
 	if (chan->net_drop > 0) {
 		chan->drop_count += 1;
@@ -357,21 +343,21 @@ Netchan_Process (netchan_t *chan)
 						sequence - (chan->incoming_sequence + 1), sequence);
 	}
 
-	// if the current outgoing reliable message has been acknowledged
+	/// If the current outgoing reliable message has been acknowledged,
-	// clear the buffer to make way for the next
+	/// clear the buffer to make way for the next.
 	if (reliable_ack == (unsigned int) chan->reliable_sequence)
 		chan->reliable_length = 0;		// it has been received
 
-	// if this message contains a reliable message, bump
+	/// If this message contains a reliable message, bump
-	// incoming_reliable_sequence 
+	/// incoming_reliable_sequence 
 	chan->incoming_sequence = sequence;
 	chan->incoming_acknowledged = sequence_ack;
 	chan->incoming_reliable_acknowledged = reliable_ack;
 	if (reliable_message)
 		chan->incoming_reliable_sequence ^= 1;
 
-	// the message can now be read from the current message pointer
+	// The message can now be read from the current message pointer.
-	// update statistics counters
+	/// Update statistics counters.
 	chan->frame_latency = chan->frame_latency * OLD_AVG
 		+ (chan->outgoing_sequence - sequence_ack) * (1.0 - OLD_AVG);
 	chan->frame_rate = chan->frame_rate * OLD_AVG