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

[linuxtestproject.agent@gmail.com]

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