[LTP] [PATCH 1/2] doc: Convert tst_kvercmp.h to RST

[Petr Vorel]

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
Hi all,

Could you please check my English.
@Cyril you're the author of the functions, please check my description.

Kind regards,
Petr

 doc/developers/api_c_tests.rst |  1 +
 include/tst_kvercmp.h          | 78 +++++++++++++++++++++++++++++-----
 2 files changed, 69 insertions(+), 10 deletions(-)

diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
index ad384a1bbd..5ab945fe51 100644
--- a/doc/developers/api_c_tests.rst
+++ b/doc/developers/api_c_tests.rst
@@ -41,6 +41,7 @@ Guarded buffers
 Kernel
 ------
 .. kernel-doc:: ../../include/tst_kernel.h
+.. kernel-doc:: ../../include/tst_kvercmp.h
 
 NUMA
 ----
diff --git a/include/tst_kvercmp.h b/include/tst_kvercmp.h
index fbefa0f793..bfe943a304 100644
--- a/include/tst_kvercmp.h
+++ b/include/tst_kvercmp.h
@@ -6,39 +6,97 @@
 #ifndef TST_KVERCMP_H__
 #define TST_KVERCMP_H__
 
-/*
+/**
+ * tst_kvcmp() - Compare given kernel version with kernel in string.
+ *
+ * @cur_kver: Kernel version in string (struct utsname.release).
+ * @r1: Required major kernel version.
+ * @r2: Required minor kernel version.
+ * @r3: Required kernel patch level.
+ *
  * The same as tst_kvercmp() but running kernel version is passed as parameter
  * instead of utilizing uname().
+ *
+ * Return: Negative if older, 0 if the same and positive if newer.
  */
 int tst_kvcmp(const char *cur_kver, int r1, int r2, int r3);
 
-/*
- * Parsers string into three integer version.
+/**
+ * tst_parse_kver() - Parsers string into three integer version.
+ *
+ * @str_kver: Kernel version in string (struct utsname.release).
+ * @v1: Major kernel version.
+ * @v2: Minor kernel version.
+ * @v3: Kernel patch level.
+ *
+ * Return: 0 on success, 1 on error.
  */
 int tst_parse_kver(const char *str_kver, int *v1, int *v2, int *v3);
 
-/*
- * Returns distribution name parsed from kernel version string or NULL.
+/**
+ * tst_kvcmp_distname() - Get the distribution name from kernel version string.
+ *
+ * @cur_kver: Kernel version in string (struct utsname.release).
+ *
+ * Return: The distribution name parsed from kernel version string or NULL.
  */
 const char *tst_kvcmp_distname(const char *cur_kver);
 
-/*
- * Compares versions up to five version numbers long.
+/**
+ * tst_kvexcmp() - Compares versions up to five version numbers long.
+ * @tst_exv: The tested kernel version in string (struct utsname.release).
+ * @cur_kver: The current version in string (struct utsname.release).
+ *
+ * The return value is similar to the 'strcmp()' function, i.e. zero means
+ * equal, negative value means that the kernel is older than the expected value
+ * and positive means that it's newer.
+ *
+ * Return: negative if older, 0 if the same and positive if newer.
  */
 int tst_kvexcmp(const char *tst_exv, const char *cur_kver);
 
-/*
- * Compare given kernel version with currently running kernel.
+/**
+ * tst_kvercmp() - Compare given kernel version with the currently running kernel.
  *
- * Returns negative if older, 0 if the same and positive if newer.
+ * @r1: Required major kernel version.
+ * @r2: Required minor kernel version.
+ * @r3: Required kernel patch level.
+ *
+ * Parse the output from 'uname()' and compare it to the passed values.
+ *
+ * The return value is similar to the 'strcmp()' function, i.e. zero means
+ * equal, negative value means that the kernel is older than the expected value
+ * and positive means that it's newer.
+ *
+ * Return: negative if older, 0 if the same and positive if newer.
  */
 int tst_kvercmp(int r1, int r2, int r3);
 
+/**
+ * struct tst_kern_exv - describe vendor kernel.
+ *
+ * @dist_name: A distribution name, e.g. "SLES", "RHEL9", "UBUNTU"
+ * @extra_ver: A vendor kernel version to check, e.g. "5.14.0-441".
+ */
 struct tst_kern_exv {
 	char *dist_name;
 	char *extra_ver;
 };
 
+/**
+ * tst_kvercmp2() - Compare given *distro* kernel version with the currently running kernel.
+ *
+ * @r1: Major kernel version.
+ * @r2: Minor kernel version.
+ * @r3: Kernel patch level.
+ * @vers: struct tst_kern_exv.
+ *
+ * The return value is similar to the 'strcmp()' function, i.e. zero means
+ * equal, negative value means that the kernel is older than the expected value
+ * and positive means that it's newer.
+ *
+ * Return: negative if older, 0 if the same and positive if newer.
+ */
 int tst_kvercmp2(int r1, int r2, int r3, struct tst_kern_exv *vers);
 
 #endif	/* TST_KVERCMP_H__ */
-- 
2.51.0