[LTP] [PATCH] tst_cmd.h: Convert the rest of comments to kerneldoc

[Li Wang]

On Fri, Oct 10, 2025 at 7:30 PM Petr Vorel <pvorel@suse.cz> wrote:

> Move docs from the private function implementations (functions with
> trailing underscore) to functions used into functions used in the new
> API.
>
> This avoids to document private functions.
>
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
>

 Reviewed-by: Li Wang <liwang@redhat.com>

---
> FYI I dared to merge the obvious part of the conversion:
>
>
> https://github.com/linux-test-project/ltp/commit/58708049bb24000af947e00fa611501aa284999a
>
> Kind regards,
> Petr
>
>  include/tst_cmd.h | 52 +++++++++++++++++++++++------------------------
>  1 file changed, 26 insertions(+), 26 deletions(-)
>
> diff --git a/include/tst_cmd.h b/include/tst_cmd.h
> index cf63829550..8397510ed6 100644
> --- a/include/tst_cmd.h
> +++ b/include/tst_cmd.h
> @@ -19,38 +19,12 @@ enum tst_cmd_flags {
>         TST_CMD_TCONF_ON_MISSING = 2,
>  };
>
> -/*
> - * vfork() + execvp() specified program.
> - *
> - * @param argv A list of two (at least program name + NULL) or more
> pointers that
> - * represent the argument list to the new program. The array of pointers
> - * must be terminated by a NULL pointer.
> - * @param stdout_fd File descriptor where to redirect stdout. Set -1 if
> - * redirection is not needed.
> - * @param stderr_fd File descriptor where to redirect stderr. Set -1 if
> - * redirection is not needed.
> - * @param flags enum tst_cmd_flags.
> - * @return The exit status of the program.
> - */
>  int tst_cmd_fds_(void (cleanup_fn)(void),
>                         const char *const argv[],
>                         int stdout_fd,
>                         int stderr_fd,
>                         enum tst_cmd_flags flags);
>
> -/*
> - * Executes tst_cmd_fds() and redirects its output to a file.
> - *
> - * @param argv A list of two (at least program name + NULL) or more
> pointers that
> - * represent the argument list to the new program. The array of pointers
> - * must be terminated by a NULL pointer.
> - * @param stdout_path Path where to redirect stdout. Set NULL if
> redirection is
> - * not needed.
> - * @param stderr_path Path where to redirect stderr. Set NULL if
> redirection is
> - * not needed.
> - * @param flags enum tst_cmd_flags.
> - * @return The exit status of the program.
> - */
>  int tst_cmd_(void (cleanup_fn)(void),
>                 const char *const argv[],
>                 const char *stdout_path,
> @@ -58,6 +32,20 @@ int tst_cmd_(void (cleanup_fn)(void),
>                 enum tst_cmd_flags flags);
>
>  #ifdef TST_TEST_H__
> +/**
> + * tst_cmd_fds() - :man2:`vfork` + :man2:`execvp` specified program.
> + *
> + * @argv: A list of two (at least program name + NULL) or more pointers
> that
> + * represent the argument list to the new program. The array of pointers
> + * must be terminated by a NULL pointer.
> + * @stdout_fd: File descriptor where to redirect stdout. Set -1 if
> + * redirection is not needed.
> + * @stderr_fd: File descriptor where to redirect stderr. Set -1 if
> + * redirection is not needed.
> + * @flags: enum tst_cmd_flags.
> + *
> + * Return: The exit status of the program.
> + */
>  static inline int tst_cmd_fds(const char *const argv[],
>                                   int stdout_fd,
>                                   int stderr_fd,
> @@ -67,6 +55,18 @@ static inline int tst_cmd_fds(const char *const argv[],
>                                 stdout_fd, stderr_fd, flags);
>  }
>
> +/**
> + * tst_cmd() - Executes tst_cmd_fds() and redirects its output to a file.
> + *
> + * @argv: A list of two (at least program name + NULL) or more pointers
> that
> + * @stdout_path: Path where to redirect stdout. Set NULL if redirection is
> + * not needed.
> + * @stderr_path: Path where to redirect stderr. Set NULL if redirection is
> + * not needed.
> + * @flags: enum tst_cmd_flags.
> + *
> + * Return: The exit status of the program.
> + */
>  static inline int tst_cmd(const char *const argv[],
>                               const char *stdout_path,
>                               const char *stderr_path,
> --
> 2.51.0
>
>
> --
> Mailing list info: https://lists.linux.it/listinfo/ltp
>
>

-- 
Regards,
Li Wang