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

[Petr Vorel]

Co-developed-by: Cyril Hrubis <chrubis@suse.cz>
Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
Changes v1->v2 (mostly from Cyril):
* Rewrite tst_kvercmp2() description.
* Remove "Required" from params.
* Remove wrongly used "in".
* Improve wording in tst_parse_kver() and tst_kvercmp() first line
  description.
* Add note "Everything after first three version numbers ... ignored" to
  tst_kvcmp() and tst_parse_kver().
* Mention array in struct tst_kern_exv->vers.
* Use :man2: and :man3: links (me).
* Use links to structs (me).

Hopefully I addressed everything.

Link to v1:
https://patchwork.ozlabs.org/project/ltp/patch/20251014145020.178840-1-pvorel@suse.cz/
https://lore.kernel.org/ltp/20251014145020.178840-1-pvorel@suse.cz/

 doc/developers/api_c_tests.rst |  1 +
 include/tst_kvercmp.h          | 85 ++++++++++++++++++++++++++++++----
 2 files changed, 76 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..ab9779f281 100644
--- a/include/tst_kvercmp.h
+++ b/include/tst_kvercmp.h
@@ -6,39 +6,104 @@
 #ifndef TST_KVERCMP_H__
 #define TST_KVERCMP_H__
 
-/*
+/**
+ * tst_kvcmp() - Compare given kernel version with kernel in string.
+ *
+ * @cur_kver: Kernel version string (struct utsname.release).
+ * @r1: Major kernel version.
+ * @r2: Minor kernel version.
+ * @r3: Kernel patch level.
+ *
+ * Everything after first three version numbers till the end of the string is
+ * ignored.
+ *
  * 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() - Parses a version string into three integers.
+ *
+ * @str_kver: Kernel version string (struct utsname.release).
+ * @v1: Major kernel version.
+ * @v2: Minor kernel version.
+ * @v3: Kernel patch level.
+ *
+ * Everything after first three version numbers till the end of the string is
+ * ignored.
+ *
+ * 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 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 string (struct utsname.release).
+ * @cur_kver: The current version in string (struct utsname.release).
+ *
+ * The return value is similar to the :man3:`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 a kernel version against currently running kernel.
+ *
+ * @r1: Major kernel version.
+ * @r2: Minor kernel version.
+ * @r3: Kernel patch level.
+ *
+ * Parse the output from :man2:`uname` and compare it to the passed values.
+ * This is shortcut for calling tst_kvcmp() with ``uname -r`` as str_kver.
  *
- * Returns negative if older, 0 if the same and positive if 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: A {} terminated array of :ref:`struct tst_kern_exv`.
+ *
+ * Attempts to look up a distro specific kernel version from the struct
+ * tst_kern_exv table first and if no match is found falls back to the version
+ * passed in r1, r2, r3 (see tst_kvercmp()).
+ *
+ * The distribution name is detected either from the kernel release string e.g.
+ * el9 is mapped to RHEL9 or as a capitalized value of the ``ID=`` variable from
+ * ``/etc/os-release``.
+ *
+ * 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