--- a/src/Network/Address.hh	Fri Jan 16 01:05:34 2009 +0200
+++ b/src/Network/Address.hh	Fri Jan 16 21:24:45 2009 +0200
@@ -1,22 +1,27 @@
 #ifndef NETWORK_ADDRESS_H
 #define NETWORK_ADDRESS_H
 
+/**
+ * @file
+ *
+ * Binary NetworkAddress
+ */
+
+#include "Platform.hh"
 #include "Endpoint.hh"
 
-/*
- * Platform-specific includes
- */
-#ifndef WIN32
-    // linux
-    #include <netinet/in.h>
-#else
-    #error "This network code won't compile on win32 :)"
-#endif
-
 /**
- * This represents a `struct sockaddr` as used by the socket API.
+ * A NetworkAddress represents a single network address in the form of a `struct sockaddr`, as used by the OS's socket
+ * API. A NetworkAddress's value may only be constructed/manipulated in sockaddr form, and the class then emulates the
+ * get_addrinfo (by building our own addrinfo struct value) and get_hostname()/get_service() (by using libc's
+ * getnameinfo() when the address is updated).
  *
- * It can be used like a NetworkEndpoint, but it's also suitable for use with recvfrom/sendto
+ * This means that a NetworkAddress can be used like a NetworkEndpoint (like a literal IP address), but can also be
+ * used in a more specifc fashion like NetworkSocket::send or NetworkSocket::accept, where a definitive address is
+ * required.
+ *
+ * XXX: currently, there is no way to form a NetworkAddress from a NetworkEndpoint for e.g. sending UDP packets without
+ * an associated TCP connection.
  */
 class NetworkAddress : public NetworkEndpoint {
     protected: