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

[Li Wang]

On Fri, Apr 26, 2024 at 3:44 PM Andrea Cervesato via ltp <ltp@lists.linux.it>
wrote:

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

+1 I guess that might be one typo.

Otherwise looks good to me, thanks!



> > + *
> > + * @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
>
>
> --
> Mailing list info: https://lists.linux.it/listinfo/ltp
>
>

-- 
Regards,
Li Wang