--- a/qmsk/net/socket/__init__.py	Tue Aug 18 22:24:36 2009 +0300
+++ b/qmsk/net/socket/__init__.py	Tue Aug 18 23:02:30 2009 +0300
@@ -1,6 +1,62 @@
-# combine all the modules
+"""
+    The low-level OS Socket API and related functionality, covering the Internet layer.
+
+    All functionality provided here aims to be a thin wrapper around the native system API, so for the most part, methods
+    map directly to *one* syscall/libc call.
+
+    Provided modules/types:
+    
+    address:
+        Abstract socket addresses.
+
+        sockaddr        - corresponds to the `struct sockaddr` used in socket API calls. This is an abstract type
+                          that cannot itself be instantated, see `sockaddr_in`/`sockaddr_in6`/`endpoint`.
+
+        addrinfo        - corresponds to the `struct addrinfo` used by the GAI API. Hold a concrete `sockaddr`
+
+        endpoint        - abstract internet hostname+service address as handled by getaddrinfo. Maps to a series of `addrinfo`'s.
+    
+    af_inet:
+        AF_INET (IPv4) -specific functionality.
+
+        sockaddr_in     - AF_INET sockaddr with addr, port fields
+
+    af_inet6:
+        AF_INET6 (IPv6) -specific functionality.
+
+        sockaddr_in6    - AF_INET6 sockaddr with addr, port, flowinfo, scope_id fields
+    
+    socket:
+        Core socket API.
+
+        socket          - socket-related syscalls with a guaranteed 1:1 mapping between methods and library
+                          calls.
+        
+    sctp:
+        SCTP-specific socket API
+
+        sctp_socket     - extension of socket.socket to support SCTP-specific socket API extensions
+    
+    constants:
+        Socket-related constants.
+
+        AF_*            - address families
+        SOCK_*          - socket types
+        IPPROTO_*       - inet protocols
+        MSG_*           - send/recv message flags
+
+        etc.
+"""
+
+## XXX: these shadow the modules... how do we want to provide these?
+#from qmsk.net.socket.address import sockaddr, addrinfo, endpoint
+#
+#from qmsk.net.socket.af_inet import sockaddr_in
+#from qmsk.net.socket.af_inet6 import sockaddr_in6
+#
+#from qmsk.net.socket.socket import socket
+#from qmsk.net.socket.sctp import sctp_socket
+#
 #from qmsk.net.socket.constants import *
-#from qmsk.net.socket.platform import *
-#from qmsk.net.socket.addr import *
-#from qmsk.net.socket.socket import *
+#