doc: Correct docstring format to silence warnings

Several unikraft files have inconsistent docstrings which generate many
warnings when building with clang.
This change corrects all inconsistencies, silencing the warnings.

Signed-off-by: Andrei Tatar <andrei@unikraft.io>
Reviewed-by: Marco Schlumpp <marco@unikraft.io>
Reviewed-by: Stefan Jumarea <stefanjumarea02@gmail.com>
Approved-by: Razvan Deaconescu <razvand@unikraft.io>
Tested-by: Unikraft CI <monkey@unikraft.io>
GitHub-Closes: unikraft#927

include/uk/bitops.h

@@ -244,10 +244,10 @@ uk_find_next_zero_bit(const unsigned long *addr, unsigned long size,
 
 /**
  * uk_test_and_clear_bit - Atomically clear a bit and return its old value
- * @nr: Bit to clear
- * @addr: Address to count from
+ * @param nr Bit to clear
+ * @param addr Address to count from
  *
- * Note that @nr may be almost arbitrarily large; this function is not
+ * Note that nr may be almost arbitrarily large; this function is not
  * restricted to acting on a single-word quantity.
  */
 static inline int
@@ -264,10 +264,10 @@ uk_test_and_clear_bit(long nr, volatile unsigned long *addr)
 
 /**
  * __uk_test_and_clear_bit - Clear a bit and return its old value
- * @nr: Bit to clear
- * @addr: Address to count from
+ * @param nr Bit to clear
+ * @param addr Address to count from
  *
- * Note that @nr may be almost arbitrarily large; this function is not
+ * Note that nr may be almost arbitrarily large; this function is not
  * restricted to acting on a single-word quantity.
  *
  * This operation is not atomic and can be reordered. If two
@@ -288,10 +288,10 @@ __uk_test_and_clear_bit(long nr, volatile unsigned long *addr)
 
 /**
  * uk_test_and_set_bit - Atomically set a bit and return its old value
- * @nr: Bit to clear
- * @addr: Address to count from
+ * @param nr Bit to clear
+ * @param addr Address to count from
  *
- * Note that @nr may be almost arbitrarily large; this function is not
+ * Note that nr may be almost arbitrarily large; this function is not
  * restricted to acting on a single-word quantity.
  */
 static inline int
@@ -308,10 +308,10 @@ uk_test_and_set_bit(long nr, volatile unsigned long *addr)
 
 /**
  * __uk_test_and_set_bit - Set a bit and return its old value
- * @nr: Bit to clear
- * @addr: Address to count from
+ * @param nr Bit to clear
+ * @param addr Address to count from
  *
- * Note that @nr may be almost arbitrarily large; this function is not
+ * Note that nr may be almost arbitrarily large; this function is not
  * restricted to acting on a single-word quantity.
  *
  * This operation is not atomic and can be reordered. If two

include/uk/plat/bootstrap.h

@@ -48,7 +48,7 @@ extern "C" {
  * already, otherwise a platform library will call ukplat_entry_argp() to let
  * the arguments parsed from a string buffer
  * @param argc Number of arguments
- * @param args Array to '\0'-terminated arguments
+ * @param argv Array to '\0'-terminated arguments
  */
 void ukplat_entry(int argc, char *argv[]) __noreturn;
 

include/uk/plat/console.h

@@ -124,7 +124,7 @@ int ukplat_coutd(const char *buf, unsigned int len);
  * Reads characters from kernel console
  * Note that returned buf is not null terminated.
  * @param buf Target buffer
- * @param len Length of string buffer
+ * @param maxlen Length of string buffer
  * @return Number of read characters, errno on < 0
  */
 int ukplat_cink(char *buf, unsigned int maxlen);

include/uk/plat/tls.h

@@ -80,6 +80,8 @@ static inline void ukplat_tls_set(void *tls_area)
 	ukplat_tlsp_set(ukarch_tls_tlsp(tls_area));
 }
 
+typedef int (*ukplat_tlsp_exec_fn)(void *);
+
 /**
  * Executes a function with a different TLS pointer activated.
  * This wrapper function will apply a given TLS pointer before executing
@@ -99,8 +101,6 @@ static inline void ukplat_tls_set(void *tls_area)
  * @return
  *   The return value from `fn()`
  */
-typedef int (*ukplat_tlsp_exec_fn)(void *);
-
 static __noinline __maybe_unused int
 ukplat_tlsp_exec(__uptr tlsp, ukplat_tlsp_exec_fn fn, void *argp)
 {

include/uk/refcount.h

@@ -59,9 +59,9 @@ extern "C" {
 /**
  * Initialize the atomic reference.
  *
- * @param ref:
+ * @param ref
  *	A reference to the atomic data structure.
- * @param value:
+ * @param value
  *	A value to initialize.
  */
 static inline void uk_refcount_init(__atomic *ref, __u32 value)
@@ -73,7 +73,7 @@ static inline void uk_refcount_init(__atomic *ref, __u32 value)
 
 /**
  * Increment the reference counter.
- * @param refs
+ * @param ref
  *	Reference to the atomic counter.
  */
 static inline void uk_refcount_acquire(__atomic *ref)
@@ -85,7 +85,7 @@ static inline void uk_refcount_acquire(__atomic *ref)
 
 /**
  * Decrement the reference counter.
- * @param refs
+ * @param ref
  *	Reference to the atomic counter.
  * @return
  *	0: there are more active reference
@@ -117,7 +117,7 @@ static inline int uk_refcount_release(__atomic *ref)
 
 /**
  * Increment the reference counter if it was already in use.
- * @param refs
+ * @param ref
  *	Reference to the atomic counter.
  * @return
  *	0: Failed to acquire the counter.
@@ -141,7 +141,7 @@ static inline int uk_refcount_acquire_if_not_zero(__atomic *ref)
 
 /**
  * refcount_read - get a refcount's value
- * @r: the refcount
+ * @param ref the refcount
  *
  * Return: the refcount's value
  */
@@ -155,7 +155,7 @@ static inline __u32 uk_refcount_read(const __atomic *ref)
 
 /**
  * Decrement the reference counter if there are multiple users of the counter.
- * @param refs
+ * @param ref
  *	Reference to the atomic counter.
  * @return
  *	0: Failed to acquire the counter.