[LTP] [PATCH v2 1/5] tst_kernel.h: Convert docs to sphinx

[Andrea Cervesato]

Hi!

LGTM

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

On 5/21/24 12:53, Petr Vorel wrote:
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> The same as in v1
>
>   doc/developers/api_c_tests.rst |  2 ++
>   include/tst_kernel.h           | 43 +++++++++++++++++++++-------------
>   2 files changed, 29 insertions(+), 16 deletions(-)
>
> diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
> index ec53ab33c..2a9f3e7b9 100644
> --- a/doc/developers/api_c_tests.rst
> +++ b/doc/developers/api_c_tests.rst
> @@ -1,4 +1,5 @@
>   .. SPDX-License-Identifier: GPL-2.0-or-later
> +.. Copyright (c) Linux Test Project, 2024
>   
>   .. Include headers in this file with:
>   .. .. kernel-doc:: ../../include/tst_test.h
> @@ -11,6 +12,7 @@ Core LTP API
>   
>   .. kernel-doc:: ../../include/tst_res_flags.h
>   .. kernel-doc:: ../../include/tst_test.h
> +.. kernel-doc:: ../../include/tst_kernel.h
>   
>   Option parsing
>   --------------
> diff --git a/include/tst_kernel.h b/include/tst_kernel.h
> index 89de79928..e0ce7ce46 100644
> --- a/include/tst_kernel.h
> +++ b/include/tst_kernel.h
> @@ -5,33 +5,44 @@
>   #ifndef TST_KERNEL_H__
>   #define TST_KERNEL_H__
>   
> -/*
> - * Returns 32 if we are running on 32bit kernel and 64 if on 64bit kernel.
> +/**
> + * tst_kernel_bits() - Detect if running on 32bit or 64bit kernel.
> + *
> + * Return: 32 if the test process is running on 32bit kernel and 64 if on 64bit
> + * kernel.
>    */
>   int tst_kernel_bits(void);
>   
> -/*
> - * Returns non-zero if the test process is running in compat mode.
> +/**
> + * tst_is_compat_mode() - Detect if running in compat mode.
> + *
> + * Detect if the test is 32bit binary executed on a 64bit kernel,
> + * i.e. we are testing the kernel compat layer.
> + *
> + * Return: non-zero if the test process is running in compat mode.
>    */
>   int tst_is_compat_mode(void);
>   
> -/*
> - * Checks if the kernel module is built-in.
> +/**
> + * tst_check_builtin_driver() - Check if the kernel module is built-in.
>    *
> - * @param driver The name of the driver.
> - * @return Returns 0 if builtin driver
> - * -1 when driver is missing or config file not available.
> - * On Android *always* 0 (always expect the driver is available).
> + * @driver: the name of the driver.
> + *
> + * Return: 0 if builtin driver or -1 when driver is missing or config file not
> + * available. On Android *always* 0 (always expect the driver is available).
>    */
>   int tst_check_builtin_driver(const char *driver);
>   
> -/*
> - * Checks support for the kernel module (both built-in and loadable).
> +/**
> + * tst_check_driver() - Check support for the kernel module.
> + *
> + * Check support for the kernel module (both built-in and loadable).
> + *
> + * @driver: the name of the driver.
>    *
> - * @param driver The name of the driver.
> - * @return Returns 0 if the kernel has the driver,
> - * -1 when driver is missing or config file not available.
> - * On Android *always* 0 (always expect the driver is available).
> + * Return: 0 if the kernel has the driver, -1 when driver is missing or config
> + * file not available. On Android *always* 0 (always expect the driver is
> + * available).
>    */
>   int tst_check_driver(const char *driver);
>   

Andrea