From d3b030be9bed8e396910a4b474ded7bdee894f1a Mon Sep 17 00:00:00 2001
From: Daniel Leung <daniel.leung@intel.com>
Date: Thu, 6 Jan 2022 16:28:14 -0800
Subject: [PATCH] kernel: remove @return doc for void functions

For functions returning nothing, there is no need to document
with @return, as Doxgen complains about "documented empty
return type of ...".

Signed-off-by: Daniel Leung <daniel.leung@intel.com>
---
 include/kernel.h        | 113 +---------------------------------------
 include/kernel/thread.h |   2 -
 kernel/init.c           |   6 ---
 kernel/mailbox.c        |   2 -
 kernel/mem_slab.c       |   5 +-
 kernel/timer.c          |   2 -
 kernel/xip.c            |   3 --
 7 files changed, 4 insertions(+), 129 deletions(-)

diff --git a/include/kernel.h b/include/kernel.h
index 4e1cd6d4459..22a4cabf311 100644
--- a/include/kernel.h
+++ b/include/kernel.h
@@ -109,8 +109,6 @@ typedef void (*k_thread_user_cb_t)(const struct k_thread *thread,
  * @note This API uses @ref k_spin_lock to protect the _kernel.threads
  * list which means creation of new threads and terminations of existing
  * threads are blocked until this API returns.
- *
- * @return N/A
  */
 extern void k_thread_foreach(k_thread_user_cb_t user_cb, void *user_data);
 
@@ -463,8 +461,6 @@ __syscall int32_t k_usleep(int32_t us);
  * k_sleep().  For example k_busy_wait(1000) may take slightly more or
  * less time than k_sleep(K_MSEC(1)), with the offset dependent on
  * clock tolerances.
- *
- * @return N/A
  */
 __syscall void k_busy_wait(uint32_t usec_to_wait);
 
@@ -474,8 +470,6 @@ __syscall void k_busy_wait(uint32_t usec_to_wait);
  * This routine causes the current thread to yield execution to another
  * thread of the same or higher priority. If there are no other ready threads
  * of the same or higher priority, the routine returns immediately.
- *
- * @return N/A
  */
 __syscall void k_yield(void);
 
@@ -487,8 +481,6 @@ __syscall void k_yield(void);
  * If @a thread is not currently sleeping, the routine has no effect.
  *
  * @param thread ID of thread to wake.
- *
- * @return N/A
  */
 __syscall void k_wakeup(k_tid_t thread);
 
@@ -545,8 +537,6 @@ static inline k_tid_t k_current_get(void)
  * all such conditions.
  *
  * @param thread ID of thread to abort.
- *
- * @return N/A
  */
 __syscall void k_thread_abort(k_tid_t thread);
 
@@ -719,8 +709,6 @@ __syscall int k_thread_priority_get(k_tid_t thread);
  *
  * @warning Changing the priority of a thread currently involved in mutex
  * priority inheritance may result in undefined behavior.
- *
- * @return N/A
  */
 __syscall void k_thread_priority_set(k_tid_t thread, int prio);
 
@@ -833,8 +821,6 @@ int k_thread_cpu_mask_disable(k_tid_t thread, int cpu);
  * If @a thread is already suspended, the routine has no effect.
  *
  * @param thread ID of thread to suspend.
- *
- * @return N/A
  */
 __syscall void k_thread_suspend(k_tid_t thread);
 
@@ -847,8 +833,6 @@ __syscall void k_thread_suspend(k_tid_t thread);
  * If @a thread is not currently suspended, the routine has no effect.
  *
  * @param thread ID of thread to resume.
- *
- * @return N/A
  */
 __syscall void k_thread_resume(k_tid_t thread);
 
@@ -877,8 +861,6 @@ __syscall void k_thread_resume(k_tid_t thread);
  *
  * @param slice Maximum time slice length (in milliseconds).
  * @param prio Highest thread priority level eligible for time slicing.
- *
- * @return N/A
  */
 extern void k_sched_time_slice_set(int32_t slice, int prio);
 
@@ -962,8 +944,6 @@ static inline bool k_is_pre_kernel(void)
  * when the operation being performed can be safely interrupted by ISRs.
  * However, if the amount of processing involved is very small, better
  * performance may be obtained by using irq_lock() and irq_unlock().
- *
- * @return N/A
  */
 extern void k_sched_lock(void);
 
@@ -973,8 +953,6 @@ extern void k_sched_lock(void);
  * This routine reverses the effect of a previous call to k_sched_lock().
  * A thread must call the routine once for each time it called k_sched_lock()
  * before the thread becomes preemptible.
- *
- * @return N/A
  */
 extern void k_sched_unlock(void);
 
@@ -989,8 +967,6 @@ extern void k_sched_unlock(void);
  *
  * @param value New custom data value.
  *
- * @return N/A
- *
  */
 __syscall void k_thread_custom_data_set(void *value);
 
@@ -1324,8 +1300,6 @@ struct k_timer {
  * invoked if the timer has been initialized with one.
  *
  * @param timer     Address of timer.
- *
- * @return N/A
  */
 typedef void (*k_timer_expiry_t)(struct k_timer *timer);
 
@@ -1342,8 +1316,6 @@ typedef void (*k_timer_expiry_t)(struct k_timer *timer);
  * initialized with one.
  *
  * @param timer     Address of timer.
- *
- * @return N/A
  */
 typedef void (*k_timer_stop_t)(struct k_timer *timer);
 
@@ -1370,8 +1342,6 @@ typedef void (*k_timer_stop_t)(struct k_timer *timer);
  * @param timer     Address of timer.
  * @param expiry_fn Function to invoke each time the timer expires.
  * @param stop_fn   Function to invoke if the timer is stopped while running.
- *
- * @return N/A
  */
 extern void k_timer_init(struct k_timer *timer,
 			 k_timer_expiry_t expiry_fn,
@@ -1390,8 +1360,6 @@ extern void k_timer_init(struct k_timer *timer,
  * @param timer     Address of timer.
  * @param duration  Initial timer duration.
  * @param period    Timer period.
- *
- * @return N/A
  */
 __syscall void k_timer_start(struct k_timer *timer,
 			     k_timeout_t duration, k_timeout_t period);
@@ -1411,8 +1379,6 @@ __syscall void k_timer_start(struct k_timer *timer,
  * @funcprops \isr_ok
  *
  * @param timer     Address of timer.
- *
- * @return N/A
  */
 __syscall void k_timer_stop(struct k_timer *timer);
 
@@ -1512,8 +1478,6 @@ static inline uint32_t k_timer_remaining_get(struct k_timer *timer)
  *
  * @param timer     Address of timer.
  * @param user_data User data to associate with the timer.
- *
- * @return N/A
  */
 __syscall void k_timer_user_data_set(struct k_timer *timer, void *user_data);
 
@@ -1701,8 +1665,6 @@ extern void *z_queue_node_peek(sys_sfnode_t *node, bool needs_free);
  * This routine initializes a queue object, prior to its first use.
  *
  * @param queue Address of the queue.
- *
- * @return N/A
  */
 __syscall void k_queue_init(struct k_queue *queue);
 
@@ -1718,8 +1680,6 @@ __syscall void k_queue_init(struct k_queue *queue);
  * @funcprops \isr_ok
  *
  * @param queue Address of the queue.
- *
- * @return N/A
  */
 __syscall void k_queue_cancel_wait(struct k_queue *queue);
 
@@ -1734,8 +1694,6 @@ __syscall void k_queue_cancel_wait(struct k_queue *queue);
  *
  * @param queue Address of the queue.
  * @param data Address of the data item.
- *
- * @return N/A
  */
 extern void k_queue_append(struct k_queue *queue, void *data);
 
@@ -1768,8 +1726,6 @@ __syscall int32_t k_queue_alloc_append(struct k_queue *queue, void *data);
  *
  * @param queue Address of the queue.
  * @param data Address of the data item.
- *
- * @return N/A
  */
 extern void k_queue_prepend(struct k_queue *queue, void *data);
 
@@ -1803,8 +1759,6 @@ __syscall int32_t k_queue_alloc_prepend(struct k_queue *queue, void *data);
  * @param queue Address of the queue.
  * @param prev Address of the previous data item.
  * @param data Address of the data item.
- *
- * @return N/A
  */
 extern void k_queue_insert(struct k_queue *queue, void *prev, void *data);
 
@@ -2056,16 +2010,14 @@ struct k_event {
 	.wait_q = Z_WAIT_Q_INIT(&obj.wait_q), \
 	.events = 0 \
 	}
+
 /**
  * @brief Initialize an event object
  *
  * This routine initializes an event object, prior to its first use.
  *
  * @param event Address of the event object.
- *
- * @return N/A
  */
-
 __syscall void k_event_init(struct k_event *event);
 
 /**
@@ -2080,10 +2032,7 @@ __syscall void k_event_init(struct k_event *event);
  *
  * @param event Address of the event object
  * @param events Set of events to post to @a event
- *
- * @return N/A
  */
-
 __syscall void k_event_post(struct k_event *event, uint32_t events);
 
 /**
@@ -2098,10 +2047,7 @@ __syscall void k_event_post(struct k_event *event, uint32_t events);
  *
  * @param event Address of the event object
  * @param events Set of events to post to @a event
- *
- * @return N/A
  */
-
 __syscall void k_event_set(struct k_event *event, uint32_t events);
 
 /**
@@ -2125,7 +2071,6 @@ __syscall void k_event_set(struct k_event *event, uint32_t events);
  * @retval set of matching events upon success
  * @retval 0 if matching events were not received within the specified time
  */
-
 __syscall uint32_t k_event_wait(struct k_event *event, uint32_t events,
 				bool reset, k_timeout_t timeout);
 
@@ -2150,7 +2095,6 @@ __syscall uint32_t k_event_wait(struct k_event *event, uint32_t events,
  * @retval set of matching events upon success
  * @retval 0 if matching events were not received within the specified time
  */
-
 __syscall uint32_t k_event_wait_all(struct k_event *event, uint32_t events,
 				    bool reset, k_timeout_t timeout);
 
@@ -2163,7 +2107,6 @@ __syscall uint32_t k_event_wait_all(struct k_event *event, uint32_t events,
  *
  * @param name Name of the event object.
  */
-
 #define K_EVENT_DEFINE(name)                                   \
 	STRUCT_SECTION_ITERABLE(k_event, name) =               \
 		Z_EVENT_INITIALIZER(name);
@@ -2198,8 +2141,6 @@ struct k_fifo {
  * This routine initializes a FIFO queue, prior to its first use.
  *
  * @param fifo Address of the FIFO queue.
- *
- * @return N/A
  */
 #define k_fifo_init(fifo) \
 	({ \
@@ -2218,8 +2159,6 @@ struct k_fifo {
  * @funcprops \isr_ok
  *
  * @param fifo Address of the FIFO queue.
- *
- * @return N/A
  */
 #define k_fifo_cancel_wait(fifo) \
 	({ \
@@ -2239,8 +2178,6 @@ struct k_fifo {
  *
  * @param fifo Address of the FIFO.
  * @param data Address of the data item.
- *
- * @return N/A
  */
 #define k_fifo_put(fifo, data) \
 	({ \
@@ -2286,8 +2223,6 @@ struct k_fifo {
  * @param fifo Address of the FIFO queue.
  * @param head Pointer to first node in singly-linked list.
  * @param tail Pointer to last node in singly-linked list.
- *
- * @return N/A
  */
 #define k_fifo_put_list(fifo, head, tail) \
 	({ \
@@ -2308,8 +2243,6 @@ struct k_fifo {
  *
  * @param fifo Address of the FIFO queue.
  * @param list Pointer to sys_slist_t object.
- *
- * @return N/A
  */
 #define k_fifo_put_slist(fifo, list) \
 	({ \
@@ -2443,8 +2376,6 @@ struct k_lifo {
  * This routine initializes a LIFO queue object, prior to its first use.
  *
  * @param lifo Address of the LIFO queue.
- *
- * @return N/A
  */
 #define k_lifo_init(lifo) \
 	({ \
@@ -2464,8 +2395,6 @@ struct k_lifo {
  *
  * @param lifo Address of the LIFO queue.
  * @param data Address of the data item.
- *
- * @return N/A
  */
 #define k_lifo_put(lifo, data) \
 	({ \
@@ -2581,8 +2510,6 @@ struct k_stack {
  * @param stack Address of the stack.
  * @param buffer Address of array used to hold stacked values.
  * @param num_entries Maximum number of values that can be stacked.
- *
- * @return N/A
  */
 void k_stack_init(struct k_stack *stack,
 		  stack_data_t *buffer, uint32_t num_entries);
@@ -2974,8 +2901,6 @@ __syscall int k_sem_take(struct k_sem *sem, k_timeout_t timeout);
  * @funcprops \isr_ok
  *
  * @param sem Address of the semaphore.
- *
- * @return N/A
  */
 __syscall void k_sem_give(struct k_sem *sem);
 
@@ -2987,8 +2912,6 @@ __syscall void k_sem_give(struct k_sem *sem);
  * with -EAGAIN.
  *
  * @param sem Address of the semaphore.
- *
- * @return N/A
  */
 __syscall void k_sem_reset(struct k_sem *sem);
 
@@ -3990,8 +3913,6 @@ struct k_work_user;
  * when the work item is processed by the workqueue.
  *
  * @param work Address of the work item.
- *
- * @return N/A
  */
 typedef void (*k_work_user_handler_t)(struct k_work_user *work);
 
@@ -4047,8 +3968,6 @@ struct k_work_user {
  *
  * @param work Address of work item.
  * @param handler Function to invoke each time work item is processed.
- *
- * @return N/A
  */
 static inline void k_work_user_init(struct k_work_user *work,
 				    k_work_user_handler_t handler)
@@ -4134,8 +4053,6 @@ static inline int k_work_user_submit_to_queue(struct k_work_user_q *work_q,
  * @param prio Priority of the work queue's thread.
  * @param name optional thread name.  If not null a copy is made into the
  *		thread's name buffer.
- *
- * @return N/A
  */
 extern void k_work_user_queue_start(struct k_work_user_q *work_q,
 				    k_thread_stack_t *stack,
@@ -4204,8 +4121,6 @@ struct k_work_poll {
  *
  * @param work Address of triggered work item.
  * @param handler Function to invoke each time work item is processed.
- *
- * @return N/A
  */
 extern void k_work_poll_init(struct k_work_poll *work,
 			     k_work_handler_t handler);
@@ -4420,8 +4335,6 @@ struct k_msgq_attrs {
  * @param buffer Pointer to ring buffer that holds queued messages.
  * @param msg_size Message size (in bytes).
  * @param max_msgs Maximum number of messages that can be queued.
- *
- * @return N/A
  */
 void k_msgq_init(struct k_msgq *msgq, char *buffer, size_t msg_size,
 		 uint32_t max_msgs);
@@ -4529,8 +4442,6 @@ __syscall int k_msgq_peek(struct k_msgq *msgq, void *data);
  * message queue are unblocked and see an -ENOMSG error code.
  *
  * @param msgq Address of the message queue.
- *
- * @return N/A
  */
 __syscall void k_msgq_purge(struct k_msgq *msgq);
 
@@ -4553,8 +4464,6 @@ __syscall uint32_t k_msgq_num_free_get(struct k_msgq *msgq);
  *
  * @param msgq Address of the message queue.
  * @param attrs pointer to message queue attribute structure.
- *
- * @return N/A
  */
 __syscall void  k_msgq_get_attrs(struct k_msgq *msgq,
 				 struct k_msgq_attrs *attrs);
@@ -4663,8 +4572,6 @@ struct k_mbox {
  * This routine initializes a mailbox object, prior to its first use.
  *
  * @param mbox Address of the mailbox.
- *
- * @return N/A
  */
 extern void k_mbox_init(struct k_mbox *mbox);
 
@@ -4702,8 +4609,6 @@ extern int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
  * @param mbox Address of the mailbox.
  * @param tx_msg Address of the transmit message descriptor.
  * @param sem Address of a semaphore, or NULL if none is needed.
- *
- * @return N/A
  */
 extern void k_mbox_async_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
 			     struct k_sem *sem);
@@ -4740,8 +4645,6 @@ extern int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg,
  * @param rx_msg Address of the receive message descriptor.
  * @param buffer Address of the buffer to receive data, or NULL to discard
  *               the data.
- *
- * @return N/A
  */
 extern void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer);
 
@@ -4825,8 +4728,6 @@ struct k_pipe {
  *               is used.
  * @param size Size of the pipe's ring buffer (in bytes), or zero if no ring
  *             buffer is used.
- *
- * @return N/A
  */
 void k_pipe_init(struct k_pipe *pipe, unsigned char *buffer, size_t size);
 
@@ -5108,8 +5009,6 @@ extern int k_mem_slab_alloc(struct k_mem_slab *slab, void **mem,
  *
  * @param slab Address of the memory slab.
  * @param mem Pointer to block address area (as set by k_mem_slab_alloc()).
- *
- * @return N/A
  */
 extern void k_mem_slab_free(struct k_mem_slab *slab, void **mem);
 
@@ -5369,8 +5268,6 @@ extern void *k_malloc(size_t size);
  * If @a ptr is NULL, no operation is performed.
  *
  * @param ptr Pointer to previously allocated memory.
- *
- * @return N/A
  */
 extern void k_free(void *ptr);
 
@@ -5584,8 +5481,6 @@ struct k_poll_event {
  *             event.
  * @param mode Future. Use K_POLL_MODE_NOTIFY_ONLY.
  * @param obj Kernel object or poll signal.
- *
- * @return N/A
  */
 
 extern void k_poll_event_init(struct k_poll_event *event, uint32_t type,
@@ -5643,8 +5538,6 @@ __syscall int k_poll(struct k_poll_event *events, int num_events,
  * Ready a poll signal object to be signaled via k_poll_signal_raise().
  *
  * @param sig A poll signal.
- *
- * @return N/A
  */
 
 __syscall void k_poll_signal_init(struct k_poll_signal *sig);
@@ -5719,8 +5612,6 @@ extern void z_handle_obj_poll_events(sys_dlist_t *events, uint32_t state);
  *
  * @note In some architectures, before returning, the function unmasks interrupts
  * unconditionally.
- *
- * @return N/A
  */
 static inline void k_cpu_idle(void)
 {
@@ -5740,8 +5631,6 @@ static inline void k_cpu_idle(void)
  * be restored as if by irq_unlock(key).
  *
  * @param key Interrupt locking key obtained from irq_lock().
- *
- * @return N/A
  */
 static inline void k_cpu_atomic_idle(unsigned int key)
 {
diff --git a/include/kernel/thread.h b/include/kernel/thread.h
index 37be2ef51c6..f065871e4f0 100644
--- a/include/kernel/thread.h
+++ b/include/kernel/thread.h
@@ -28,8 +28,6 @@
  * @param p1 First argument.
  * @param p2 Second argument.
  * @param p3 Third argument.
- *
- * @return N/A
  */
 
 #ifdef CONFIG_THREAD_MONITOR
diff --git a/kernel/init.c b/kernel/init.c
index 8c8031d0a30..d2da037d1b0 100644
--- a/kernel/init.c
+++ b/kernel/init.c
@@ -76,12 +76,9 @@ extern void idle(void *unused1, void *unused2, void *unused3);
  */
 
 /**
- *
  * @brief Clear BSS
  *
  * This routine clears the BSS region, so all bytes are 0.
- *
- * @return N/A
  */
 __boot_func
 void z_bss_zero(void)
@@ -158,13 +155,10 @@ bool z_sys_post_kernel;
 extern void boot_banner(void);
 
 /**
- *
  * @brief Mainline for kernel's background thread
  *
  * This routine completes kernel initialization by invoking the remaining
  * init functions, then invokes application's main() routine.
- *
- * @return N/A
  */
 __boot_func
 static void bg_thread_main(void *unused1, void *unused2, void *unused3)
diff --git a/kernel/mailbox.c b/kernel/mailbox.c
index 18e5c14329d..efc954b964c 100644
--- a/kernel/mailbox.c
+++ b/kernel/mailbox.c
@@ -158,8 +158,6 @@ static int mbox_message_match(struct k_mbox_msg *tx_msg,
  * then notifies the sender that message processing is complete.
  *
  * @param rx_msg Pointer to receive message descriptor.
- *
- * @return N/A
  */
 static void mbox_message_dispose(struct k_mbox_msg *rx_msg)
 {
diff --git a/kernel/mem_slab.c b/kernel/mem_slab.c
index ab64eff3b1e..5f3485e249c 100644
--- a/kernel/mem_slab.c
+++ b/kernel/mem_slab.c
@@ -21,7 +21,8 @@
  * Perform any initialization of memory slabs that wasn't done at build time.
  * Currently this just involves creating the list of free blocks for each slab.
  *
- * @return N/A
+ * @retval 0 on success.
+ * @retval -EINVAL if @p slab contains invalid configuration and/or values.
  */
 static int create_free_list(struct k_mem_slab *slab)
 {
@@ -50,7 +51,7 @@ static int create_free_list(struct k_mem_slab *slab)
  *
  * Perform any initialization that wasn't done at build time.
  *
- * @return N/A
+ * @return 0 on success, fails otherwise.
  */
 static int init_mem_slab_module(const struct device *dev)
 {
diff --git a/kernel/timer.c b/kernel/timer.c
index 04a87380879..5c338a89426 100644
--- a/kernel/timer.c
+++ b/kernel/timer.c
@@ -19,8 +19,6 @@ static struct k_spinlock lock;
  * @brief Handle expiration of a kernel timer object.
  *
  * @param t  Timeout used by the timer.
- *
- * @return N/A
  */
 void z_timer_expiration_handler(struct _timeout *t)
 {
diff --git a/kernel/xip.c b/kernel/xip.c
index 62d46785c60..7e95686ca71 100644
--- a/kernel/xip.c
+++ b/kernel/xip.c
@@ -16,12 +16,9 @@ extern volatile uintptr_t __stack_chk_guard;
 #endif /* CONFIG_STACK_CANARIES */
 
 /**
- *
  * @brief Copy the data section from ROM to RAM
  *
  * This routine copies the data section from ROM to RAM.
- *
- * @return N/A
  */
 void z_data_copy(void)
 {