[LTP] [PATCH 1/1] include: Restore kerneldoc for tst_cmd() and TST_CAP()

[LTP] [PATCH 1/1] include: Restore kerneldoc for tst_cmd() and TST_CAP()

[Petr Vorel]

This partly reverts ef4c5c61f8. We want to have the doc included,
because both the structure and the function is documented properly
there. We need to use c:func: and c:type: in references, but that's ok.

Fixes: ef4c5c61f8 ("include: Fix kernel-doc warnings in header comments")
Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
Hi Andrea, Cyril,

we agreed to have this functionality [1] but in the end you merged it
with it. Hence I'd like to revert back this part.

Best option would be, of course to rename the tst_cap struct.

tst_cmd() is indeed defined 2x in include/tst_cmd.h, due different args.
That could be solvable by moving legacy API definition into tso_cmd.h
which would import tst_cmd.h and itself be included only by test.h.
A bit impractical but should work. Other option is to find a way how to
tell sphinx to ignore the other definition.

Kind regards,
Petr

[1] https://lore.kernel.org/ltp/ah6csOP7O9R0L2hO@yuki.lan/

 include/tst_capability.h | 2 +-
 include/tst_cmd.h        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/tst_capability.h b/include/tst_capability.h
index c38dcf3534..2e9a4dc55e 100644
--- a/include/tst_capability.h
+++ b/include/tst_capability.h
@@ -69,7 +69,7 @@ struct tst_cap {
 	char *name;
 };
 
-/*
+/**
  * TST_CAP() - Create a struct tst_cap entry.
  *
  * @action: What should we do, i.e. drop or add capability.
diff --git a/include/tst_cmd.h b/include/tst_cmd.h
index 4829d0aed8..36d8751a2d 100644
--- a/include/tst_cmd.h
+++ b/include/tst_cmd.h
@@ -19,7 +19,7 @@ enum tst_cmd_flags {
 	TST_CMD_TCONF_ON_MISSING = 2,
 };
 
-/*
+/**
  * struct tst_cmd - Provides details about a command struct needed by LTP test.
  * @cmd: The name of the command.
  * @optional: A flag indicating if the command is optional.
-- 
2.53.0


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

Re: [LTP] include: Restore kerneldoc for tst_cmd() and TST_CAP()

[linuxtestproject.agent]

Hi Petr,

On Fri Sep 11 21:51:33 2026 +0200, Petr Vorel wrote:
> include: Restore kerneldoc for tst_cmd() and TST_CAP()

The subject mentions tst_cmd(), but the patch restores kerneldoc for
struct tst_cmd (the function tst_cmd() was never modified). Use
"struct tst_cmd" instead of "tst_cmd()".

> This partly reverts ef4c5c61f8. We want to have the doc included,
> because both the structure and the function is documented properly
> there. We need to use c:func: and c:type: in references, but that's ok.

ef4c5c61f8 downgraded these comments because kernel-doc and Sphinx emit
name collisions and duplicate target warnings between struct tst_cmd and
tst_cmd(), as well as struct tst_cap and TST_CAP(), when api_c_tests.rst
extracts all comments from these headers. Restoring both blocks without
resolving the target collision reintroduces documentation build warnings.
Also, tst_capability.h defines a struct and a macro, not a function.

> diff --git a/include/tst_capability.h b/include/tst_capability.h
> index c38dcf353..2e9a4dc55 100644
> --- a/include/tst_capability.h
> +++ b/include/tst_capability.h
> @@ -69,7 +69,7 @@ struct tst_cap {
>  	char *name;
>  };
>  
> -/*
> +/**
>   * TST_CAP() - Create a struct tst_cap entry.
>   *
>   * @action: What should we do, i.e. drop or add capability.

For macros, the kernel-doc summary line must use "name" without
parentheses. Change "TST_CAP()" to "TST_CAP".

> diff --git a/include/tst_cmd.h b/include/tst_cmd.h
> index 4829d0aed..36d8751a2 100644
> --- a/include/tst_cmd.h
> +++ b/include/tst_cmd.h
> @@ -19,7 +19,7 @@ enum tst_cmd_flags {
>  	TST_CMD_TCONF_ON_MISSING = 2,
>  };
>  
> -/*
> +/**
>   * struct tst_cmd - Provides details about a command struct needed by LTP test.
>   * @cmd: The name of the command.
>   * @optional: A flag indicating if the command is optional.

Restoring the kernel-doc comment here causes a duplicate target collision
with the existing tst_cmd() function documentation in api_c_tests.rst.

Verdict - Needs revision

Pre-existing issues:
- include/tst_capability.h: tst_capget() and tst_capset() kernel-doc blocks
  use lowercase "return:" instead of "Return:".

---
Note:

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