Complete public socket API documentation

Signed-off-by: Michael Steinert <mike.steinert@gmail.com>

1 files changed, 41 insertions, 0 deletions

diff --git a/librabbitmq/amqp_socket.h b/librabbitmq/amqp_socket.h
index a40d13e..cee399b 100644
--- a/librabbitmq/amqp_socket.h
+++ b/librabbitmq/amqp_socket.h
@@ -20,6 +20,10 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * An abstract socket interface.
+ */
+
 #ifndef AMQP_SOCKET_H
 #define AMQP_SOCKET_H
 
@@ -37,6 +41,7 @@ typedef int (*amqp_socket_close_fn)(void *);
 typedef int (*amqp_socket_error_fn)(void *);
 typedef int (*amqp_socket_get_sockfd_fn)(void *);
 
+/** V-table for amqp_socket_t */
 struct amqp_socket_class_t {
 	amqp_socket_writev_fn writev;
 	amqp_socket_send_fn send;
@@ -47,16 +52,52 @@ struct amqp_socket_class_t {
 	amqp_socket_get_sockfd_fn get_sockfd;
 };
 
+/** Abstract base class for amqp_socket_t */
 struct amqp_socket_t_ {
 	const struct amqp_socket_class_t *klass;
 };
 
+/**
+ * Write to a socket.
+ *
+ * This function is analagous to writev(2).
+ *
+ * \param [in,out] self A socket object.
+ * \param [in] iov One or more data vecors.
+ * \param [in] iovcnt The number of vectors in \e iov.
+ *
+ * \return The number of bytes written, or -1 if an error occurred.
+ */
 ssize_t
 amqp_socket_writev(amqp_socket_t *self, const struct iovec *iov, int iovcnt);
 
+/**
+ * Send a message from a socket.
+ *
+ * This function is analagous to send(2).
+ *
+ * \param [in,out] self A socket object.
+ * \param [in] buf A buffer to read from.
+ * \param [in] len The number of bytes in \e buf.
+ * \param [in] flags Send flags, implementation specific.
+ *
+ * \return The number of bytes sent, or -1 if an error occurred.
+ */
 ssize_t
 amqp_socket_send(amqp_socket_t *self, const void *buf, size_t len, int flags);
 
+/**
+ * Receive a message from a socket.
+ *
+ * This function is analagous to recv(2).
+ *
+ * \param [in,out] self A socket object.
+ * \param [out] buf A buffer to write to.
+ * \param [in] len The number of bytes at \e buf.
+ * \param [in] flags Receive flags, implementation specific.
+ *
+ * \return The number of bytes received, or -1 if an error occurred.
+ */
 ssize_t
 amqp_socket_recv(amqp_socket_t *self, void *buf, size_t len, int flags);