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

[Petr Vorel]

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
Changes in v2:
* Hopefully address all Cyril's comments in v1. @Cyril if not, please
  fix it and merge under your SOB, it's mostly your text anyway.
* Describe also tst_remaining_runtime() (that changes
  tst_remaining_runtime() mentioned in struct tst_test members clickable)

Link to v1:
https://lore.kernel.org/ltp/20260421143200.GA611911@pevik/T/#t
https://patchwork.ozlabs.org/project/ltp/patch/20260325120629.113245-1-pvorel@suse.cz/

 include/tst_test.h | 89 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 72 insertions(+), 17 deletions(-)

diff --git a/include/tst_test.h b/include/tst_test.h
index f12c59f393..c547037ccd 100644
--- a/include/tst_test.h
+++ b/include/tst_test.h
@@ -696,35 +696,87 @@ void tst_reinit(void);
  */
 int tst_run_script(const char *script_name, char *const params[]);
 
-/*
- * Sets entire timeout in seconds.
+/**
+ * tst_set_timeout() - Sets the timeout part of the overall timeout.
+ *
+ * Allows to set the overall timeout dynamically during the test setup phase.
+ *
+ * This is used only for rare cases that the test does something that runs for a
+ * long time and cannot be easily interrupted (otherwise it would set
+ * :c:type:`.runtime <tst_test>` and exit when runtime was exhausted).
+ *
+ * @timeout: A timeout in seconds, defines the total time allowed for a single
+ * test iteration, including the setup, runtime, and teardown phases.
  */
 void tst_set_timeout(int timeout);
 
+/**
+ * tst_multiply_timeout() - Uses heuristics to multiply a time interval based on
+ * expected CPU slowdowns.
+ *
+ * If a machine is expected to be running slow for some reason a user can export
+ * :doc:`LTP_TIMEOUT_MUL <../users/setup_tests>` variable that is used by this
+ * call to multiply the interval.
+ *
+ * Various kernel configuration (debugging) options that slow down the machine
+ * are also attempted to be detected and are taken into account.
+ *
+ * @timeout: A timeout.
+ *
+ * Return: timeout multiplied with LTP_TIMEOUT_MUL environment variable.
+ */
 unsigned int tst_multiply_timeout(unsigned int timeout);
 
-/*
- * Returns remaining test runtime. Test that runs for more than a few seconds
- * should check if they should exit by calling this function regularly.
+/**
+ * tst_remaining_runtime() - Returns the remaining test runtime.
  *
  * The function returns remaining runtime in seconds. If runtime was used up
  * zero is returned.
+ *
+ * Test that runs for more than a few seconds should check if they should exit
+ * by calling this function regularly.
+ *
+ * Return: the remaining test runtime in seconds.
  */
 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.
+ *
+ * A test that sets a runtime must monitor the remaining time with
+ * tst_remaining_runtime() in the main loop.
+ *
+ * @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);
 
@@ -740,13 +792,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