[LTP] [PATCH 4/9] include: Document assertion API macros

[Andrea Cervesato]

From: Andrea Cervesato <andrea.cervesato@suse.com>

Add kernel-doc comments for the public assertion macros in
include/tst_assert.h to populate the Assertion section in the generated
C API documentation.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
 include/tst_assert.h | 85 ++++++++++++++++++++++++++++++++++------------------
 1 file changed, 56 insertions(+), 29 deletions(-)

diff --git a/include/tst_assert.h b/include/tst_assert.h
index dcb62dfea..e952f612f 100644
--- a/include/tst_assert.h
+++ b/include/tst_assert.h
@@ -7,58 +7,85 @@
 #ifndef TST_ASSERT_H__
 #define TST_ASSERT_H__
 
+/**
+ * TST_ASSERT_INT() - Asserts that integer value in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @val: Expected integer value.
+ *
+ * Reads an integer from the file at path and compares it to val.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
 #define TST_ASSERT_INT(path, val) \
 	tst_assert_int(__FILE__, __LINE__, path, val)
 
-/*
- * Asserts that integer value stored in file pointed by path equals to the
- * value passed to this function. This is mostly useful for asserting correct
- * values in sysfs, procfs, etc.
- */
 void tst_assert_int(const char *file, const int lineno,
 		    const char *path, int val);
 
+/**
+ * TST_ASSERT_FILE_INT() - Asserts that integer value for field in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @prefix: Field name or line prefix preceding the integer value.
+ * @val: Expected integer value.
+ *
+ * Scans lines in path for prefix followed by an integer.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
 #define TST_ASSERT_FILE_INT(path, prefix, val) \
 	tst_assert_file_int(__FILE__, __LINE__, path, prefix, val)
 
-/*
- * Same as tst_assert_int() but for unsigned long.
- */
-void tst_assert_ulong(const char *file, const int lineno,
-                      const char *path, unsigned long val);
+void tst_assert_file_int(const char *file, const int lineno,
+			 const char *path, const char *prefix, int val);
 
+/**
+ * TST_ASSERT_ULONG() - Asserts that unsigned long value in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @val: Expected unsigned long value.
+ *
+ * Reads an unsigned long from the file at path and compares it to val.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
 #define TST_ASSERT_ULONG(path, val) \
 	tst_assert_ulong(__FILE__, __LINE__, path, val)
 
-/*
- * Asserts that integer value stored in the prefix field of file pointed by path
- * equals to the value passed to this function. This is mostly useful for
- * asserting correct field values in sysfs, procfs, etc.
- */
-
-void tst_assert_file_int(const char *file, const int lineno,
-			 const char *path, const char *prefix, int val);
-
+void tst_assert_ulong(const char *file, const int lineno,
+		      const char *path, unsigned long val);
 
+/**
+ * TST_ASSERT_STR() - Asserts that string value in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @val: Expected string value.
+ *
+ * Reads a whitespace-delimited string from path and compares it to val.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
 #define TST_ASSERT_STR(path, val) \
 	tst_assert_str(__FILE__, __LINE__, path, val)
 
-/*
- * Asserts that a string value stored in file pointed by path equals to the
- * value passed to this function. This is mostly useful for asserting correct
- * values in sysfs, procfs, etc.
- */
 void tst_assert_str(const char *file, const int lineno,
 		    const char *path, const char *val);
 
+/**
+ * TST_ASSERT_FILE_STR() - Asserts that string value for field in file equals val.
+ *
+ * @path: Path to the file to check.
+ * @prefix: Field name or prefix preceding the string value.
+ * @val: Expected string value.
+ *
+ * Scans lines in path for prefix followed by ": " and a string value.
+ * Reports :c:enum:`TPASS <tst_res_flags>` on match, or
+ * :c:enum:`TFAIL <tst_res_flags>` on mismatch.
+ */
 #define TST_ASSERT_FILE_STR(path, prefix, val) \
 	tst_assert_file_str(__FILE__, __LINE__, path, prefix, val)
 
-/*
- * Asserts that a string value stored in the prefix field of file pointed by path
- * equals to the value passed to this function. This is mostly useful for
- * asserting correct field values in sysfs, procfs, etc.
- */
 void tst_assert_file_str(const char *file, const int lineno,
 			 const char *path, const char *prefix, const char *val);
 

-- 
2.51.0