[LTP] [PATCH 3/4] include: Fix kernel-doc warnings in header comments

[Andrea Cervesato]

From: Andrea Cervesato <andrea.cervesato@suse.com>

Drop :ref: cross-references to undocumented structs in tst_test.h
and tst_kvercmp.h kernel-doc comments, replacing them with plain
text. These produced 'undefined label' Sphinx warnings.

Downgrade kernel-doc comments to plain comments for struct tst_cmd
and TST_CAP() macro to avoid name collisions with the tst_cmd()
function and struct tst_cap respectively. The kernel-doc parser
flattens names case-insensitively, causing 'name used several times'
errors and duplicate target warnings.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
 include/tst_capability.h |  2 +-
 include/tst_cmd.h        |  2 +-
 include/tst_kvercmp.h    |  2 +-
 include/tst_test.h       | 16 ++++++++--------
 4 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/include/tst_capability.h b/include/tst_capability.h
index ccf4bd77b5d7f663f35f587ea2c0a7369070552e..34c5d94d2e54fb96742ba208301cfab83bdbcac2 100644
--- a/include/tst_capability.h
+++ b/include/tst_capability.h
@@ -67,7 +67,7 @@ struct tst_cap {
 	char *name;
 };
 
-/**
+/*
  * TST_CAP() - Create a struct tst_cap entry.
  *
  * @action: What should we do, i.e. drop or add capability.
diff --git a/include/tst_cmd.h b/include/tst_cmd.h
index 831cb4da486881f9ef345b9f6ead461feb5dfd46..77fbbbc867b6edf841c5347ac612569a5b8470d1 100644
--- a/include/tst_cmd.h
+++ b/include/tst_cmd.h
@@ -19,7 +19,7 @@ enum tst_cmd_flags {
 	TST_CMD_TCONF_ON_MISSING = 2,
 };
 
-/**
+/*
  * struct tst_cmd - Provides details about a command struct needed by LTP test.
  * @cmd: The name of the command.
  * @optional: A flag indicating if the command is optional.
diff --git a/include/tst_kvercmp.h b/include/tst_kvercmp.h
index 7c991c746a3ab5383535b545c3025f2174d7722b..8457f7926da2022a9fcd215c9404e5cd7f566e0b 100644
--- a/include/tst_kvercmp.h
+++ b/include/tst_kvercmp.h
@@ -93,7 +93,7 @@ struct tst_kern_exv {
  * @r1: Major kernel version.
  * @r2: Minor kernel version.
  * @r3: Kernel patch level.
- * @vers: A {} terminated array of :ref:`struct tst_kern_exv`.
+ * @vers: A {} terminated array of 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
diff --git a/include/tst_test.h b/include/tst_test.h
index 530f22f6e8ee3686bea4b4cc8b080b3c4e6a70c3..16387d21b31896092c82a596147dcc06376933b3 100644
--- a/include/tst_test.h
+++ b/include/tst_test.h
@@ -298,7 +298,7 @@ struct tst_fs {
  *
  * @tcnt: A number of tests. If set the test() callback is called tcnt times
  *        and each time passed an increasing counter value.
- * @options: An NULL optstr terminated array of :ref:`struct tst_option`.
+ * @options: An NULL optstr terminated array of struct tst_option.
  *
  * @min_kver: A minimal kernel version the test can run on. e.g. "3.10".
  *
@@ -322,7 +322,7 @@ struct tst_fs {
  * @forks_child: Has to be set if the test intends to fork children.
  *
  * @needs_device: If set a block device is prepared for the test, the device
- *                path and size are set in the :ref:`struct tst_device` variable
+ *                path and size are set in the struct tst_device variable
  *                called tst_device. If $LTP_DEV variable exists in the test
  *                environment the test attempts to use that device first and
  *                only if that fails the test falls back to use loop devices.
@@ -361,7 +361,7 @@ struct tst_fs {
  *                   i.e. file system that is supported by the kernel and has
  *                   mkfs installed on the system.The file system is mounted at
  *                   tst_test.mntpoint and file system details, e.g. type are set
- *                   in the :ref:`struct tst_device`. Each execution is independent,
+ *                   in the struct tst_device. Each execution is independent,
  *                   that means that for each iteration tst_test.setup() is
  *                   called at the test start and tst_test.cleanup() is called
  *                   at the end and tst_brk() only exits test for a single
@@ -500,7 +500,7 @@ struct tst_fs {
  *
  * @save_restore: A {} terminated array of /proc or /sys files that should
  *                saved at the start of the test and restored at the end. See
- *                tst_sys_conf_save() and :ref:`struct tst_path_val` for details.
+ *                tst_sys_conf_save() and struct tst_path_val for details.
  *
  * @ulimit: A {} terminated array of process limits RLIMIT_* to be adjusted for
  *          the test.
@@ -522,14 +522,14 @@ struct tst_fs {
  * @bufs: A description of guarded buffers to be allocated for the test. Guarded
  *        buffers are buffers with poisoned page allocated right before the start
  *        of the buffer and canary right after the end of the buffer. See
- *        :ref:`struct tst_buffers` and tst_buffers_alloc() for details.
+ *        struct tst_buffers and tst_buffers_alloc() for details.
  *
  * @caps: A {} terminated array of capabilities to change before the start of
- *        the test. See :ref:`struct tst_cap` and tst_cap_setup() for details.
+ *        the test. See struct tst_cap and tst_cap_setup() for details.
  *
- * @tags: A {} terminated array of test tags. See :ref:`struct tst_tag` for details.
+ * @tags: A {} terminated array of test tags. See struct tst_tag for details.
  *
- * @needs_cmds: A NULL terminated array of :ref:`struct tst_cmd` required for the test to run.
+ * @needs_cmds: A NULL terminated array of struct tst_cmd required for the test to run.
  *
  * @needs_cgroup_ver: If set the test will run only if the specified cgroup
  *                    version is present on the system.

-- 
2.51.0