[HUST CSE][document] Fix some comments, invalid grouping commands and warnings in Doxygen.

将Doxygen输入文件（由Doxyfile中的INPUT定义）中的失效Doxygen分组指令（如/*@*/和/*@}*/）更改为有效的分组指令（如/**@*/和/**@}*/）；（此处只对INPUT中的文件做了修改，bsp目录下和libcpu目录下存在近万个失效的Doxygen分组指令，但由于不作为文档的输入文件且这些文件过于庞大老旧，没有对这些文件中的无效指令做修改）
将图片文件统一放入了images目录下；
修改了Doxyfile和部分Doxygen注释，使得Doxyfile能够定位到新的代码路径且不受重复实现的影响；
解决了一些注释中的参数名不匹配、参数多余/缺失等问题。

components/dfs/dfs_v1/src/dfs.c

@@ -39,10 +39,9 @@ static int  fd_alloc(struct dfs_fdtable *fdt, int startfd);
 
 /**
  * @addtogroup DFS
+ * @{
  */
 
-/*@{*/
-
 /**
  * this function will initialize device file system.
  */
@@ -967,5 +966,5 @@ MSH_CMD_EXPORT(lsof, list open files);
 #endif /* RT_USING_SMART */
 
 #endif
-/*@}*/
+/**@}*/
 

components/dfs/dfs_v1/src/dfs_file.c

@@ -89,10 +89,9 @@ static struct dfs_vnode *dfs_vnode_find(const char *path, rt_list_t **hash_head)
 
 /**
  * @addtogroup FileApi
+ * @{
  */
 
-/*@{*/
-
 /**
  * This function will return whether this file has been opend.
  *
@@ -1091,5 +1090,5 @@ FINSH_FUNCTION_EXPORT(copy, copy file or dir)
 #endif /* DFS_USING_POSIX */
 
 #endif /* RT_USING_FINSH */
-/* @} */
+/**@}*/
 

components/dfs/dfs_v1/src/dfs_fs.c

@@ -18,8 +18,8 @@
 
 /**
  * @addtogroup FsApi
+ * @{
  */
-/*@{*/
 
 /**
  * this function will register a file system instance to device file system.
@@ -654,4 +654,4 @@ int df(const char *path)
 FINSH_FUNCTION_EXPORT(df, get disk free);
 #endif
 
-/* @} */
+/**@}*/

components/dfs/dfs_v1/src/dfs_posix.c

@@ -20,10 +20,9 @@
 
 /**
  * @addtogroup FsPosixApi
+ * @{
  */
 
-/*@{*/
-
 /**
  * this function is a POSIX compliant version, which will open a file and
  * return a file descriptor according specified flags.
@@ -260,8 +259,8 @@ RTM_EXPORT(lseek);
  * this function is a POSIX compliant version, which will rename old file name
  * to new file name.
  *
- * @param old the old file name.
- * @param new the new file name.
+ * @param old_file the old file name.
+ * @param new_file the new file name.
  *
  * @return 0 on successful, -1 on failed.
  *
@@ -392,7 +391,7 @@ RTM_EXPORT(fsync);
  *
  * @param fildes the file description
  * @param cmd the specified command
- * @param data represents the additional information that is needed by this
+ * @param ... represents the additional information that is needed by this
  * specific device to perform the requested function.
  *
  * @return 0 on successful completion. Otherwise, -1 shall be returned and errno
@@ -434,7 +433,7 @@ RTM_EXPORT(fcntl);
  *
  * @param fildes the file description
  * @param cmd the specified command
- * @param data represents the additional information that is needed by this
+ * @param ... represents the additional information that is needed by this
  * specific device to perform the requested function.
  *
  * @return 0 on successful completion. Otherwise, -1 shall be returned and errno
@@ -921,8 +920,6 @@ int access(const char *path, int amode)
  * working directory.
  *
  * @param buf the current directory.
- *
- * @return null.
  */
 void setcwd(char *buf)
 {
@@ -979,4 +976,4 @@ char *getcwd(char *buf, size_t size)
 }
 RTM_EXPORT(getcwd);
 
-/* @} */
+/**@}*/

components/dfs/dfs_v2/src/dfs.c

@@ -39,10 +39,9 @@ static int  fd_alloc(struct dfs_fdtable *fdt, int startfd);
 
 /**
  * @addtogroup DFS
+ * @{
  */
 
-/*@{*/
-
 /**
  * this function will initialize device file system.
  */
@@ -967,5 +966,5 @@ MSH_CMD_EXPORT(lsof, list open files);
 #endif /* RT_USING_SMART */
 
 #endif
-/*@}*/
+/**@}*/
 

components/dfs/dfs_v2/src/dfs_file.c

@@ -89,10 +89,9 @@ static struct dfs_vnode *dfs_vnode_find(const char *path, rt_list_t **hash_head)
 
 /**
  * @addtogroup FileApi
+ * @{
  */
 
-/*@{*/
-
 /**
  * This function will return whether this file has been opend.
  *
@@ -1091,5 +1090,5 @@ FINSH_FUNCTION_EXPORT(copy, copy file or dir)
 #endif /* DFS_USING_POSIX */
 
 #endif /* RT_USING_FINSH */
-/* @} */
+/**@}*/
 

components/dfs/dfs_v2/src/dfs_fs.c

@@ -18,8 +18,8 @@
 
 /**
  * @addtogroup FsApi
+ * @{
  */
-/*@{*/
 
 /**
  * this function will register a file system instance to device file system.
@@ -654,4 +654,4 @@ int df(const char *path)
 FINSH_FUNCTION_EXPORT(df, get disk free);
 #endif
 
-/* @} */
+/**@}*/

components/dfs/dfs_v2/src/dfs_posix.c

@@ -20,10 +20,9 @@
 
 /**
  * @addtogroup FsPosixApi
+ * @{
  */
 
-/*@{*/
-
 /**
  * this function is a POSIX compliant version, which will open a file and
  * return a file descriptor according specified flags.
@@ -260,8 +259,8 @@ RTM_EXPORT(lseek);
  * this function is a POSIX compliant version, which will rename old file name
  * to new file name.
  *
- * @param old the old file name.
- * @param new the new file name.
+ * @param old_file the old file name.
+ * @param new_file the new file name.
  *
  * @return 0 on successful, -1 on failed.
  *
@@ -392,7 +391,7 @@ RTM_EXPORT(fsync);
  *
  * @param fildes the file description
  * @param cmd the specified command
- * @param data represents the additional information that is needed by this
+ * @param ... represents the additional information that is needed by this
  * specific device to perform the requested function.
  *
  * @return 0 on successful completion. Otherwise, -1 shall be returned and errno
@@ -434,7 +433,7 @@ RTM_EXPORT(fcntl);
  *
  * @param fildes the file description
  * @param cmd the specified command
- * @param data represents the additional information that is needed by this
+ * @param ... represents the additional information that is needed by this
  * specific device to perform the requested function.
  *
  * @return 0 on successful completion. Otherwise, -1 shall be returned and errno
@@ -921,8 +920,6 @@ int access(const char *path, int amode)
  * working directory.
  *
  * @param buf the current directory.
- *
- * @return null.
  */
 void setcwd(char *buf)
 {
@@ -979,4 +976,4 @@ char *getcwd(char *buf, size_t size)
 }
 RTM_EXPORT(getcwd);
 
-/* @} */
+/**@}*/

documentation/doxygen/Doxyfile

@@ -60,7 +60,7 @@ PROJECT_BRIEF          = "An open source embedded real-time operating system"
 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
 # the logo to the output directory.
 
-PROJECT_LOGO           = ./rtthread_logo.png
+PROJECT_LOGO           = ./images/rtthread_logo.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
 # into which the generated documentation will be written. If a relative path is
@@ -128,7 +128,7 @@ BRIEF_MEMBER_DESC      = NO
 # brief descriptions will be completely suppressed.
 # The default value is: YES.
 
-REPEAT_BRIEF           = NO
+REPEAT_BRIEF           = YES
 
 # This tag implements a quasi-intelligent brief description abbreviator that is
 # used to form the text in various listings. Each string in this list, if found
@@ -156,7 +156,7 @@ ABBREVIATE_BRIEF       = "The $name class" \
 # description.
 # The default value is: NO.
 
-ALWAYS_DETAILED_SEC    = NO
+ALWAYS_DETAILED_SEC    = YES
 
 # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
 # inherited members of a class in the documentation of that class as if those
@@ -910,8 +910,8 @@ INPUT                  = ../../src \
                          ../../include \
                          . \
                          ../../components/finsh \
-                         ../../components/dfs/src \
-                         ../../components/dfs/include
+                         ../../components/dfs/dfs_v2/src \
+                         ../../components/dfs/dfs_v2/include
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1012,7 +1012,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             = ../doxygen
+IMAGE_PATH             = ./images
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

documentation/doxygen/hardware.h

@@ -12,21 +12,21 @@
  * in board, the pinmux setting etc. In RT-Thread RTOS, the bsp is placed under bsp
  * directory.
  *
- * Chip Support Package (CSP) is a software set that contains chip specific software.
+ * Chip Support Package(CSP) is a software set that contains chip specific software.
  * A CSP usually includes operating system porting and peripheral device drivers inside
  * chip. In RT-Thread RTOS, the csp is placed under libcpu directory.
  */
 
 /**
  * @addtogroup bsp
+ * @{
  */
-/*@{*/
 
 /**
  * This function will return current system interrupt status and disable system
  * interrupt.
  *
- * @return the current system interrupt status
+ * @return the current system interrupt status.
  */
 rt_base_t rt_hw_interrupt_disable(void);
 
@@ -34,6 +34,8 @@ rt_base_t rt_hw_interrupt_disable(void);
  * This function will set the specified interrupt status, which shall saved by
  * rt_hw_intterrupt_disable function. If the saved interrupt status is interrupt
  * opened, this function will open system interrupt status.
+ *
+ * @param level the interrupt status to be set.
  */
 void rt_hw_interrupt_enable(rt_base_t level);
 
@@ -70,7 +72,7 @@ void rt_hw_interrupt_umask(int vector);
  * @note not all of platform provide this function.
  */
 void rt_hw_interrupt_install(int vector, rt_isr_handler_t new_handler,
-		rt_isr_handler_t *old_handler);
+                            rt_isr_handler_t *old_handler);
 
 /**
  * This function will reset whole platform.
@@ -82,4 +84,4 @@ void rt_hw_cpu_reset(void);
  */
 void rt_hw_cpu_shutdown(void);
 
-/*@}*/
+/**@}*/

documentation/doxygen/kernel.h

@@ -16,8 +16,8 @@
 
 /**
  * @addtogroup Kernel
+ * @{
  */
-/*@{*/
 
 /**
  * @defgroup Thread Thread Management
@@ -41,7 +41,7 @@
 
 /**
  * @defgroup Clock Clock and Timer Management
- *  * @brief clock and system timer management
+ * @brief clock and system timer management
  *
  * RT-Thread uses clock tick to implement shared time-slice scheduling.
  *
@@ -157,4 +157,4 @@
  * bad things happen, the current thread's errno will be set. see @ref _rt_errno
  */
 
-/*@}*/
+/**@}*/

documentation/doxygen/systeminit.h

@@ -55,19 +55,9 @@
  * has not started. User can allocate memory, create thread, semaphore etc. However,
  * user shall not suspend 'current' thread.
  */
-void rt_application_init()
-{
-}
+void rt_application_init();
 
 /**
  * @ingroup SystemInit
- *
- * This function will initialize system heap memory.
- *
- * @param begin_addr the beginning address of system heap memory.
- * @param end_addr the end address of system heap memory.
- *
  */
-void rt_system_heap_init(void* begin_addr, void* end_addr)
-{
-}
+void rt_system_heap_init(void* begin_addr, void* end_addr);

documentation/doxygen/thread.h

@@ -0,0 +1,89 @@
+/*
+ * This file is only used for doxygen document generation.
+ */
+
+/**
+ * @addtogroup Thread
+ * @{
+ */
+
+/**
+ * @brief This function will handle IPI interrupt and do a scheduling in system.
+ *
+ * @param vector is the number of IPI interrupt for system scheduling.
+ *
+ * @param param is not used, and can be set to RT_NULL.
+ *
+ * @note this function should be invoke or register as ISR in BSP.
+ *
+ * @note this function is only implemented in scheduler_mp.c.
+ */
+void rt_scheduler_ipi_handler(int vector, void *param);
+
+/**
+ * @brief This function will perform one scheduling. It will select one thread
+ *        with the highest priority level in global ready queue or local ready queue,
+ *        then switch to it.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_schedule(void);
+
+/**
+ * @brief This function checks whether a scheduling is needed after an IRQ context switching. If yes,
+ *        it will select one thread with the highest priority level, and then switch
+ *        to it.
+ *
+ * @param context is the context to be switched to.
+ *
+ * @note this function is only implemented in scheduler_mp.c.
+ */
+void rt_scheduler_do_irq_switch(void *context);
+
+/**
+ * @brief This function will insert a thread to the system ready queue. The state of
+ *        thread will be set as READY and the thread will be removed from suspend queue.
+ *
+ * @param thread is the thread to be inserted.
+ *
+ * @note  Please do not invoke this function in user application.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_schedule_insert_thread(struct rt_thread *thread);
+
+/**
+ * @brief This function will remove a thread from system ready queue.
+ *
+ * @param thread is the thread to be removed.
+ *
+ * @note  Please do not invoke this function in user application.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_schedule_remove_thread(struct rt_thread *thread);
+
+/**
+ * @brief This function will lock the thread scheduler.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_enter_critical(void);
+
+/**
+ * @brief This function will unlock the thread scheduler.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+void rt_exit_critical(void);
+
+/**
+ * @brief Get the scheduler lock level.
+ *
+ * @return the level of the scheduler lock. 0 means unlocked.
+ *
+ * @note this function is implemented in both scheduler_up.c and scheduler_mp.c.
+ */
+rt_uint16_t rt_critical_level(void);
+
+/**@}*/

src/components.c

@@ -174,6 +174,8 @@ struct rt_thread main_thread;
  * @brief  The system main thread. In this thread will call the rt_components_init()
  *         for initialization of RT-Thread Components and call the user's programming
  *         entry main().
+ *
+ * @param  parameter is the arg of the thread.
  */
 void main_thread_entry(void *parameter)
 {
@@ -228,6 +230,8 @@ void rt_application_init(void)
 /**
  * @brief  This function will call all levels of initialization functions to complete
  *         the initialization of the system, and finally start the scheduler.
+ *
+ * @return Normally never returns. If 0 is returned, the scheduler failed.
  */
 int rtthread_startup(void)
 {

src/cpu.c

@@ -178,6 +178,8 @@ struct rt_cpu *rt_cpu_self(void)
 /**
  * @brief   This fucntion will return the cpu object corresponding to index.
  *
+ * @param   index is the index of target cpu object.
+ *
  * @return  Return a pointer to the cpu object corresponding to index.
  */
 struct rt_cpu *rt_cpu_index(int index)
@@ -242,6 +244,8 @@ RTM_EXPORT(rt_cpus_unlock);
  * This function is invoked by scheduler.
  * It will restore the lock state to whatever the thread's counter expects.
  * If target thread not locked the cpus then unlock the cpus lock.
+ *
+ * @param   thread is a pointer to the target thread.
  */
 void rt_cpus_lock_status_restore(struct rt_thread *thread)
 {

src/device.c

@@ -461,8 +461,8 @@ RTM_EXPORT(rt_device_set_tx_complete);
 /**
  * This function  bind drvier and device
  *
- * @param driver the pointer of driver structure
  * @param device the pointer of device structure
+ * @param driver the pointer of driver structure
  * @param node the pointer of fdt node structure
  *
  * @return the error code, RT_EOK on successfully.

src/kservice.c

@@ -1902,6 +1902,8 @@ const rt_uint8_t __lowest_bit_bitmap[] =
  * Bits are numbered starting at 1 (the least significant bit).  A return value of
  * zero from any of these functions means that the argument was zero.
  *
+ * @param value is the value to find the first bit set in.
+ *
  * @return return the index of the first bit set. If value is 0, then this function
  * shall return 0.
  */
@@ -1937,6 +1939,8 @@ const rt_uint8_t __lowest_bit_bitmap[] =
  * Bits are numbered starting at 1 (the least significant bit).  A return value of
  * zero from any of these functions means that the argument was zero.
  *
+ * @param value is the value to find the first bit set in.
+ *
  * @return Return the index of the first bit set. If value is 0, then this function
  *         shall return 0.
  */

src/scheduler_mp.c

@@ -239,6 +239,7 @@ void rt_system_scheduler_start(void)
 
 /**
  * @addtogroup Thread
+ * @cond
  */
 
 /**@{*/
@@ -754,3 +755,4 @@ rt_uint16_t rt_critical_level(void)
 RTM_EXPORT(rt_critical_level);
 
 /**@}*/
+/**@endcond*/

src/scheduler_up.c

@@ -212,6 +212,7 @@ void rt_system_scheduler_start(void)
 
 /**
  * @addtogroup Thread
+ * @cond
  */
 
 /**@{*/
@@ -500,3 +501,4 @@ rt_uint16_t rt_critical_level(void)
 RTM_EXPORT(rt_critical_level);
 
 /**@}*/
+/**@endcond*/