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

[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


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] tst_test.h: Convert rest of doc to kerneldoc

[linuxtestproject.agent]

Hi Petr,

On Tue, 21 Apr 2026 16:41:26 +0200, Petr Vorel wrote:
> tst_test.h: Convert rest of doc to kerneldoc

The commit message body is missing. Please add at least one sentence
explaining why this conversion is being done (e.g. to enable Sphinx
kerneldoc extraction).

> +/**
> + * tst_set_timeout() - Sets the timeout part of the overall timeout.
> + *
[...]
> + * @timeout: A timeout in seconds, defines the total time allowed for a single
> + * test iteration, including the setup, runtime, and teardown phases.

The @timeout description is inaccurate. The implementation computes:

  overall_time = tst_multiply_timeout(DEFAULT_TIMEOUT + timeout) + context->runtime

So @timeout is not the total time per iteration — it is added to
DEFAULT_TIMEOUT before multiplication, and the runtime portion is added
separately. The description should reflect what the argument actually
controls, not the resulting overall_time.

---
Note:

Our agent completed the review of the patch.

The agent can sometimes produce false positives although often its
findings are genuine. If you find issues with the review, please
comment this email or ignore the suggestions.

Regards,
LTP AI Reviewer

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp