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

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

[Petr Vorel]

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.
+ *
+ * @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.
+ *
+ * @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);
 
-- 
2.43.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Andrea Cervesato via ltp]

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


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [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

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Petr Vorel]

Hi Li,

> > >   /**
> > > - * 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!

Thanks a lot for catching these (on 2 places, diff below). I'm travelling for a
few days, thus I'll leave it for others to see before merge.

Kind regards,
Petr

+++ include/libswap.h
@@ -30,7 +30,7 @@ int make_swapfile(const char *file, const int lineno,
 /**
  * MAKE_SMALL_SWAPFILE - create small swap file.
  *
- * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
+ * Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
  *
  * @swapfile: swap filename.
  */
@@ -41,7 +41,7 @@ int make_swapfile(const char *file, const int lineno,
 /**
  * SAFE_MAKE_SMALL_SWAPFILE - create small swap file (safe version).
  *
- * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
+ * Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
  * Includes safety checks to handle potential errors.
  *
  * @swapfile: swap filename.

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Petr Vorel]

Hi Andrea,

> > - * 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, my typo, 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
Yeah.

BTW we need to have CI job which tries to generate our docs with sphinx.

Kind regards,
Petr

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Andrea Cervesato via ltp]

Hi!

LGTM with fix

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

On 4/26/24 20:25, Petr Vorel wrote:
> Hi Li,
>
>>>>    /**
>>>> - * 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!
> Thanks a lot for catching these (on 2 places, diff below). I'm travelling for a
> few days, thus I'll leave it for others to see before merge.
>
> Kind regards,
> Petr
>
> +++ include/libswap.h
> @@ -30,7 +30,7 @@ int make_swapfile(const char *file, const int lineno,
>   /**
>    * MAKE_SMALL_SWAPFILE - create small swap file.
>    *
> - * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
> + * Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
>    *
>    * @swapfile: swap filename.
>    */
> @@ -41,7 +41,7 @@ int make_swapfile(const char *file, const int lineno,
>   /**
>    * SAFE_MAKE_SMALL_SWAPFILE - create small swap file (safe version).
>    *
> - * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
> + * Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB.
>    * Includes safety checks to handle potential errors.
>    *
>    * @swapfile: swap filename.



-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

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

[Petr Vorel]

Hi Andrea, Li,

> Hi!

> LGTM with fix

Thanks for your review, merged!

Kind regards,
Petr

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp