doc: libltpswap: Add kerneldoc

Link: https://lore.kernel.org/ltp/[email protected]/
Reviewed-by: Li Wang <[email protected]>
Reviewed-by: Andrea Cervesato <[email protected]>
Signed-off-by: Petr Vorel <[email protected]>

Author: pevik

doc/developers/api_c_tests.rst

@@ -31,3 +31,7 @@ Capabilities
 ------------
 
 .. kernel-doc:: ../../include/tst_capability.h
+
+libltpswap
+----------
+.. kernel-doc:: ../../include/libswap.h

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 <[email protected]>
  */
 
 /*
- * 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 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 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);