From 13e205a0e5042f967a6993b79dafd3bd9bee9002 Mon Sep 17 00:00:00 2001
From: Michael Jumper <mike.jumper@guac-dev.org>
Date: Wed, 7 May 2014 21:19:15 -0700
Subject: [PATCH] GUAC-654: Add missing comments to telnet_client.c

---
 src/protocols/telnet/telnet_client.c | 51 ++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/src/protocols/telnet/telnet_client.c b/src/protocols/telnet/telnet_client.c
index 9ceff036..d6ff6426 100644
--- a/src/protocols/telnet/telnet_client.c
+++ b/src/protocols/telnet/telnet_client.c
@@ -41,6 +41,10 @@
 #include <guacamole/socket.h>
 #include <libtelnet.h>
 
+/**
+ * Support levels for various telnet options, required for connection
+ * negotiation by telnet_init(), part of libtelnet.
+ */
 static const telnet_telopt_t __telnet_options[] = {
     { TELNET_TELOPT_ECHO,      TELNET_WONT, TELNET_DO   },
     { TELNET_TELOPT_TTYPE,     TELNET_WILL, TELNET_DONT },
@@ -50,6 +54,16 @@ static const telnet_telopt_t __telnet_options[] = {
     { -1, 0, 0 }
 };
 
+/**
+ * Write the entire buffer given to the specified file descriptor, retrying
+ * the write automatically if necessary. This function will return a value
+ * not equal to the buffer's size iff an error occurs which prevents all
+ * future writes.
+ *
+ * @param fd The file descriptor to write to.
+ * @param buffer The buffer to write.
+ * @param size The number of bytes from the buffer to write.
+ */
 static int __guac_telnet_write_all(int fd, const char* buffer, int size) {
 
     int remaining = size;
@@ -70,6 +84,11 @@ static int __guac_telnet_write_all(int fd, const char* buffer, int size) {
 
 }
 
+/**
+ * Event handler, as defined by libtelnet. This function is passed to
+ * telnet_init() and will be called for every event fired by libtelnet,
+ * including feature enable/disable and receipt/transmission of data.
+ */
 static void __guac_telnet_event_handler(telnet_t* telnet, telnet_event_t* event, void* data) {
 
     guac_client* client = (guac_client*) data;
@@ -134,6 +153,14 @@ static void __guac_telnet_event_handler(telnet_t* telnet, telnet_event_t* event,
 
 }
 
+/**
+ * Input thread, started by the main telnet client thread. This thread
+ * continuously reads from the terminal's STDIN and transfers all read
+ * data to the telnet connection.
+ *
+ * @param data The current guac_client instance.
+ * @return Always NULL.
+ */
 static void* __guac_telnet_input_thread(void* data) {
 
     guac_client* client = (guac_client*) data;
@@ -153,6 +180,14 @@ static void* __guac_telnet_input_thread(void* data) {
 
 }
 
+/**
+ * Connects to the telnet server specified within the data associated
+ * with the given guac_client, which will have been populated by
+ * guac_client_init.
+ *
+ * @return The connected telnet instance, if successful, or NULL if the
+ *         connection fails for any reason.
+ */
 static telnet_t* __guac_telnet_create_session(guac_client* client) {
 
     int retval;
@@ -243,6 +278,13 @@ static telnet_t* __guac_telnet_create_session(guac_client* client) {
 
 }
 
+/**
+ * Sends a 16-bit value over the given telnet connection with the byte order
+ * required by the telnet protocol.
+ *
+ * @param telnet The telnet connection to use.
+ * @param value The value to send.
+ */
 static void __guac_telnet_send_uint16(telnet_t* telnet, uint16_t value) {
 
     unsigned char buffer[2];
@@ -260,6 +302,15 @@ void guac_telnet_send_naws(telnet_t* telnet, uint16_t width, uint16_t height) {
     telnet_finish_sb(telnet);
 }
 
+/**
+ * Waits for data on the given file descriptor for up to one second. The
+ * return value is identical to that of select(): 0 on timeout, < 0 on
+ * error, and > 0 on success.
+ *
+ * @param socket_fd The file descriptor to wait for.
+ * @return A value greater than zero on success, zero on timeout, and
+ *         less than zero on error.
+ */
 static int __guac_telnet_wait(int socket_fd) {
 
     fd_set fds;