--- 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);
 };