--- a/src/Network/Address.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Address.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -20,6 +20,8 @@
  * used in a more specifc fashion like NetworkSocket::send or NetworkSocket::accept, where a definitive address is
  * required.
  *
+ * The update() method does a blocking reverse-DNS lookup. XXX: only do the reverse lookup if get_hostname is called?
+ *
  * XXX: currently, there is no way to form a NetworkAddress from a NetworkEndpoint for e.g. sending UDP packets without
  * an associated TCP connection.
  */

--- a/src/Network/Buffer.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Buffer.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -224,7 +224,7 @@
 /*
  * NetworkBufferInput template method implementation
  */
-template <typename PrefixType> bool NetworkBufferOutput::peek_data (PrefixType &prefix, char *&buf_ref) {
+template <typename PrefixType> bool NetworkBufferInput::peek_data (PrefixType &prefix, char *&buf_ref) {
     size_t missing = 0;
     
     do {    
@@ -261,7 +261,7 @@
     return true;
 }
 
-template <typename PrefixType> void NetworkBufferOutput::flush_data (void) {
+template <typename PrefixType> void NetworkBufferInput::flush_data (void) {
     PrefixType prefix;
     
     // we *must* have a valid prefix

--- a/src/Network/Client.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Client.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,6 +1,12 @@
 #ifndef NETWORKCLIENT_HH
 #define NETWORKCLIENT_HH
 
+/**
+ * @file
+ *
+ * Game client implementation
+ */
+
 // forward-declare
 class NetworkClient;
 class NetworkClientLocalPlayer;

--- a/src/Network/Config.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Config.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,28 +1,24 @@
 #ifndef NETWORK_CONFIG_HH
 #define NETWORK_CONFIG_HH
 
-// socket-related includes
-// copied from clanlib code, so should be relatively OS-safe
-#ifndef WIN32
-        #include <sys/socket.h>
-        #include <netinet/in.h>
-        #include <arpa/inet.h>
-        #include <netdb.h>
-        #include <sys/time.h>
-        #include <unistd.h> 
-#else
-        #include <winsock2.h>
-        #include <windows.h>
-        typedef int socklen_t;
-#endif
+/**
+ * @file
+ *
+ * Network-related configuration
+ */
 
 #include <string>
 
+/** Default port used for network games */
 const std::string NETWORK_PORT_STR = "9338";
 
+/** Maximum packet size used for normal NetworkPackets... aligned to a sensible UDP mtu */
 const size_t NETWORK_PACKET_SIZE = 1280;
+
+/** Backlog used for TCP server... doesn't really matter all that much */
 const int NETWORK_LISTEN_BACKLOG = 5;
 
+/** Magic string used to identify game between client/server */
 const char NETWORK_MAGIC_STR[8+1] = "KISNGLIS";
 const uint64_t NETWORK_MAGIC_ID = * ((const uint64_t *) NETWORK_MAGIC_STR);
 

--- a/src/Network/Endpoint.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Endpoint.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -31,6 +31,8 @@
  * It may be of value to note that the hostname/service is only interpreted by the get_addrinfo() method, which means
  * that invalid/non-existant hostnames/services will only raise an error once the NetworkEndpoint is passed to
  * NetworkSocket.
+ *
+ * All DNS lookups are blocking.
  */ 
 class NetworkEndpoint {
     protected:

--- a/src/Network/Error.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Error.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,6 +1,12 @@
 #ifndef NETWORK_ERROR_HH
 #define NETWORK_ERROR_HH
 
+/**
+ * @file
+ *
+ * Base classes for shared errno-enabled errors
+ */
+
 #include "../Error.hh"
 
 /**

--- a/src/Network/Node.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Node.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,6 +1,12 @@
 #ifndef NETWORK_NODE_HH
 #define NETWORK_NODE_HH
 
+/**
+ * @file
+ *
+ * Remote NetworkSessions
+ */
+
 // forward-declare
 class NetworkNode;
 

--- a/src/Network/Object.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Object.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,6 +1,12 @@
 #ifndef NETWORK_OBJECT_HH
 #define NETWORK_OBJECT_HH
 
+/**
+ * @file
+ *
+ * Object-based network protocol for use with NetworkSession
+ */
+
 #include "Session.hh"
 #include "Node.hh"
 #include "../Logger.hh"

--- a/src/Network/Packet.cc	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Packet.cc	Fri Jan 16 22:03:49 2009 +0200
@@ -3,6 +3,7 @@
 #include <cstring>
 
 #include "Packet.hh"
+#include "Platform.hh"
 
 #include <zlib.h>
 

--- a/src/Network/Packet.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Packet.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,6 +1,12 @@
 #ifndef NETWORK_PACKET_HH
 #define NETWORK_PACKET_HH
 
+/**
+ * @file
+ *
+ * Provides the NetworkPackets that are used to communicate over a NetworkTCP/NetworkUDP sockets.
+ */
+
 #include "Config.hh"
 #include "../Types.hh"
 #include "../Error.hh"
@@ -101,6 +107,9 @@
     protected:
         /**
          * Adjust size of the most recent write_ptr area of buf_len bytes to data_len bytes.
+         *
+         * You must not call write() between calls to write_ptr() and write_ptr_adjust(). This is only valid for the
+         * most recent write_ptr()
          */
         virtual void write_ptr_adjust (size_t buf_len, size_t data_len) = 0;
 
@@ -182,7 +191,6 @@
          */
         char *buf_ptr;
         
-        // the buffer size, the amount of data in the buffer, and the current read/write offset
         /**
          * The size of the memory region pointed to by buf_ptr
          */
@@ -263,6 +271,8 @@
 
         /*
          * Accessor functions, used by the actual socket code to read/write the buffer
+         *
+         * XXX: own abstract class for these? Virtual methods <3
          */
         char* get_buf (void) { return buf_ptr; }
         const char* get_buf (void) const { return buf_ptr; }

--- a/src/Network/Platform.h	Fri Jan 16 21:24:45 2009 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,30 +0,0 @@
-#ifndef NETWORK_PLATFORM_H
-#define NETWORK_PLATFORM_H
-
-/**
- * @file
- *
- * Takes care of platform-specific imports and #defines as regards the Network code
- */
-
-#ifndef WIN32
-    // NetworkAddress
-    #include <netinet/in.h>
-    
-    // NetworkEndpoint
-    #include <sys/types.h>
-    #include <netdb.h>
-    
-    // NetworkSocket
-    #include <sys/types.h>
-    #include <sys/socket.h>
-    #include <unistd.h>
-    #include <fcntl.h>
-    #define closesocket close
-
-#else
-    #error "This network code won't compile on win32 :)"
-#endif
-
-
-#endif

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/Network/Platform.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -0,0 +1,43 @@
+#ifndef NETWORK_PLATFORM_HH
+#define NETWORK_PLATFORM_HH
+
+/**
+ * @file
+ *
+ * Takes care of platform-specific imports and #defines as regards the Network code
+ */
+
+#ifndef WIN32
+    // NetworkAddress
+    #include <netinet/in.h>
+    
+    // NetworkEndpoint
+    #include <sys/types.h>
+    #include <netdb.h>
+    
+    // NetworkSocket
+    #include <sys/types.h>
+    #include <sys/socket.h>
+    #include <unistd.h>
+    #include <fcntl.h>
+    #define closesocket close
+    
+    // NetworkReactor
+    #include <sys/select.h>
+    #include <errno.h>
+
+    // misc, here because ClanLib included these... 
+    #include <arpa/inet.h>
+    #include <sys/time.h>
+    #include <unistd.h> 
+#else
+    // misc, here because ClanLib included these...
+    #include <winsock2.h>
+    #include <windows.h>
+    typedef int socklen_t;
+
+    #error "This network code won't compile on win32 :)"
+#endif
+
+
+#endif

--- a/src/Network/Protocol.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Protocol.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,10 +1,15 @@
 #ifndef NETWORK_PROTOCOL_HH
 #define NETWORK_PROTOCOL_HH
 
-/*
- * The network protocol is defined here :o
+/**
+ * @file
+ *
+ * Definitions for game network protocol
  */
 
+/**
+ * The various NetworkChannelIDs used with our NetworkSession
+ */
 enum NetworkChannel {
     /*
      * Core channel used for NetworkSession
@@ -21,15 +26,27 @@
     NETCHAN_TERRAIN_ARRAY   = 0x0010,
 };
 
+/**
+ * Various flags used with NETMSG_PLAYER_POSITION related to PhysicsObject state
+ */
 enum NetworkPhysicsFlags {
     NETWORK_PHYSICS_INAIR               = 0x01,
     NETWORK_PHYSICS_FACE_RIGHT          = 0x02,
 };
 
+/**
+ * Various flags used with NETMSG_PROJECTILE_* messages...
+ */
 enum NetworkProjectileFlags {
+    /** NETMSG_PROJECTILE_DESTROY */
     NETWORK_PROJECTILE_REMOVE_GROUND    = 0x01,
 };
 
+/**
+ * Various NetworkMessageIDs used with our NetworkSession's NetworkObjects.
+ *
+ * Message names are of the form 'NETMSG_<object type>_<action>'
+ */
 enum NetworkMessage {
     NETMSG_PACKET_INVALID       = 0x0000,
 

--- a/src/Network/Reactor.cc	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Reactor.cc	Fri Jan 16 22:03:49 2009 +0200
@@ -10,7 +10,7 @@
 void NetworkReactor::poll (timeval *timeout) {
     int ret;
 
-    // start counting the maximum fd from -1, so that select is given nfds=0 if our list is empty
+    // start counting the maximum fd from 0, select will be given nfds=1 if empty
     int fd_max = 0;
 
     // zero our fdsets
@@ -25,7 +25,7 @@
         // ask socket what events it wants
         NetworkPollMask mask = socket->get_poll();
 
-        // set read/write
+        // ignore if nothing
         if (mask) {
             // socket file descriptor...
             int fd = socket->get_socket();
@@ -40,11 +40,11 @@
             
             // read...
             if (mask & POLL_READ)
-                FD_SET(socket->get_socket(), &read);
+                FD_SET(fd, &read);
             
             // write...
             if (mask & POLL_WRITE)
-                FD_SET(socket->get_socket(), &write);
+                FD_SET(fd, &write);
         }
     }
 

--- a/src/Network/Reactor.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Reactor.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,11 +1,17 @@
 #ifndef NETWORK_REACTOR_HH
 #define NETWORK_REACTOR_HH
 
+/**
+ * @file
+ *
+ * A select() based reactor for NetworkSocket's
+ */
+
 // forward-declare
 class NetworkReactor;
 
 /**
- * Events to poll for
+ * Event types to poll for
  */
 enum NetworkPollBit {
     POLL_READ       = 0x01,
@@ -17,24 +23,21 @@
  */
 typedef int NetworkPollMask;
 
+#include "Platform.hh"
 #include "Socket.hh"
 #include "Error.hh"
 
-/*
- * Platform-specific includes
- */
-#ifndef WIN32
-    // linux
-    #include <sys/select.h>
-    #include <errno.h>
-#else
-    #error "This network code won't compile on win32 :)"
-#endif
-
 #include <list>
 
 /**
- * A Reactor manages a set of NetworkSockets, providing readyness notification and a poll method
+ * A reactor maintains a list of NetworkSockets (which must register themselves to their reactor), and providers
+ * readyness notification of non-blocking I/O operations.
+ *
+ * NetworkSockets must call add_socket(), whereup the NetworkReactor will use NetworkSocket::get_poll() to build the
+ * set of sockets to notify. If activity is detected, I will call NetworkSocket::notify().
+ *
+ * The poll() method can then be used by the application main loop to do timed sleeps, waking up on socket activity and
+ * driving the sockets.
  */
 class NetworkReactor {
     protected:
@@ -47,13 +50,13 @@
         NetworkReactor (void);
 
         /**
-         * Our static global reactor
+         * The global NetworkReactor, used by default for all NetworkSockets.
          */
         static NetworkReactor *current;
 
         /**
          * Add a NetworkSocket to our list of sockets. The desired notification states are fetched directly from the
-         * socket itself.
+         * socket itself using NetworkSocket::get_poll(), and it will be notified using NetworkSocket::notify().
          *
          * @param socket the socket to watch
          */
@@ -67,8 +70,11 @@
         void remove_socket (NetworkSocket *socket) { sockets.remove(socket); }
 
         /**
-         * Poll our sockets and drive any I/O, optionally sleeping for the given timeout. This is efficient if our
-         * sockets list is empty.
+         * Wait for activity on any of the sockets registered and with notification enabled, driving them using 
+         * NetworkSocket::notify() if select() indicates activity. This method will sleep at most \a timeout, returning
+         * once there was socket activity, or the timeout ran out.
+         *
+         * This is intended to be particularly efficient if the socket list is empty.
          */
         void poll (timeval *timeout = NULL);
 };

--- a/src/Network/Server.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Server.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,6 +1,12 @@
 #ifndef NETWORKSERVER_HH
 #define NETWORKSERVER_HH
 
+/**
+ * @file
+ *
+ * Game server implementation
+ */
+
 #include "../GameState.hh"
 #include "Session.hh"
 #include "Object.hh"

--- a/src/Network/Session.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Session.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,6 +1,12 @@
 #ifndef NETWORK_SESSION_HH
 #define NETWORK_SESSION_HH
 
+/**
+ * @file
+ *
+ * Support for a groups of clients/servers with associated TCP/UDP sockets
+ */
+
 #include <map>
 #include <stdint.h>
 

--- a/src/Network/Socket.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/Socket.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -147,37 +147,47 @@
         int get_socket (void) const { return fd; }
 
         /**
-         * Bind to a specific local address
+         * Bind to a local endpoint. This can be specified in hostname form, and a suitable socket will be chosen.
          */ 
         void bind (const NetworkEndpoint &addr);
 
         /**
-         * Put socket into listen mode
+         * Put socket into listen mode for accept()
          */
         void listen (int backlog);
 
         /**
          * Get local address
+         *
+         * Note that this may block on a reverse DNS lookup.
          */
         NetworkAddress get_local_address (void); 
 
         /**
          * Get remote address
+         *
+         * Note that this may block on a reverse DNS lookup.
          */
         NetworkAddress get_remote_address (void); 
 
         /**
-         * Make send/recv/connect non-blocking
+         * Make send/recv non-blocking. The current connect() implementation does not support use of non-blocking
+         * connects.
          */
         void set_nonblocking (bool nonblocking);
 
         /**
-         * Accept a new connection, optionally giving the connection's source address
+         * Accept an incoming connection on a listen() socket as a new socket, optionally storing the connection's
+         * source address.
+         *
+         * Note that this may block on a reverse DNS lookup if \a src is given.
          */
         NetworkSocket* accept (NetworkAddress *src);
 
         /**
-         * Establish a new connection
+         * Connect this socket to a remote endpoint, going through the resolved addresses until we find one that works.
+         *
+         * This is currently implemented in an entirely blocking fashion, DNS lookups and connect() included.
          */
         void connect (const NetworkEndpoint &addr);
 
@@ -225,24 +235,24 @@
         void register_poll (void);
 
         /**
-         * Trigger sig_read() once socket is ready for recv?
+         * Trigger sig_read() once socket is ready for recv()
          */
         void set_poll_read (bool want_read) { this->want_read = want_read; if (!registered) register_poll(); }
 
         /**
-         * Trigger sig_write() once socket is ready for send?
+         * Trigger sig_write() once socket is ready for send()
          */
         void set_poll_write (bool want_write) { this->want_write = want_write; if (!registered) register_poll(); }
 
         /**
-         * What events this socket is interested in.
+         * What events this socket is interested in (called by NetworkReactor)
          */
         NetworkPollMask get_poll (void) { 
             return (want_read ? POLL_READ : 0) | (want_write ? POLL_WRITE : 0); 
         }
 
         /**
-         * Notify of events
+         * Notify of events (called by NetworkReactor)
          */
         void notify (NetworkPollMask mask) { 
             if (mask & POLL_READ) _sig_read();

--- a/src/Network/TCP.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/TCP.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,6 +1,12 @@
 #ifndef NETWORK_TCP_HH
 #define NETWORK_TCP_HH
 
+/**
+ * @file
+ *
+ * Simple message-based TCP implementation
+ */
+
 #include <ClanLib/core.h>
 
 #include "Socket.hh"
@@ -19,7 +25,12 @@
 // @}
 
 /**
- * A connected TCP socket, so either a client or a server-accept socket
+ * A connected TCP socket, so either a client or a server's accept'd socket. Can be used to send/receive messages.
+ *
+ * Not instanted directly, use NetworkTCPServer/NetworkTCPClient.
+ *
+ * Most of the functionality is present in NetworkSocket/NetworkBuffer*, so mostly this just implements the
+ * higher-level logic for reading messages, triggering signals, driving connect/listen and maintaing the poll flags.
  */
 class NetworkTCPTransport {
     protected:
@@ -120,7 +131,8 @@
 
     public:
         /**
-         * Listen on the specific address.
+         * Listen on the specific endpoint for incoming client connections. \a listen_addr may be a hostname, a
+         * suitable address will be chosen.
          */
         NetworkTCPServer (const NetworkEndpoint &listen_addr);
 
@@ -158,7 +170,10 @@
 class NetworkTCPClient : public NetworkTCPTransport {
     public:
         /**
-         * Create a NetworkTCPTransport, and then connect our socket to the given address.
+         * Create a NetworkTCPTransport, and then connect our socket to the given remote endpoint
+         *
+         * This is address-family-agnostic, and fully supports endpoints with multiple addresses. They will be tried in
+         * turn until one works.
          *
          * @param connect_addr the address to connect to
          */

--- a/src/Network/UDP.hh	Fri Jan 16 21:24:45 2009 +0200
+++ b/src/Network/UDP.hh	Fri Jan 16 22:03:49 2009 +0200
@@ -1,6 +1,12 @@
 #ifndef NETWORK_UDP_HH
 #define NETWORK_UDP_HH
 
+/**
+ * @file
+ *
+ * UDP implementation
+ */
+
 #include "Socket.hh"
 #include "Address.hh"
 #include "Packet.hh"
@@ -44,6 +50,9 @@
     public:
         /**
          * Send the given packet on this UDP socket to the given destination address
+         *
+         * @return true if the packet was passed on to the socket API, false if the socket was busy and the packet was
+         * dropped (no chance of it arriving).
          */
         bool sendto (const NetworkPacketBuffer &packet, const NetworkAddress &dst);