Re: [LTP] [PATCH 1/1] doc: libltpswap: Add kerneldoc

Andrea Cervesato via ltp
2024-04-26T07:44:03Z

Hi!

On 4/26/24 06:28, Petr Vorel wrote:
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
> doc/developers/api_c_tests.rst | 4 +++
> include/libswap.h | 61 +++++++++++++++++++++++++++-------
> 2 files changed, 53 insertions(+), 12 deletions(-)
>
> diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
> index 2c0c8419d..ec53ab33c 100644
> --- a/doc/developers/api_c_tests.rst
> +++ b/doc/developers/api_c_tests.rst
> @@ -31,3 +31,7 @@ Capabilities
> ------------
>
> .. kernel-doc:: ../../include/tst_capability.h
> +
> +libltpswap
> +----------
> +.. kernel-doc:: ../../include/libswap.h
> diff --git a/include/libswap.h b/include/libswap.h
> index f757073cc..681849166 100644
> --- a/include/libswap.h
> +++ b/include/libswap.h
> @@ -1,11 +1,12 @@
> // SPDX-License-Identifier: GPL-2.0-or-later
> /*
> * Copyright (c) 2013 Oracle and/or its affiliates. All Rights Reserved.
> + * Copyright (c) Linux Test Project, 2021-2024
> * Author: Stanislav Kholmanskikh <stanislav.kholmanskikh@oracle.com>
> */
>
> /*
> - * Contains common content for all swapon/swapoff tests
> + * Contains common content for all swapon/swapoff tests.
> */
>
> #ifndef __LIBSWAP_H__
> @@ -27,60 +28,96 @@ int make_swapfile(const char *file, const int lineno,
> #define MINIMAL_SWAP_SIZE_MB 1
>
> /**
> - * Macro to create minimal swapfile.
> + * MAKE_SMALL_SWAPFILE - create small swap file.
> + *
> + * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
"small small" sounds weird. Maybe "really small"
> + *
> + * @swapfile: swap filename.
> */
> #define MAKE_SMALL_SWAPFILE(swapfile) \
> make_swapfile(__FILE__, __LINE__, swapfile, MINIMAL_SWAP_SIZE_MB, 0, \
> SWAPFILE_BY_SIZE)
>
> /**
> - * Macro to create minimal swapfile.
> + * SAFE_MAKE_SMALL_SWAPFILE - create small swap file (safe version).
> + *
> + * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
> * Includes safety checks to handle potential errors.
Same here
> + *
> + * @swapfile: swap filename.
> */
> #define SAFE_MAKE_SMALL_SWAPFILE(swapfile) \
> make_swapfile(__FILE__, __LINE__, swapfile, MINIMAL_SWAP_SIZE_MB, 1, \
> SWAPFILE_BY_SIZE)
>
> /**
> - * Macro to create swapfile size in megabytes (MB).
> + * MAKE_SWAPFILE_SIZE - create swap file (MB).
> + *
> + * Macro to create swap file, size specified in megabytes (MB).
> + *
> + * @swapfile: swap filename.
> + * @size: swap size in MB.
> */
> #define MAKE_SWAPFILE_SIZE(swapfile, size) \
> make_swapfile(__FILE__, __LINE__, swapfile, size, 0, SWAPFILE_BY_SIZE)
>
> /**
> - * Macro to create swapfile size in block numbers.
> + * MAKE_SWAPFILE_BLKS - create swap file (blocks).
> + *
> + * Macro to create swap file, size specified in block numbers.
> + *
> + * @swapfile: swap filename.
> + * @blocks: number of blocks.
> */
> #define MAKE_SWAPFILE_BLKS(swapfile, blocks) \
> make_swapfile(__FILE__, __LINE__, swapfile, blocks, 0, SWAPFILE_BY_BLKS)
>
> /**
> - * Macro to safely create swapfile size in megabytes (MB).
> + * SAFE_MAKE_SWAPFILE_SIZE - create swap file (MB, safe version).
> + *
> + * Macro to safely create swap file, size specified in megabytes (MB).
> * Includes safety checks to handle potential errors.
> + *
> + * @swapfile: swap file name.
> + * @size: swap size in MB.
> */
> #define SAFE_MAKE_SWAPFILE_SIZE(swapfile, size) \
> make_swapfile(__FILE__, __LINE__, swapfile, size, 1, SWAPFILE_BY_SIZE)
>
> /**
> - * Macro to safely create swapfile size in block numbers.
> + * SAFE_MAKE_SWAPFILE_BLKS - create swap file (block, safe version)
> + *
> + * Macro to safely create swap file, size specified in block numbers.
> * Includes safety checks to handle potential errors.
> + *
> + * @swapfile: swap file name.
> + * @blocks: number of blocks.
> */
> #define SAFE_MAKE_SWAPFILE_BLKS(swapfile, blocks) \
> make_swapfile(__FILE__, __LINE__, swapfile, blocks, 1, SWAPFILE_BY_BLKS)
>
> -/*
> +/**
> + * is_swap_supported() - Check swapon/swapoff support.
> + *
> * Check swapon/swapoff support status of filesystems or files
> * we are testing on.
> + *
> + * @filename: swap file name.
> + * Return: true if swap is supported, false if not.
> */
> bool is_swap_supported(const char *filename);
>
> -/*
> - * Get kernel constant MAX_SWAPFILES value.
> +/**
> + * tst_max_swapfiles() - Get kernel constant MAX_SWAPFILES value.
> *
> + * Return: MAX_SWAPFILES value.
> */
> int tst_max_swapfiles(void);
>
> -/*
> - * Get the used swapfiles number.
> +/**
> + * tst_count_swaps() - Get the used swapfiles number.
> + *
> + * Return: used swapfiles number.
> */
> int tst_count_swaps(void);
>

Andrea