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

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

[Petr Vorel]

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>
---
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

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

[Li Wang via ltp]

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

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

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

[Petr Vorel]

Hi all,

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

@Li FYI if you put space before RBT it's not taken.

I created a ticket for it:
https://github.com/getpatchwork/patchwork/issues/645

...
> >  #ifdef TST_TEST_H__
> > +/**
> > + * tst_cmd_fds() - :man2:`vfork` + :man2:`execvp` specified program.

execvp is man3, I fixed it before merge.

Thanks for your review, merged!

Kind regards,
Petr

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

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

[Andrea Cervesato via ltp]

Hi,

Feel free to merge.

Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com>


-- 
Andrea Cervesato
SUSE QE Automation Engineer Linux
andrea.cervesato@suse.com


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