Re: [LTP] doc: Add missing API references to api_c_tests.rst

[linuxtestproject.agent@gmail.com]

Hi Andrea,

On Thu, 04 Jun 2026 10:45:08 +0200, Andrea Cervesato wrote:
> doc: Add missing API references to api_c_tests.rst

--- [PATCH 1/3] ---

> +/**
> + * struct tst_device - Block device used by a test.
>   ...
>  */
>  struct tst_device {
>  ...
>  /*
> - * Automatically initialized if test.needs_device is set.
> + * tst_device - Pointer to the test block device.
> + *
> + * Automatically initialized if tst_test.needs_device is set.
>   */
>  extern struct tst_device *tst_device;

The tst_device variable comment body was updated to kernel-doc format
(starting with "tst_device - ..."), but the opening delimiter was left
as "/*" instead of "/**". kernel-doc ignores "/*" blocks, so this
variable will not appear in the generated documentation. Every other
function in this file was converted with "/**" in the same commit.

> +Filesystems
> +-----------
> +.. kernel-doc:: ../../include/tst_fs.h
>
> ...
>
> +Memory
> +------
> +.. kernel-doc:: ../../include/tst_memutils.h

tst_fs.h and tst_memutils.h were not converted to kernel-doc format in
this commit. tst_fs.h has a single "/**" comment for tst_path_exists(),
and tst_memutils.h has one for tst_mapping_in_range(). The primary APIs
in each header -- tst_fs_type(), tst_fs_has_free(), tst_pollute_memory(),
tst_available_mem(), tst_available_swap() -- all use plain "/*" comments
and will not be extracted.

The resulting "Filesystems" and "Memory" sections under LTP C API will
each document only one function, neither of which is the main API the
section title implies.

Was the intent to convert these headers in a follow-up, or should they
be converted here to avoid publishing sparse documentation sections?

Verdict: Needs revision

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