[PATCH 2/4] test: document ut.h
Heinrich Schuchardt
heinrich.schuchardt at canonical.com
Tue Nov 18 21:17:31 CET 2025
Add missing Sphinx comments in include/test/ut.h
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
---
include/test/ut.h | 159 ++++++++++++++++++++++++++++++++++++++--------
1 file changed, 132 insertions(+), 27 deletions(-)
diff --git a/include/test/ut.h b/include/test/ut.h
index be5502e03a1..79c11367471 100644
--- a/include/test/ut.h
+++ b/include/test/ut.h
@@ -130,18 +130,28 @@ int ut_check_console_end(struct unit_test_state *uts);
*
* This only supports a byte dump.
*
- * @total_bytes: Size of the expected dump in bytes`
- * Return: 0 if OK (looks like a dump and the length matches), other value on
- * error
+ * @uts: Test state
+ * @total_bytes: Size of the expected dump in bytes
+ * Return: 0 if OK (looks like a dump and the length matches),
+ * other value on error
*/
int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
-/* Report a failure, with printf() string */
+/**
+ * ut_report() - Report a failure, with printf() string
+ *
+ * @fmt: format string
+ * @args: arguments to be printed
+ */
#define ut_reportf(fmt, args...) \
ut_failf(uts, __FILE__, __LINE__, __func__, "report", \
fmt, ##args)
-/* Assert that a condition is non-zero */
+/**
+ * ut_assert() - Assert that a condition is true (not 0)
+ *
+ * @cond: condition
+ */
#define ut_assert(cond) ({ \
int __ret = 0; \
\
@@ -152,7 +162,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that a condition is non-zero, with printf() string */
+/**
+ * ut_assertf() - Assert that a condition is true with printf string
+ *
+ * @cond: condition
+ * @fmt: format string
+ * @args: arguments to be printed
+ */
#define ut_assertf(cond, fmt, args...) ({ \
int __ret = 0; \
\
@@ -164,7 +180,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that two int expressions are equal */
+/**
+ * ut_asserteq() - Assert that two int32 expressions are equal
+ *
+ * @expr1: expected value
+ * @expr2: actual value
+ */
#define ut_asserteq(expr1, expr2) ({ \
unsigned int _val1 = (expr1), _val2 = (expr2); \
int __ret = 0; \
@@ -179,7 +200,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that two 64 int expressions are equal */
+/**
+ * ut_asserteq_64() - Assert that two int64 expressions are equal
+ *
+ * @expr1: expected value
+ * @expr2: actual value
+ */
#define ut_asserteq_64(expr1, expr2) ({ \
u64 _val1 = (expr1), _val2 = (expr2); \
int __ret = 0; \
@@ -197,7 +223,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that two string expressions are equal */
+/**
+ * ut_asserteq_str() - Assert that two string expressions are equal
+ *
+ * @expr1: expected value
+ * @expr2: actual value
+ */
#define ut_asserteq_str(expr1, expr2) ({ \
const char *_val1 = (expr1), *_val2 = (expr2); \
int __ret = 0; \
@@ -211,9 +242,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/*
- * Assert that two string expressions are equal, up to length of the
- * first
+/**
+ * ut_asserteq_strn() - Assert that two string expressions are equal
+ * up to the length of the first expression
+ *
+ * @expr1: expected value
+ * @expr2: actual value
*/
#define ut_asserteq_strn(expr1, expr2) ({ \
const char *_val1 = (expr1), *_val2 = (expr2); \
@@ -230,7 +264,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that two memory areas are equal */
+/**
+ * ut_asserteq_mem() - Assert that two memory areas are equal
+ *
+ * @expr1: expected value
+ * @expr2: actual value
+ * @len: length of the memory areas
+ */
#define ut_asserteq_mem(expr1, expr2, len) ({ \
const u8 *_val1 = (u8 *)(expr1), *_val2 = (u8 *)(expr2); \
const uint __len = len; \
@@ -250,7 +290,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that two pointers are equal */
+/**
+ * ut_asserteq_ptr() - Assert that two string pointers are equal
+ *
+ * @expr1: expected value
+ * @expr2: actual value
+ */
#define ut_asserteq_ptr(expr1, expr2) ({ \
const void *_val1 = (expr1), *_val2 = (expr2); \
int __ret = 0; \
@@ -264,7 +309,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that two addresses (converted from pointers) are equal */
+/**
+ * ut_asserteq_addr() - Assert that two addresses (converted from pointers)
+ * are equal
+ *
+ * @expr1: expected value
+ * @expr2: actual value
+ */
#define ut_asserteq_addr(expr1, expr2) ({ \
ulong _val1 = map_to_sysmem(expr1); \
ulong _val2 = map_to_sysmem(expr2); \
@@ -279,7 +330,11 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that a pointer is NULL */
+/**
+ * ut_assertnull() - Assert that a pointer is NULL
+ *
+ * @expr: pointer
+ */
#define ut_assertnull(expr) ({ \
const void *_val = (expr); \
int __ret = 0; \
@@ -293,7 +348,11 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that a pointer is not NULL */
+/**
+ * ut_assertnonnull() - Assert that a pointer is not NULL
+ *
+ * @expr: pointer
+ */
#define ut_assertnonnull(expr) ({ \
const void *_val = (expr); \
int __ret = 0; \
@@ -307,7 +366,11 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that a pointer is not an error pointer */
+/**
+ * ut_assertok_ptr() - Assert that a pointer is not an error pointer
+ *
+ * @expr: pointer
+ */
#define ut_assertok_ptr(expr) ({ \
const void *_val = (expr); \
int __ret = 0; \
@@ -322,10 +385,19 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that an operation succeeds (returns 0) */
+/**
+ * ut_assertok() - Assert that an operation succeeds (returns 0)
+ *
+ * @cond: expression
+ */
#define ut_assertok(cond) ut_asserteq(0, cond)
-/* Assert that the next console output line matches */
+/**
+ * ut_assert_nextline() - Assert that the next console output line matches
+ *
+ * @fmt: format string
+ * @args: print arguments
+ */
#define ut_assert_nextline(fmt, args...) ({ \
int __ret = 0; \
\
@@ -338,7 +410,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that the next console output line matches up to the length */
+/**
+ * ut_assert_nextlinen() - Assert that the next console output line matches
+ * up to the length of the expected string.
+ *
+ * @fmt: format string
+ * @args: print arguments
+ */
#define ut_assert_nextlinen(fmt, args...) ({ \
int __ret = 0; \
\
@@ -351,7 +429,10 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that there is a 'next' console output line, and skip it */
+/**
+ * ut_assert_skipline() - Assert that there is a 'next' console output line,
+ * and skip it
+ */
#define ut_assert_skipline() ({ \
int __ret = 0; \
\
@@ -363,7 +444,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that a following console output line matches */
+/**
+ * ut_assert_skip_to_line() - Assert that a following console output line
+ * matches
+ *
+ * @fmt: format string
+ * @args: print arguments
+ */
#define ut_assert_skip_to_line(fmt, args...) ({ \
int __ret = 0; \
\
@@ -376,7 +463,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that a following console output line matches */
+/**
+ * ut_assert_skip_to_linen() - Assert that a following console output line
+ * matches up to the length of the expected string
+ *
+ * @fmt: format string
+ * @args: print arguments
+ */
#define ut_assert_skip_to_linen(fmt, args...) ({ \
int __ret = 0; \
\
@@ -389,7 +482,9 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that there is no more console output */
+/**
+ * ut_assert_console_end() - Assert that there is no more console output
+ */
#define ut_assert_console_end() ({ \
int __ret = 0; \
\
@@ -402,7 +497,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that the next lines are print_buffer() dump at an address */
+/**
+ * ut_assert_nextlines_are_dump - Assert that the next lines are print_buffer()
+ * dump at an address
+ *
+ * @total_bytes: Size of the expected dump in bytes
+ */
#define ut_assert_nextlines_are_dump(total_bytes) ({ \
int __ret = 0; \
\
@@ -416,7 +516,10 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
-/* Assert that the next console output line is empty */
+/**
+ * ut_assert_nextline_empty() - Assert that the next console output line is
+ * empty
+ */
#define ut_assert_nextline_empty() \
ut_assert_nextline("%s", "")
@@ -451,6 +554,8 @@ void ut_silence_console(struct unit_test_state *uts);
*
* This restarts console output again and turns off console recording. This
* happens on all boards, including sandbox.
+ *
+ * @uts: Test state
*/
void ut_unsilence_console(struct unit_test_state *uts);
--
2.51.0
More information about the U-Boot
mailing list