[LTP] [PATCH 1/1] tst_test.h: Convert rest of doc to kerneldoc

[Petr Vorel]

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
 include/tst_test.h | 66 ++++++++++++++++++++++++++++++++++++----------
 1 file changed, 52 insertions(+), 14 deletions(-)

diff --git a/include/tst_test.h b/include/tst_test.h
index ddfe9d4d6c..fa336207e9 100644
--- a/include/tst_test.h
+++ b/include/tst_test.h
@@ -694,11 +694,25 @@ void tst_reinit(void);
  */
 int tst_run_script(const char *script_name, char *const params[]);
 
-/*
- * Sets entire timeout in seconds.
+/**
+ * tst_set_timeout() - Sets entire timeout in seconds.
+ *
+ * Allows to sett the overall timeout dynamically during the test setup phase.
+ * The timeout is specified in seconds and defines the total time allowed for a
+ * single test iteration, including the setup, runtime, and teardown phases.
+ *
+ * @timeout: A timeout in seconds.
  */
 void tst_set_timeout(int timeout);
 
+/**
+ * tst_multiply_timeout() - Multiply the timeout with LTP_TIMEOUT_MUL
+ * environment variable.
+ *
+ * @timeout: A timeout in seconds.
+ *
+ * Return: timeout multiplied with LTP_TIMEOUT_MUL environment variable.
+ */
 unsigned int tst_multiply_timeout(unsigned int timeout);
 
 /*
@@ -710,19 +724,40 @@ unsigned int tst_multiply_timeout(unsigned int timeout);
  */
 unsigned int tst_remaining_runtime(void);
 
-/*
- * Sets maximal test runtime in seconds.
+/**
+ * tst_set_runtime() - Sets maximal test runtime in seconds.
+ *
+ * Allows for setting the runtime per test iteration dynamically during the test
+ * setup phase.  The runtime is specified in seconds and defines how long the
+ * test is allowed to execute its main workload, excluding the setup and
+ * teardown phases.
+ *
+ * This function is useful for tests where the duration of the main workload can
+ * be controlled or needs to be adjusted dynamically. For example, tests that
+ * run in a loop until the runtime expires can use this function to define how
+ * long they should execute.
+ *
+ * @runtime: A timeout in seconds.
  */
 void tst_set_runtime(int runtime);
 
-/*
- * Create and open a random file inside the given dir path.
- * It unlinks the file after opening and return file descriptor.
+/**
+ * tst_creat_unlinked() - Create and open a random file inside the given
+ * directory path, unlinks the file after opening and return file descriptor.
+ *
+ * @path: Path to the directory.
+ * @flags: :manpage:`open(2)` flags.
+ * @mode: :manpage:`open(2)` mode.
+ *
+ * Return: the file descriptor.
  */
 int tst_creat_unlinked(const char *path, int flags, mode_t mode);
 
-/*
- * Returns path to the test temporary directory root (TMPDIR).
+/**
+ * tst_get_tmpdir_root() - Returns path to the test temporary directory root
+ * (TMPDIR environment variable).
+ *
+ * Return: the path to TMPDIR.
  */
 const char *tst_get_tmpdir_root(void);
 
@@ -738,13 +773,16 @@ const char *tst_get_tmpdir_root(void);
  */
 bool tst_cmd_present(const char *cmd);
 
-/*
- * Validates exit status of child processes
- */
 int tst_validate_children_(const char *file, const int lineno,
 	unsigned int count);
-#define tst_validate_children(child_count) \
-	tst_validate_children_(__FILE__, __LINE__, (child_count))
+
+/**
+ * tst_validate_children() - Validates exit status of the child processes.
+ *
+ * @count: Number of the child processes.
+ */
+#define tst_validate_children(count) \
+	tst_validate_children_(__FILE__, __LINE__, (count))
 
 #ifndef TST_NO_DEFAULT_MAIN
 
-- 
2.53.0