--- a/src/sock.h	Tue Mar 10 03:48:00 2009 +0200
+++ b/src/sock.h	Tue Mar 10 19:52:38 2009 +0200
@@ -1,29 +1,34 @@
 #ifndef SOCK_H
 #define SOCK_H
 
-/*
+/**
+ * @file
+ *
  * Low-level socket-related functions
  */
 #include "error.h"
 #include <sys/types.h>
 #include <event2/event.h>
 
-/*
- * The generic socket handle
+/**
+ * The generic stream socket handle
  */
 struct sock_stream;
 
-/*
+/**
  * Async callbacks for socket operation
  */
 struct sock_stream_callbacks {
-    /* Sockeet is readable */
+    /** Sockeet is readable */
     void (*on_read)(struct sock_stream *sock, void *arg);
 
-    /* Socket is writeable */
+    /** Socket is writeable */
     void (*on_write)(struct sock_stream *sock, void *arg);
 };
 
+/**
+ * Socket function error codes
+ */
 enum sock_error_code {
     _ERR_SOCK_BEGIN = _ERR_SOCK,
     
@@ -52,18 +57,24 @@
     ERR_CLOSE,
 };
 
-/*
+/**
  * Initialize the socket module's global state. Call this before calling any other sock_* functions.
  *
  * The given \a ev_base is the libevent base to use for nonblocking operation.
+ *
+ * @param ev_base the libevent base to use for events
+ * @param err returned error info
  */
 err_t sock_init (struct event_base *ev_base, struct error_info *err);
 
-/*
+/**
  * A simple blocking TCP connect to the given host/service, using getaddrinfo. The connected socket is returned via
  * *sock_ptr. In case of errors, additional error information is stored in *err.
  *
- * @return zero on success, nonzero on error
+ * @param sock_ptr the new sock_stream
+ * @param host the hostname to connect to
+ * @param service the service name (i.e. port) to connect to
+ * @param err returned error info
  *
  * XXX: blocking
  */
@@ -73,34 +84,67 @@
  * A simple blocking SSL connect to the given host/service. The connected/handshake'd SSL socket is returned via
  * *sock_ptr. In case of errors, additional error information is stored in *err.
  *
+ * @param sock_ptr the new sock_stream
+ * @param host the hostname to connect to
+ * @param service the TCP service name (i.e. port) to connect to
+ * @param err returned error info
+ *
  * XXX: blocking
  * XXX: doesn't do any certificate verification.
  */
 err_t sock_ssl_connect (struct sock_stream **sock_ptr, const char *host, const char *service, struct error_info *err);
 
-/*
- * 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.
+/**
+ * Read a series of bytes from the socket into the given \a buf (up to \a len bytes). If succesfull, this returns
+ * the number of bytes read (which will be less than or equal to \a len). If the socket is nonblocking (i.e.
+ * sock_stream_event_init() was set), and there is no data available, this returns zero, and one should use
+ * sock_stream_event_enable() to wait for more data.
+ *
+ * On errors, this returns the negative err_t code, and the specific error information can be accessed using
+ * sock_stream_error()..
+ *
+ * @param sock the socket to read the bytes from
+ * @param buf the byte buffer to write the bytes into
+ * @param len the number of bytes to read into the buffer
+ * @return bytes read, zero if none available, -err_t
  */
 int sock_stream_read (struct sock_stream *sock, void *buf, size_t len);
+
+/**
+ * Write a series of bytes from the given \a buf (containing \a len bytes) to the socket. If succesfull, this returns
+ * the number of bytes written (which may be less than \a len if the OS write buffer was full). If the socket is
+ * nonblocking (i.e. sock_stream_event_init() was set), and the operation would have blocked, no data was written, and
+ * this returns zero, and one should use sock_stream_event_enable() to retry.
+ *
+ * On errors, this returns the negative err_t code, and the specific error information can be accessed using
+ * sock_stream_error().
+ *
+ * @param sock the socket to write the bytes to
+ * @param buf the byte buffer
+ * @param len number of bytes to write
+ * @return bytes written, zero if would have blocked, -err_t
+ */
 int sock_stream_write (struct sock_stream *sock, const void *buf, size_t len);
 
-/*
+/**
  * Initialize event-based operation for this sock_stream. This will set the stream into nonblocking mode, and the given
  * callbacks will be fired once enabled using sock_stream_event_enable().
  *
  * Note that the callbacks struct isn't copied - it's used as-is-given.
+ *
+ * @param sock the socket to set up for nonblocking operation
+ * @param callbacks the on_read/on_write callbacks to invoke
+ * @param arg the context argument for the callbacks
  */
 err_t sock_stream_event_init (struct sock_stream *sock, const struct sock_stream_callbacks *callbacks, void *arg);
 
-/*
- * Enable the events for this sock, as set up earlier with event_init. Mask should contain EV_READ/EV_WRITE.
+/**
+ * Enable some events for this sock, as set up earlier with event_init. Mask should contain EV_READ/EV_WRITE.
  *
  * 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.
+ * call event_enable(EV_READ), wherepon on_read will later be called. Other operations (such as calling
+ * sock_stream_write with *different* data after it once returns zero) might result in errors.
  */
 err_t sock_stream_event_enable (struct sock_stream *sock, short mask);