From b4ffc870333113d96c299a5825403860ab2e99b9 Mon Sep 17 00:00:00 2001
From: Michael Jumper <mike.jumper@guac-dev.org>
Date: Tue, 6 Aug 2013 12:13:47 -0700
Subject: [PATCH] Comment util_suite.h thoroughly.

---
 tests/util/util_suite.h | 47 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

diff --git a/tests/util/util_suite.h b/tests/util/util_suite.h
index 2b878e64..02c4f882 100644
--- a/tests/util/util_suite.h
+++ b/tests/util/util_suite.h
@@ -38,16 +38,53 @@
 #ifndef _GUAC_TEST_UTIL_SUITE_H
 #define _GUAC_TEST_UTIL_SUITE_H
 
-/* Unicode (UTF-8) strings */
+/**
+ * Test suite containing unit tests for utility functions built into libguac.
+ * These utility functions are included for convenience rather as integral
+ * requirements of the core.
+ *
+ * @file util_suite.h
+ */
 
-#define UTF8_1b "g"                /* One byte    */
-#define UTF8_2b "\xc4\xa3"         /* Two bytes   */
-#define UTF8_3b "\xe7\x8a\xac"     /* Three bytes */
-#define UTF8_4b "\xf0\x90\x84\xa3" /* Four bytes  */
 
+/**
+ * A single Unicode character encoded as one byte with UTF-8.
+ */
+#define UTF8_1b "g"
+
+/**
+ * A single Unicode character encoded as two bytes with UTF-8.
+ */
+#define UTF8_2b "\xc4\xa3"
+
+/**
+ * A single Unicode character encoded as three bytes with UTF-8.
+ */
+#define UTF8_3b "\xe7\x8a\xac"
+
+/**
+ * A single Unicode character encoded as four bytes with UTF-8.
+ */
+#define UTF8_4b "\xf0\x90\x84\xa3"
+
+/**
+ * Registers the utility test suite with CUnit.
+ */
 int register_util_suite();
 
+/**
+ * Unit test for the guac_pool structure and related functions. The guac_pool
+ * structure provides a consistent source of pooled integers. This unit test
+ * checks that the associated functions behave as documented (returning
+ * integers in the proper order, allocating new integers as necessary, etc.).
+ */
 void test_guac_pool();
+
+/**
+ * Unit test for libguac's Unicode convenience functions. This test checks that
+ * the functions provided for determining string length, character length, and
+ * for reading and writing UTF-8 behave as specified in the documentation.
+ */
 void test_guac_unicode();
 
 #endif