--- a/qmsk/net/socket/__init__.py	Tue Aug 18 23:02:56 2009 +0300
+++ b/qmsk/net/socket/__init__.py	Wed Aug 19 00:12:07 2009 +0300
@@ -1,5 +1,6 @@
 """
-    The low-level OS Socket API and related functionality, covering the Internet layer.
+    The low-level OS Socket API and related functionality, covering the Network layer. This includes network addresses
+    and hostname resolving.
 
     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.

--- a/qmsk/net/transport/__init__.py	Tue Aug 18 23:02:56 2009 +0300
+++ b/qmsk/net/transport/__init__.py	Wed Aug 19 00:12:07 2009 +0300
@@ -2,4 +2,98 @@
     Transport-layer functionality.
 
     This implements TCP/UDP/SCTP functionality, plus relevant Transport-Application layer stuff like TLS, SOCKS, SSH-channels, etc.
+
+    Firstly, this defines a set of abstract interfaces that model the actual implementation as built on top of the
+    socket packages's network-layer implementation:
+
+
+    Interfaces:
+
+        Transport           - very abstract interface that embodies the notion of sending something somewhere
+
+            ConnectedTransport      - connection-oriented transport
+            
+                Stream                  - connection-oriented full-duplex byte stream (reliable, sequenced)
+    
+                PacketStream            - connection-oriented full-duplex packet-oriented communication
+ 
+
+            UnconnectedTransport    - non-connection-oriented transport dealing with packets
+
+                Peer                    - connectionless packet-oriented communication
+
+
+        Endpoint        - some transport-level endpoint (local/remote address/socket)
+
+            Client          - connection-oriented endpoint that can establish a Transport to some remote Service
+
+            Service         - listening endpoint that recieves connections from remote Clients and represents those as Transports
+
+
+    Next, there are some mid-level helpers, mostly for dealing with 
+
+
+    Then there is are implementations of these interfaces for specific protocols, layering on top of the socket module,
+    or other application-level protocols.
+
+    TCP:
+        TCP implementation using a SOCK_STREAM socket.
+
+        Stream          - connected TCP socket with TCP's byte stream semantics
+
+        Service         - TCP socket accept()'ing Streams from remote Clients
+
+        Client          - TCP socket connect()'ing to a remote Service
+
+
+    UDP:
+        UDP implementation using a SOCK_DGRAM socket.
+
+        Peer            - bind()'d UDP socket without any connection
+
+        Client          - connect()'d UDP socket, representing a PacketStream
+
+
+    UNIX:
+        UNIX socket implementation support both SOCK_STREAM and SOCK_DGRAM.
+
+        XXX: verify that this is correct...
+
+        Stream          - connected AF_UNIX SOCK_STREAM
+
+        Service         - accept()'ing AF_UNIX socket of either SOCK_STREAM mode
+
+        Client          - connect()'ing AF_UNIX socket of SOCK_STREAM mode
+
+        Peer            - bind()'d AF_UNIX socket of SOCK_DGRAM mode
+
+    SCTP:
+        SCTP implementation offering both SOCK_SEQPACKET and SOCK_STREAM -based socket interfaces.
+
+        Stream          - a PacketStream carried by an Association
+
+        Association     - a Transport that represents a SCTP association between a local and remote Endpoint
+
+        Peer            - one-to-many style interface, with a single Peer holding multiple Associations
+
+        Service         - a one-to-one style listen()'ing interface which accepts Associations from remote Endpoints
+
+        Client          - a one-to-one style connect()'ing interface which establishes Associations with remote Endpoints
+
+    SSL:
+        SSL implementation using either OpenSSL or gnutls.
+
+        Stream          - tcp.Stream carrying an encrypted byte stream
+
+        Service         - tcp.Service accepting connections from SSL endpoints
+
+        Client          - tcp.Client connecting to an SSL service
+
+    SOCKS:
+        SOCKSv5 client implementing TCP client serviecs.
+
+        Stream          - tcp.Stream carried over a SOCKSv5 connections
+
+        Client          - tcp.Client connecting via a SOCKSv5 server
+        
 """