From 2c98ce4605515910025212a85b2f776129a0981c Mon Sep 17 00:00:00 2001 From: Xu Biang Date: Sat, 15 Apr 2023 00:33:43 +0800 Subject: [PATCH] [HUST CSE][document] Fix some comments, invalid grouping commands and warnings in Doxygen. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将Doxygen输入文件（由Doxyfile中的INPUT定义）中的失效Doxygen分组指令（如/*@*/和/*@}*/）更改为有效的分组指令（如/**@*/和/**@}*/）；（此处只对INPUT中的文件做了修改，bsp目录下和libcpu目录下存在近万个失效的Doxygen分组指令，但由于不作为文档的输入文件且这些文件过于庞大老旧，没有对这些文件中的无效指令做修改） 将图片文件统一放入了images目录下； 修改了Doxyfile和部分Doxygen注释，使得Doxyfile能够定位到新的代码路径且不受重复实现的影响； 解决了一些注释中的参数名不匹配、参数多余/缺失等问题。 --- components/dfs/dfs_v1/src/dfs.c | 5 +- components/dfs/dfs_v1/src/dfs_file.c | 5 +- components/dfs/dfs_v1/src/dfs_fs.c | 4 +- components/dfs/dfs_v1/src/dfs_posix.c | 15 ++- components/dfs/dfs_v2/src/dfs.c | 5 +- components/dfs/dfs_v2/src/dfs_file.c | 5 +- components/dfs/dfs_v2/src/dfs_fs.c | 4 +- components/dfs/dfs_v2/src/dfs_posix.c | 15 ++- documentation/doxygen/Doxyfile | 12 +-- documentation/doxygen/hardware.h | 12 ++- documentation/doxygen/images/.gitkeep | 0 .../doxygen/{ => images}/Kernel_Object.png | Bin .../doxygen/{ => images}/System_Arch.png | Bin .../doxygen/{ => images}/Thread_Scheduler.png | Bin documentation/doxygen/{ => images}/dfs.png | Bin documentation/doxygen/{ => images}/finsh.png | Bin .../doxygen/{ => images}/rtthread_logo.png | Bin documentation/doxygen/kernel.h | 6 +- documentation/doxygen/systeminit.h | 16 +--- documentation/doxygen/thread.h | 89 ++++++++++++++++++ src/components.c | 4 + src/cpu.c | 4 + src/device.c | 2 +- src/kservice.c | 4 + src/scheduler_mp.c | 2 + src/scheduler_up.c | 2 + 26 files changed, 149 insertions(+), 62 deletions(-) delete mode 100644 documentation/doxygen/images/.gitkeep rename documentation/doxygen/{ => images}/Kernel_Object.png (100%) rename documentation/doxygen/{ => images}/System_Arch.png (100%) rename documentation/doxygen/{ => images}/Thread_Scheduler.png (100%) rename documentation/doxygen/{ => images}/dfs.png (100%) rename documentation/doxygen/{ => images}/finsh.png (100%) rename documentation/doxygen/{ => images}/rtthread_logo.png (100%) create mode 100644 documentation/doxygen/thread.h diff --git a/components/dfs/dfs_v1/src/dfs.c b/components/dfs/dfs_v1/src/dfs.c index cd68bf5828..ecab062d7a 100644 --- a/components/dfs/dfs_v1/src/dfs.c +++ b/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 -/*@}*/ +/**@}*/ diff --git a/components/dfs/dfs_v1/src/dfs_file.c b/components/dfs/dfs_v1/src/dfs_file.c index fe63fc987a..bc9ac3ccdc 100644 --- a/components/dfs/dfs_v1/src/dfs_file.c +++ b/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 */ -/* @} */ +/**@}*/ diff --git a/components/dfs/dfs_v1/src/dfs_fs.c b/components/dfs/dfs_v1/src/dfs_fs.c index e9be891068..4240736778 100644 --- a/components/dfs/dfs_v1/src/dfs_fs.c +++ b/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 -/* @} */ +/**@}*/ diff --git a/components/dfs/dfs_v1/src/dfs_posix.c b/components/dfs/dfs_v1/src/dfs_posix.c index 8c37c4afe1..fd6d56d0b5 100644 --- a/components/dfs/dfs_v1/src/dfs_posix.c +++ b/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); -/* @} */ +/**@}*/ diff --git a/components/dfs/dfs_v2/src/dfs.c b/components/dfs/dfs_v2/src/dfs.c index cd68bf5828..ecab062d7a 100644 --- a/components/dfs/dfs_v2/src/dfs.c +++ b/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 -/*@}*/ +/**@}*/ diff --git a/components/dfs/dfs_v2/src/dfs_file.c b/components/dfs/dfs_v2/src/dfs_file.c index 30dc0ac8bf..fd97976cf1 100644 --- a/components/dfs/dfs_v2/src/dfs_file.c +++ b/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 */ -/* @} */ +/**@}*/ diff --git a/components/dfs/dfs_v2/src/dfs_fs.c b/components/dfs/dfs_v2/src/dfs_fs.c index e9be891068..4240736778 100644 --- a/components/dfs/dfs_v2/src/dfs_fs.c +++ b/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 -/* @} */ +/**@}*/ diff --git a/components/dfs/dfs_v2/src/dfs_posix.c b/components/dfs/dfs_v2/src/dfs_posix.c index 8c37c4afe1..fd6d56d0b5 100644 --- a/components/dfs/dfs_v2/src/dfs_posix.c +++ b/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); -/* @} */ +/**@}*/ diff --git a/documentation/doxygen/Doxyfile b/documentation/doxygen/Doxyfile index 582ca8cd8f..03f04279fa 100644 --- a/documentation/doxygen/Doxyfile +++ b/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 diff --git a/documentation/doxygen/hardware.h b/documentation/doxygen/hardware.h index dd50f3abe8..bc05274998 100644 --- a/documentation/doxygen/hardware.h +++ b/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); -/*@}*/ +/**@}*/ diff --git a/documentation/doxygen/images/.gitkeep b/documentation/doxygen/images/.gitkeep deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/documentation/doxygen/Kernel_Object.png b/documentation/doxygen/images/Kernel_Object.png similarity index 100% rename from documentation/doxygen/Kernel_Object.png rename to documentation/doxygen/images/Kernel_Object.png diff --git a/documentation/doxygen/System_Arch.png b/documentation/doxygen/images/System_Arch.png similarity index 100% rename from documentation/doxygen/System_Arch.png rename to documentation/doxygen/images/System_Arch.png diff --git a/documentation/doxygen/Thread_Scheduler.png b/documentation/doxygen/images/Thread_Scheduler.png similarity index 100% rename from documentation/doxygen/Thread_Scheduler.png rename to documentation/doxygen/images/Thread_Scheduler.png diff --git a/documentation/doxygen/dfs.png b/documentation/doxygen/images/dfs.png similarity index 100% rename from documentation/doxygen/dfs.png rename to documentation/doxygen/images/dfs.png diff --git a/documentation/doxygen/finsh.png b/documentation/doxygen/images/finsh.png similarity index 100% rename from documentation/doxygen/finsh.png rename to documentation/doxygen/images/finsh.png diff --git a/documentation/doxygen/rtthread_logo.png b/documentation/doxygen/images/rtthread_logo.png similarity index 100% rename from documentation/doxygen/rtthread_logo.png rename to documentation/doxygen/images/rtthread_logo.png diff --git a/documentation/doxygen/kernel.h b/documentation/doxygen/kernel.h index 527ce835f0..ad6471db36 100644 --- a/documentation/doxygen/kernel.h +++ b/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 */ -/*@}*/ +/**@}*/ diff --git a/documentation/doxygen/systeminit.h b/documentation/doxygen/systeminit.h index c45eda4079..c320529303 100644 --- a/documentation/doxygen/systeminit.h +++ b/documentation/doxygen/systeminit.h @@ -7,7 +7,7 @@ * * @brief System initialization procedure. * - * When RT-Thread operating system starts up, the basic operating system facility + * When RT-Thread operating system starts up, the basic operating system facility * initialization routines must be invoked. * * The suggested initialization sequence is: @@ -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); diff --git a/documentation/doxygen/thread.h b/documentation/doxygen/thread.h new file mode 100644 index 0000000000..76ca383717 --- /dev/null +++ b/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); + +/**@}*/ diff --git a/src/components.c b/src/components.c index 809ca72a1d..97ace80990 100644 --- a/src/components.c +++ b/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) { diff --git a/src/cpu.c b/src/cpu.c index a89a0cca6a..8108d28da4 100644 --- a/src/cpu.c +++ b/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) { diff --git a/src/device.c b/src/device.c index 9665788c77..2bd2289e22 100644 --- a/src/device.c +++ b/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. diff --git a/src/kservice.c b/src/kservice.c index 1c1d8da848..1f06055ff1 100644 --- a/src/kservice.c +++ b/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. */ diff --git a/src/scheduler_mp.c b/src/scheduler_mp.c index 543d9abc6a..243cfd8dbe 100644 --- a/src/scheduler_mp.c +++ b/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*/ diff --git a/src/scheduler_up.c b/src/scheduler_up.c index 6c552c6a24..4c96089e34 100644 --- a/src/scheduler_up.c +++ b/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*/