From 14522dab22279da6555bf2eccfae2812b7113dbf Mon Sep 17 00:00:00 2001
From: Michael Jumper <mike.jumper@guac-dev.org>
Date: Tue, 1 Mar 2016 13:02:42 -0800
Subject: [PATCH] GUAC-1389: Add missing documentation for socket handlers.

---
 src/libguac/socket-fd.c   | 58 +++++++++++++++++++++++++++++++++++++++
 src/libguac/socket-nest.c | 11 ++++++++
 2 files changed, 69 insertions(+)

diff --git a/src/libguac/socket-fd.c b/src/libguac/socket-fd.c
index c1a6b42c..b137e38f 100644
--- a/src/libguac/socket-fd.c
+++ b/src/libguac/socket-fd.c
@@ -129,6 +129,22 @@ ssize_t guac_socket_fd_write(guac_socket* socket,
 
 }
 
+/**
+ * Attempts to read from the underlying file descriptor of the given
+ * guac_socket, populating the given buffer.
+ *
+ * @param socket
+ *     The guac_socket being read from.
+ *
+ * @param buf
+ *     The arbitrary buffer which we must populate with data.
+ *
+ * @param count
+ *     The maximum number of bytes to read into the buffer.
+ *
+ * @return
+ *     The number of bytes read, or -1 if an error occurs.
+ */
 static ssize_t guac_socket_fd_read_handler(guac_socket* socket,
         void* buf, size_t count) {
 
@@ -176,6 +192,16 @@ static ssize_t guac_socket_fd_flush(guac_socket* socket) {
 
 }
 
+/**
+ * Flushes the internal buffer of the given guac_socket, writing all data
+ * to the underlying file descriptor.
+ *
+ * @param socket
+ *     The guac_socket to flush.
+ *
+ * @return
+ *     Zero if the flush operation was successful, non-zero otherwise.
+ */
 static ssize_t guac_socket_fd_flush_handler(guac_socket* socket) {
 
     int retval;
@@ -258,6 +284,23 @@ static ssize_t guac_socket_fd_write_buffered(guac_socket* socket,
 
 }
 
+/**
+ * Appends the provided data to the internal buffer for future writing. The
+ * actual write attempt will occur only upon flush, or when the internal buffer
+ * is full.
+ *
+ * @param socket
+ *     The guac_socket being write to.
+ *
+ * @param buf
+ *     The arbitrary buffer containing the data to be written.
+ *
+ * @param count
+ *     The number of bytes contained within the buffer.
+ *
+ * @return
+ *     The number of bytes written, or -1 if an error occurs.
+ */
 static ssize_t guac_socket_fd_write_handler(guac_socket* socket,
         const void* buf, size_t count) {
 
@@ -277,6 +320,21 @@ static ssize_t guac_socket_fd_write_handler(guac_socket* socket,
 
 }
 
+/**
+ * Waits for data on the underlying file desriptor of the given socket to
+ * become available such that the next read operation will not block.
+ *
+ * @param socket
+ *     The guac_socket to wait for.
+ *
+ * @param usec_timeout
+ *     The maximum amount of time to wait for data, in microseconds, or -1 to
+ *     potentially wait forever.
+ *
+ * @return
+ *     A positive value on success, zero if the timeout elapsed and no data is
+ *     available, or a negative value if an error occurs.
+ */
 static int guac_socket_fd_select_handler(guac_socket* socket,
         int usec_timeout) {
 
diff --git a/src/libguac/socket-nest.c b/src/libguac/socket-nest.c
index 3fb1b163..8ce57672 100644
--- a/src/libguac/socket-nest.c
+++ b/src/libguac/socket-nest.c
@@ -105,6 +105,17 @@ ssize_t __guac_socket_nest_write_handler(guac_socket* socket,
 
 }
 
+/**
+ * Frees all implementation-specific data associated with the given socket, but
+ * not the socket object itself.
+ *
+ * @param socket
+ *     The guac_socket whose associated data should be freed.
+ *
+ * @return
+ *     Zero if the data was successfully freed, non-zero otherwise. This
+ *     implementation always succeeds, and will always return zero.
+ */
 static int __guac_socket_nest_free_handler(guac_socket* socket) {
 
     /* Free associated data */