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

[Cyril Hrubis <chrubis@suse.cz>]

Hi!
> +/**
> + * tst_set_timeout() - Sets entire timeout in seconds.
> + *
> + * Allows to sett the overall timeout dynamically during the test setup phase.
                 ^
		 set
> + * The timeout is specified in seconds and defines the total time allowed for a
> + * single test iteration, including the setup, runtime, and teardown phases.

Looking at the code this call increases the timeout part of the overall
timeout. 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 runtime and exit when runtime was exhausted). The description
should explain that instead.

> + * @timeout: A timeout in seconds.
>   */
>  void tst_set_timeout(int timeout);
>  
> +/**
> + * tst_multiply_timeout() - Multiply the timeout with LTP_TIMEOUT_MUL
> + * environment variable.

This is again more complex. We use the timeout multiplier but also
look at the kconfig.

It should be something as:

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 LTP_TIMEOUT_MUL variable that is used by this call to multiply
the interval. We also attempt to detect various kernel config
(debugging) options that slown down the machine and take them into an
account.

> + * @timeout: A timeout in seconds.

Technically the call just multiplies a number and works for any time
unit. If you pass in minutes, you get multiplied minutes. If you pass in
weeks, you get weeks on output...

> + * 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.

Maybe add:

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);
>  
> @@ -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
> 

-- 
Cyril Hrubis
chrubis@suse.cz

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