--- a/src/sock.h	Sat Feb 28 17:39:37 2009 +0200
+++ b/src/sock.h	Sat Feb 28 18:48:10 2009 +0200
@@ -51,7 +51,10 @@
 err_t sock_gnutls_connect (struct sock_stream **sock_ptr, const char *host, const char *service, struct error_info *err);
 
 /*
- * The generic read/write API for stream sockets.
+ * The generic read/write API for stream sockets. These are mostly identical to the equivalent read/write syscalls, but
+ * the handling of EOF and EAGAIN is different. Normally, these return the (positive) number of bytes written. For
+ * EAGAIN, these return zero. For EOF, these return -ERR_READ_EOF/ERR_WRITE_EOF. Otherwise, these return the -ERR_*
+ * code.
  */
 int sock_stream_read (struct sock_stream *sock, void *buf, size_t len);
 int sock_stream_write (struct sock_stream *sock, const void *buf, size_t len);
@@ -65,10 +68,11 @@
 err_t sock_stream_event_init (struct sock_stream *sock, const struct sock_stream_callbacks *callbacks, void *arg);
 
 /*
- * Prime the callbacks set up earlier with sock_stream_event_init to fire once ready.
+ * Enable the events for this sock, as set up earlier with event_init. Mask should contain EV_READ/EV_WRITE.
  *
- * \a mask is a bitmask of EV_* bits, such as EV_READ, EV_WRITE or EV_PERSIST. See event_set() for more info about the
- * behaviour of those.
+ * The implementation of this is slightly hazy for complex protocols; this should only be used to map from
+ * sock_stream_read/write to the corresponding sock_stream_callback. That is, if sock_stream_read returns zero, then
+ * call event_enable(EV_READ), wherepon on_read will later be called.
  */
 err_t sock_stream_event_enable (struct sock_stream *sock, short mask);