tests: document test API

Add some comments to the test header file.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

diff --git a/tests/unit/gpiod-unit.h b/tests/unit/gpiod-unit.h
index 8e97244f213c4757ac4ea07d4dfb18b01f630ce2..6b6dd3eedc4daa3575a9b52335b4e7c983ca4c65 100644 (file)
--- a/tests/unit/gpiod-unit.h
+++ b/tests/unit/gpiod-unit.h
@@ -48,6 +48,19 @@ void _gu_test_failed(const char *fmt, ...) GU_PRINTF(1, 2);
        }                                                               \
        static int _gu_##test##_sentinel GU_UNUSED
 
+/*
+ * This macro should be used for code brevity instead of manually declaring
+ * the gu_test structure.
+ *
+ * The macro accepts the following arguments:
+ *   _a_func: name of the test function
+ *   _a_name: name of the test case (will be shown to user)
+ *   _a_named_lines: indicate whether we want the GPIO lines to be named
+ *
+ * The last argument must be an array of unsigned integers specifying the
+ * number of GPIO lines in each subsequent mockup chip. The size of this
+ * array will at the same time specify the number of gpiochips to create.
+ */
 #define GU_DEFINE_TEST(_a_func, _a_name, _a_named_lines, ...)          \
        static unsigned int _##_a_func##_lines[] = __VA_ARGS__;         \
        static struct gu_test _##_a_func##_descr = {                    \
@@ -66,10 +79,32 @@ enum {
        GU_LINES_NAMED = true,
 };
 
+/*
+ * We want libgpiod tests to co-exist with gpiochips created by other GPIO
+ * drivers. For that reason we can't just use hardcoded device file paths or
+ * gpiochip names.
+ *
+ * The test suite detects the chips that were exported by the gpio-mockup
+ * module and stores them in the internal test context structure. Test cases
+ * should use the routines declared below to access the gpiochip path, name
+ * or number by index corresponding with the order in which the mockup chips
+ * were requested in the GU_DEFINE_TEST() macro.
+ */
 const char * gu_chip_path(unsigned int index);
 const char * gu_chip_name(unsigned int index);
 unsigned int gu_chip_num(unsigned int index);
 
+/*
+ * Every GU_ASSERT_*() macro expansion can make a test function return, so it
+ * would be quite difficult to keep track of every resource allocation. At
+ * the same time we don't want any deliberate memory leaks as we also use this
+ * test suite to find actual memory leaks in the library with valgrind.
+ *
+ * For this reason, the tests should generally always use the GU_CLEANUP()
+ * macro for dynamically allocated variables and objects that need closing.
+ *
+ * The functions below can be reused by different tests for common use cases.
+ */
 void gu_close_chip(struct gpiod_chip **chip);
 void gu_free_str(char **str);
 void gu_free_chip_iter(struct gpiod_chip_iter **iter);