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