[doxygen] Fix some warnings in doxygen (#6899)

9 files changed, 29 insertions, 39 deletions

diff --git a/documentation/doxygen/.gitignore b/documentation/doxygen/.gitignore
new file mode 100644
index 0000000000..fe056cc69f
--- /dev/null
+++ b/documentation/doxygen/.gitignore
@@ -0,0 +1,2 @@
+html/
+latex/
\ No newline at end of file
diff --git a/documentation/doxygen/filesystem.h b/documentation/doxygen/filesystem.h
index f5a1834e25..ed322d0953 100644
--- a/documentation/doxygen/filesystem.h
+++ b/documentation/doxygen/filesystem.h
@@ -21,8 +21,8 @@
 
 /**
  * @addtogroup DFS
+ * @{
  */
-/*@{*/
 
 /**
  * @defgroup Fd File Descriptor
@@ -41,4 +41,4 @@
  * @defgroup FsPosixApi File POSIX API
  */
 
-/*@}*/
+/**@}*/
diff --git a/documentation/doxygen/images/.gitkeep b/documentation/doxygen/images/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/documentation/doxygen/images/.gitkeep
diff --git a/include/rtdef.h b/include/rtdef.h
index ffafa5db1d..31341759bf 100644
--- a/include/rtdef.h
+++ b/include/rtdef.h
@@ -570,6 +570,8 @@ typedef struct rt_timer *rt_timer_t;
 /**
  * @addtogroup Signal
  */
+/**@{*/
+
 #ifdef RT_USING_SIGNALS
 #include <sys/signal.h>
 typedef unsigned long rt_sigset_t;
diff --git a/include/rtthread.h b/include/rtthread.h
index b5203015ee..7538a3c032 100644
--- a/include/rtthread.h
+++ b/include/rtthread.h
@@ -37,10 +37,9 @@ extern "C" {
 
 /**
  * @addtogroup KernelObject
+ * @{
  */
 
-/**@{*/
-
 /*
  * kernel object interface
  */
@@ -80,10 +79,9 @@ void rt_object_put_sethook(void (*hook)(struct rt_object *object));
 
 /**
  * @addtogroup Clock
+ * @{
  */
 
-/**@{*/
-
 /*
  * clock & timer interface
  */
@@ -130,10 +128,9 @@ void rt_timer_exit_sethook(void (*hook)(struct rt_timer *timer));
 
 /**
  * @addtogroup Thread
+ * @{
  */
 
-/**@{*/
-
 /*
  * thread interface
  */
@@ -232,14 +229,13 @@ int rt_signal_wait(const rt_sigset_t *set, rt_siginfo_t *si, rt_int32_t timeout)
 
 int rt_system_signal_init(void);
 #endif
-/*@}*/
+/**@}*/
 
 /**
  * @addtogroup MM
+ * @{
  */
 
-/**@{*/
-
 /*
  * memory management interface
  */
@@ -347,10 +343,9 @@ void rt_slab_free(rt_slab_t m, void *ptr);
 
 /**
  * @addtogroup IPC
+ * @{
  */
 
-/**@{*/
-
 #ifdef RT_USING_SEMAPHORE
 /*
  * semaphore interface
@@ -537,10 +532,9 @@ void rt_spin_unlock_irqrestore(struct rt_spinlock *lock, rt_base_t level);
 #ifdef RT_USING_DEVICE
 /**
  * @addtogroup Device
+ * @{
  */
 
-/**@{*/
-
 /*
  * device (I/O) system interface
  */
@@ -627,10 +621,9 @@ void rt_components_board_init(void);
 
 /**
  * @addtogroup KernelService
+ * @{
  */
 
-/**@{*/
-
 /*
  * general kernel service
  */
diff --git a/src/ipc.c b/src/ipc.c
index fa25ce73a1..0aafb2ea6d 100644
--- a/src/ipc.c
+++ b/src/ipc.c
@@ -67,10 +67,9 @@ extern void (*rt_object_put_hook)(struct rt_object *object);
 
 /**
  * @addtogroup IPC
+ * @{
  */
 
-/**@{*/
-
 /**
  * @brief    This function will initialize an IPC object, such as semaphore, mutex, messagequeue and mailbox.
  *
@@ -112,6 +111,8 @@ rt_inline rt_err_t _ipc_object_init(struct rt_ipc_object *ipc)
  *               the first-in-first-out principle, and you clearly understand that all threads involved in
  *               this semaphore will become non-real-time threads.
  *
+ * @param    suspend_flag status flag of the thread to be suspended.
+ *
  * @return   Return the operation status. When the return value is RT_EOK, the function is successfully executed.
  *           When the return value is any other values, it means the initialization failed.
  *
@@ -257,14 +258,12 @@ rt_inline rt_err_t _ipc_list_resume_all(rt_list_t *list)
     return RT_EOK;
 }
 
-/**@}*/
-
 #ifdef RT_USING_SEMAPHORE
 /**
  * @addtogroup semaphore
+ * @{
  */
 
-/**@{*/
 /**
  * @brief    This function will initialize a static semaphore object.
  *
@@ -777,7 +776,7 @@ rt_inline rt_uint8_t _thread_get_mutex_priority(struct rt_thread* thread)
 }
 
 rt_inline void _thread_update_priority(struct rt_thread *thread, rt_uint8_t priority, int suspend_flag)
-{   
+{
     rt_err_t ret;
     RT_DEBUG_LOG(RT_DEBUG_IPC,
             ("thread:%s priority -> %d\n", thread->name, priority));
@@ -828,10 +827,9 @@ rt_inline void _thread_update_priority(struct rt_thread *thread, rt_uint8_t prio
 
 /**
  * @addtogroup mutex
+ * @{
  */
 
-/**@{*/
-
 /**
  * @brief    Initialize a static mutex object.
  *
@@ -1538,10 +1536,9 @@ RTM_EXPORT(rt_mutex_control);
 #ifdef RT_USING_EVENT
 /**
  * @addtogroup event
+ * @{
  */
 
-/**@{*/
-
 /**
  * @brief    The function will initialize a static event object.
  *
@@ -2084,10 +2081,9 @@ RTM_EXPORT(rt_event_control);
 #ifdef RT_USING_MAILBOX
 /**
  * @addtogroup mailbox
+ * @{
  */
 
-/**@{*/
-
 /**
  * @brief    Initialize a static mailbox object.
  *
@@ -2102,6 +2098,8 @@ RTM_EXPORT(rt_event_control);
  *
  * @param    name is a pointer to the name that given to the mailbox.
  *
+ * @param    msgpool the begin address of buffer to save received mail.
+ *
  * @param    size is the maximum number of mails in the mailbox.
  *           For example, when the mailbox buffer capacity is N, size is N/4.
  *
@@ -2842,10 +2840,9 @@ RTM_EXPORT(rt_mb_control);
 #ifdef RT_USING_MESSAGEQUEUE
 /**
  * @addtogroup messagequeue
+ * @{
  */
 
-/**@{*/
-
 struct rt_mq_message
 {
     struct rt_mq_message *next;
@@ -3778,5 +3775,4 @@ RTM_EXPORT(rt_mq_control);
 
 /**@}*/
 #endif /* RT_USING_MESSAGEQUEUE */
-
 /**@}*/
diff --git a/src/kservice.c b/src/kservice.c
index 0a8902b360..54c2e133ab 100644
--- a/src/kservice.c
+++ b/src/kservice.c
@@ -44,10 +44,9 @@
 
 /**
  * @addtogroup KernelService
+ * @{
  */
 
-/**@{*/
-
 /* global errno in RT-Thread */
 static volatile int __rt_errno;
 
@@ -1390,10 +1389,9 @@ static void (*rt_free_hook)(void *ptr);
 
 /**
  * @addtogroup Hook
+ * @{
  */
 
-/**@{*/
-
 /**
  * @brief This function will set a hook function, which will be invoked when a memory
  *        block is allocated from heap memory.
diff --git a/src/mem.c b/src/mem.c
index 221a5553e6..aade0f5bfa 100644
--- a/src/mem.c
+++ b/src/mem.c
@@ -165,8 +165,6 @@ static void plug_holes(struct rt_small_mem *m, struct rt_small_mem_item *mem)
 /**
  * @brief This function will initialize small memory management algorithm.
  *
- * @param m the small memory management object.
- *
  * @param name is the name of the small memory management object.
  *
  * @param begin_addr the beginning address of memory.
diff --git a/src/thread.c b/src/thread.c
index 6c642bb8a8..5614edea4d 100644
--- a/src/thread.c
+++ b/src/thread.c
@@ -967,7 +967,8 @@ static void rt_thread_set_suspend_state(struct rt_thread *thread, int suspend_fl
  *          thread is executing when you suspend it. If you suspend a thread while sharing a resouce with
  *          other threads and occupying this resouce, starvation can occur very easily.
  *
- * @param   thread is the thread to be suspended.
+ * @param   thread the thread to be suspended.
+ * @param   suspend_flag status flag of the thread to be suspended.
  *
  * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
  *          If the return value is any other values, it means this operation failed.