[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能够定位到新的代码路径且不受重复实现的影响;
解决了一些注释中的参数名不匹配、参数多余/缺失等问题。
This commit is contained in:
Xu Biang 2023-04-15 00:33:43 +08:00 committed by GitHub
parent 4157a2802b
commit 2c98ce4605
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
26 changed files with 149 additions and 62 deletions

View File

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

View File

@ -89,10 +89,9 @@ static struct dfs_vnode *dfs_vnode_find(const char *path, rt_list_t **hash_head)
/** /**
* @addtogroup FileApi * @addtogroup FileApi
* @{
*/ */
/*@{*/
/** /**
* This function will return whether this file has been opend. * 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 /* DFS_USING_POSIX */
#endif /* RT_USING_FINSH */ #endif /* RT_USING_FINSH */
/* @} */ /**@}*/

View File

@ -18,8 +18,8 @@
/** /**
* @addtogroup FsApi * @addtogroup FsApi
* @{
*/ */
/*@{*/
/** /**
* this function will register a file system instance to device file system. * 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); FINSH_FUNCTION_EXPORT(df, get disk free);
#endif #endif
/* @} */ /**@}*/

View File

@ -20,10 +20,9 @@
/** /**
* @addtogroup FsPosixApi * @addtogroup FsPosixApi
* @{
*/ */
/*@{*/
/** /**
* this function is a POSIX compliant version, which will open a file and * this function is a POSIX compliant version, which will open a file and
* return a file descriptor according specified flags. * 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 * this function is a POSIX compliant version, which will rename old file name
* to new file name. * to new file name.
* *
* @param old the old file name. * @param old_file the old file name.
* @param new the new file name. * @param new_file the new file name.
* *
* @return 0 on successful, -1 on failed. * @return 0 on successful, -1 on failed.
* *
@ -392,7 +391,7 @@ RTM_EXPORT(fsync);
* *
* @param fildes the file description * @param fildes the file description
* @param cmd the specified command * @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. * specific device to perform the requested function.
* *
* @return 0 on successful completion. Otherwise, -1 shall be returned and errno * @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 fildes the file description
* @param cmd the specified command * @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. * specific device to perform the requested function.
* *
* @return 0 on successful completion. Otherwise, -1 shall be returned and errno * @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. * working directory.
* *
* @param buf the current directory. * @param buf the current directory.
*
* @return null.
*/ */
void setcwd(char *buf) void setcwd(char *buf)
{ {
@ -979,4 +976,4 @@ char *getcwd(char *buf, size_t size)
} }
RTM_EXPORT(getcwd); RTM_EXPORT(getcwd);
/* @} */ /**@}*/

View File

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

View File

@ -89,10 +89,9 @@ static struct dfs_vnode *dfs_vnode_find(const char *path, rt_list_t **hash_head)
/** /**
* @addtogroup FileApi * @addtogroup FileApi
* @{
*/ */
/*@{*/
/** /**
* This function will return whether this file has been opend. * 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 /* DFS_USING_POSIX */
#endif /* RT_USING_FINSH */ #endif /* RT_USING_FINSH */
/* @} */ /**@}*/

View File

@ -18,8 +18,8 @@
/** /**
* @addtogroup FsApi * @addtogroup FsApi
* @{
*/ */
/*@{*/
/** /**
* this function will register a file system instance to device file system. * 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); FINSH_FUNCTION_EXPORT(df, get disk free);
#endif #endif
/* @} */ /**@}*/

View File

@ -20,10 +20,9 @@
/** /**
* @addtogroup FsPosixApi * @addtogroup FsPosixApi
* @{
*/ */
/*@{*/
/** /**
* this function is a POSIX compliant version, which will open a file and * this function is a POSIX compliant version, which will open a file and
* return a file descriptor according specified flags. * 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 * this function is a POSIX compliant version, which will rename old file name
* to new file name. * to new file name.
* *
* @param old the old file name. * @param old_file the old file name.
* @param new the new file name. * @param new_file the new file name.
* *
* @return 0 on successful, -1 on failed. * @return 0 on successful, -1 on failed.
* *
@ -392,7 +391,7 @@ RTM_EXPORT(fsync);
* *
* @param fildes the file description * @param fildes the file description
* @param cmd the specified command * @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. * specific device to perform the requested function.
* *
* @return 0 on successful completion. Otherwise, -1 shall be returned and errno * @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 fildes the file description
* @param cmd the specified command * @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. * specific device to perform the requested function.
* *
* @return 0 on successful completion. Otherwise, -1 shall be returned and errno * @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. * working directory.
* *
* @param buf the current directory. * @param buf the current directory.
*
* @return null.
*/ */
void setcwd(char *buf) void setcwd(char *buf)
{ {
@ -979,4 +976,4 @@ char *getcwd(char *buf, size_t size)
} }
RTM_EXPORT(getcwd); RTM_EXPORT(getcwd);
/* @} */ /**@}*/

View File

@ -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 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory. # 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 # 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 # 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. # brief descriptions will be completely suppressed.
# The default value is: YES. # The default value is: YES.
REPEAT_BRIEF = NO REPEAT_BRIEF = YES
# This tag implements a quasi-intelligent brief description abbreviator that is # 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 # 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. # description.
# The default value is: NO. # 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 # 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 # inherited members of a class in the documentation of that class as if those
@ -910,8 +910,8 @@ INPUT = ../../src \
../../include \ ../../include \
. \ . \
../../components/finsh \ ../../components/finsh \
../../components/dfs/src \ ../../components/dfs/dfs_v2/src \
../../components/dfs/include ../../components/dfs/dfs_v2/include
# This tag can be used to specify the character encoding of the source files # 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 # 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 # that contain images that are to be included in the documentation (see the
# \image command). # \image command).
IMAGE_PATH = ../doxygen IMAGE_PATH = ./images
# The INPUT_FILTER tag can be used to specify a program that doxygen should # 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 # invoke to filter for each input file. Doxygen will invoke the filter program

View File

@ -19,14 +19,14 @@
/** /**
* @addtogroup bsp * @addtogroup bsp
* @{
*/ */
/*@{*/
/** /**
* This function will return current system interrupt status and disable system * This function will return current system interrupt status and disable system
* interrupt. * interrupt.
* *
* @return the current system interrupt status * @return the current system interrupt status.
*/ */
rt_base_t rt_hw_interrupt_disable(void); 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 * This function will set the specified interrupt status, which shall saved by
* rt_hw_intterrupt_disable function. If the saved interrupt status is interrupt * rt_hw_intterrupt_disable function. If the saved interrupt status is interrupt
* opened, this function will open system interrupt status. * 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); void rt_hw_interrupt_enable(rt_base_t level);
@ -82,4 +84,4 @@ void rt_hw_cpu_reset(void);
*/ */
void rt_hw_cpu_shutdown(void); void rt_hw_cpu_shutdown(void);
/*@}*/ /**@}*/

View File

Before

Width:  |  Height:  |  Size: 9.9 KiB

After

Width:  |  Height:  |  Size: 9.9 KiB

View File

Before

Width:  |  Height:  |  Size: 70 KiB

After

Width:  |  Height:  |  Size: 70 KiB

View File

Before

Width:  |  Height:  |  Size: 8.5 KiB

After

Width:  |  Height:  |  Size: 8.5 KiB

View File

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

View File

Before

Width:  |  Height:  |  Size: 7.1 KiB

After

Width:  |  Height:  |  Size: 7.1 KiB

View File

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 24 KiB

View File

@ -16,8 +16,8 @@
/** /**
* @addtogroup Kernel * @addtogroup Kernel
* @{
*/ */
/*@{*/
/** /**
* @defgroup Thread Thread Management * @defgroup Thread Thread Management
@ -41,7 +41,7 @@
/** /**
* @defgroup Clock Clock and Timer Management * @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. * 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 * bad things happen, the current thread's errno will be set. see @ref _rt_errno
*/ */
/*@}*/ /**@}*/

View File

@ -55,19 +55,9 @@
* has not started. User can allocate memory, create thread, semaphore etc. However, * has not started. User can allocate memory, create thread, semaphore etc. However,
* user shall not suspend 'current' thread. * user shall not suspend 'current' thread.
*/ */
void rt_application_init() void rt_application_init();
{
}
/** /**
* @ingroup SystemInit * @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);
{
}

View File

@ -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);
/**@}*/

View File

@ -174,6 +174,8 @@ struct rt_thread main_thread;
* @brief The system main thread. In this thread will call the rt_components_init() * @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 * for initialization of RT-Thread Components and call the user's programming
* entry main(). * entry main().
*
* @param parameter is the arg of the thread.
*/ */
void main_thread_entry(void *parameter) 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 * @brief This function will call all levels of initialization functions to complete
* the initialization of the system, and finally start the scheduler. * 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) int rtthread_startup(void)
{ {

View File

@ -178,6 +178,8 @@ struct rt_cpu *rt_cpu_self(void)
/** /**
* @brief This fucntion will return the cpu object corresponding to index. * @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. * @return Return a pointer to the cpu object corresponding to index.
*/ */
struct rt_cpu *rt_cpu_index(int index) struct rt_cpu *rt_cpu_index(int index)
@ -242,6 +244,8 @@ RTM_EXPORT(rt_cpus_unlock);
* This function is invoked by scheduler. * This function is invoked by scheduler.
* It will restore the lock state to whatever the thread's counter expects. * 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. * 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) void rt_cpus_lock_status_restore(struct rt_thread *thread)
{ {

View File

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

View File

@ -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 * 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. * 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 * @return return the index of the first bit set. If value is 0, then this function
* shall return 0. * 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 * 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. * 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 * @return Return the index of the first bit set. If value is 0, then this function
* shall return 0. * shall return 0.
*/ */

View File

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

View File

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