GUACAMOLE-1538: Add missing documentation for libguac-terminal functions.

src/terminal/terminal/terminal.h

@@ -276,6 +276,9 @@ guac_terminal_options* guac_terminal_options_create(
 
 /**
  * Frees all resources associated with the given terminal.
+ *
+ * @param term
+ *     The terminal to free.
  */
 void guac_terminal_free(guac_terminal* term);
 
@@ -298,7 +301,7 @@ void guac_terminal_set_upload_path_handler(guac_terminal* terminal,
  * @param terminal
  *     The terminal to set the file download handler for.
  *
- * @param upload_path_handler
+ * @param file_download_handler
  *      The handler to be called whenever the necessary terminal codes are sent to
  *      the given terminal to initiate a download of a given remote file.
  */
@@ -308,6 +311,13 @@ void guac_terminal_set_file_download_handler(guac_terminal* terminal,
 /**
  * Renders a single frame of terminal data. If data is not yet available,
  * this function will block until data is written.
+ *
+ * @param terminal
+ *     The terminal that should be rendered.
+ *
+ * @return
+ *     Zero if the frame was rendered successfully, non-zero if an error
+ *     occurred.
  */
 int guac_terminal_render_frame(guac_terminal* terminal);
 
@@ -316,6 +326,19 @@ int guac_terminal_render_frame(guac_terminal* terminal);
  * supplied by calls to guac_terminal_send_key(),
  * guac_terminal_send_mouse(), and guac_terminal_send_stream(). If input is not
  * yet available, this function will block.
+ *
+ * @param terminal
+ *     The terminal to read from.
+ *
+ * @param c
+ *     The buffer that should receive the bytes read.
+ *
+ * @param size
+ *     The number of bytes available within the buffer.
+ *
+ * @return
+ *     The number of bytes read into the buffer, zero if end-of-file is reached
+ *     (STDIN has been closed), or a negative value if an error occurs.
  */
 int guac_terminal_read_stdin(guac_terminal* terminal, char* c, int size);
 
@@ -377,8 +400,23 @@ char* guac_terminal_prompt(guac_terminal* terminal, const char* title,
 
 /**
  * Writes the given format string and arguments to this terminal's STDOUT in
- * the same manner as printf(). This function may block until space is
+ * the same manner as printf(). The entire populated format string will always
+ * be written unless an error occurs. This function may block until space is
  * freed in the output buffer by guac_terminal_render_frame().
+ *
+ * @param terminal
+ *     The terminal to write to.
+ *
+ * @param format
+ *     A printf-style format string describing the data to be written to
+ *     STDOUT.
+ *
+ * @param ...
+ *     Any arguments to use when filling the format string.
+ *
+ * @return
+ *     The number of bytes written to STDOUT, or a negative value if an error
+ *     occurs preventing the data from being written in its entirety.
  */
 int guac_terminal_printf(guac_terminal* terminal, const char* format, ...);
 
@@ -486,9 +524,24 @@ int guac_terminal_send_data(guac_terminal* term, const char* data, int length);
 int guac_terminal_send_string(guac_terminal* term, const char* data);
 
 /**
- * Writes the given string of characters to the terminal.
+ * Writes the given buffer to the given terminal's STDOUT. All requested bytes
+ * will be written unless an error occurs. This function may block until space
+ * is freed in the output buffer by guac_terminal_render_frame().
+ *
+ * @param term
+ *     The terminal to write to.
+ *
+ * @param buffer
+ *     A buffer containing the characters to be written to the terminal.
+ *
+ * @param length
+ *     The number of bytes within the given string to write to the terminal.
+ *
+ * @return
+ *     The number of bytes written to STDOUT, or a negative value if an error
+ *     occurs preventing the data from being written in its entirety.
  */
-int guac_terminal_write(guac_terminal* term, const char* c, int size);
+int guac_terminal_write(guac_terminal* term, const char* buffer, int length);
 
 /**
  * Initializes the handlers of the given guac_stream such that it serves as the
@@ -532,7 +585,7 @@ int guac_terminal_send_stream(guac_terminal* term, guac_user* user,
  *     STDIN.
  *
  * @param ...
- *     Any srguments to use when filling the format string.
+ *     Any arguments to use when filling the format string.
  *
  * @return
  *     The number of bytes written to STDIN, or a negative value if an error
@@ -560,7 +613,20 @@ void guac_terminal_dup(guac_terminal* term, guac_user* user,
         guac_socket* socket);
 
 /**
- * Resize the terminal to the given dimensions.
+ * Resize the client display and terminal to the given pixel dimensions.
+ *
+ * @param term
+ *     The terminal to resize.
+ *
+ * @param width
+ *     The new terminal width, in pixels.
+ *
+ * @param height
+ *     The new terminal height, in pixels.
+ *
+ * @return
+ *     Zero if the terminal was successfully resized to the given dimensions,
+ *     non-zero otherwise.
  */
 int guac_terminal_resize(guac_terminal* term, int width, int height);