[LTP] [PATCH 8/9] doc: Document CPU and common test helpers

[Andrea Cervesato <andrea.cervesato@suse.de>]

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

Fix the kernel-doc formatting in include/tst_common.h and include
both tst_common.h and tst_cpu.h in the C API reference documentation.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
 doc/developers/api_c_tests.rst |  5 +++++
 include/tst_common.h           | 18 ++++++++++--------
 2 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst
index d4d06df0a..af7d84ce1 100644
--- a/doc/developers/api_c_tests.rst
+++ b/doc/developers/api_c_tests.rst
@@ -29,9 +29,14 @@ Commands
 
 Core LTP API
 ------------
+.. kernel-doc:: ../../include/tst_common.h
 .. kernel-doc:: ../../include/tst_res_flags.h
 .. kernel-doc:: ../../include/tst_test.h
 
+CPU
+---
+.. kernel-doc:: ../../include/tst_cpu.h
+
 Crypto
 ------
 .. kernel-doc:: ../../include/tst_crypto.h
diff --git a/include/tst_common.h b/include/tst_common.h
index d09edbbbe..b7a0e6734 100644
--- a/include/tst_common.h
+++ b/include/tst_common.h
@@ -30,15 +30,17 @@ unsigned int tst_multiply_timeout(unsigned int timeout);
 
 /**
  * TST_RETRY_FUNC() - Repeatedly retry a function with an increasing delay.
- * @FUNC - The function which will be retried
- * @ECHCK - Function/macro for validating @FUNC return value
  *
- * This macro will call @FUNC in a loop with a delay between retries.
- * If ECHCK(ret) evaluates to non-zero, the loop ends. The delay between
- * retries starts at one microsecond and is then doubled each iteration until
- * it exceeds one second (the total time sleeping will be approximately one
- * second as well). When the delay exceeds one second, the loop will end.
- * The TST_RETRY_FUNC() macro returns the last value returned by @FUNC.
+ * @FUNC: The function which will be retried.
+ * @ECHCK: Function or macro for validating @FUNC return value.
+ *
+ * This macro will call @FUNC in a loop with an exponential delay between
+ * retries. If ECHCK(ret) evaluates to non-zero, the loop ends. The delay
+ * starts at one microsecond and doubles each iteration until it exceeds
+ * one second (scaled by tst_multiply_timeout()). When the maximum delay
+ * is exceeded, the loop ends.
+ *
+ * Return: The last value returned by @FUNC.
  */
 #define TST_RETRY_FUNC(FUNC, ECHCK) \
 	TST_RETRY_FN_EXP_BACKOFF(FUNC, ECHCK, 1)

-- 
2.51.0


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