From c82e66716ac356e8ba65b3e1cd17f1f5375deda7 Mon Sep 17 00:00:00 2001 From: Chen Wang Date: Mon, 11 Aug 2025 21:52:10 +0800 Subject: [PATCH] doxygen: fix build error fixed: b084503b6d "[kernel] add UP scheduler critical switch flag." After this commit, doxygen build with warning: include/rtthread.h:658: warning: argument 'lock' from the argument list of rt_spin_unlock has multiple @param documentation sections include/rtthread.h:660: warning: argument 'lock' from the argument list of rt_spin_unlock_irqrestore has multiple @param documentation sections include/rtthread.h:660: warning: argument 'level' from the argument list of rt_spin_unlock_irqrestore has multiple @param documentation sections Rootcasue analysis: src/cpu_up.c and src/cpu_mp.c define two identical functions. Because the INPUT parameter in the documentation/Doxyfile currently compiles all source files under ./src, i.e both of them, Doxygen automatically merges the Doxygen comments for identically named functions if it finds the content of doxygen comments different, resulting in multiple @param. Previously, the API comments in both files were identical, so there was no problem. However, the b084503b6d change only modified the comments in src/cpu_up.c but not in src/cpu_mp.c, causing problems. Another drawback of the b084503b6d change is that Doxygen recommends a single line for the @brief; multiple lines are not recommended. Solution: Given the requirement for a single line for the @brief, this issue is relatively simple to resolve: simply list the extra content as @note. Regarding the warning: A perfect solution has not yet been found. One possible approach is to write a single Doxygen comment for a kernel API with two implementations. This approach involves writing Doxygen comments in only one file, such as src/cpu_up.c , while omitting them in src/cpu_mp.c . Another solution is to add API comments to include/rtthread.h , but the RT-Thread include/rtthread.h file is already quite large, and adding comments there would be even more cumbersome. A temporary solution currently in use is to ensure that the Doxygen comments for the same API are identical in both src/cpu_up.c and src/cpu_mp.c . This ensures that Doxygen compilation does not generate warnings, and the files are automatically merged into a single file in the HTML document. Signed-off-by: Chen Wang --- src/cpu_mp.c | 4 ++++ src/cpu_up.c | 6 ++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/src/cpu_mp.c b/src/cpu_mp.c index a10e35f479c..0ef5a868a41 100644 --- a/src/cpu_mp.c +++ b/src/cpu_mp.c @@ -59,6 +59,8 @@ RTM_EXPORT(rt_spin_lock) /** * @brief This function will unlock the spinlock, will unlock the thread scheduler. * + * @note If the scheduling function is called before unlocking, it will be scheduled in this function. + * * @param lock is a pointer to the spinlock. */ void rt_spin_unlock(struct rt_spinlock *lock) @@ -95,6 +97,8 @@ RTM_EXPORT(rt_spin_lock_irqsave) /** * @brief This function will unlock the spinlock and then restore current cpu interrupt status, will unlock the thread scheduler. * + * @note If the scheduling function is called before unlocking, it will be scheduled in this function. + * * @param lock is a pointer to the spinlock. * * @param level is interrupt status returned by rt_spin_lock_irqsave(). diff --git a/src/cpu_up.c b/src/cpu_up.c index d1720c94596..b2531b0be44 100644 --- a/src/cpu_up.c +++ b/src/cpu_up.c @@ -40,7 +40,8 @@ void rt_spin_lock(struct rt_spinlock *lock) /** * @brief This function will unlock the spinlock, will unlock the thread scheduler. - * If the scheduling function is called before unlocking, it will be scheduled in this function. + * + * @note If the scheduling function is called before unlocking, it will be scheduled in this function. * * @param lock is a pointer to the spinlock. */ @@ -73,7 +74,8 @@ rt_base_t rt_spin_lock_irqsave(struct rt_spinlock *lock) /** * @brief This function will unlock the spinlock and then restore current cpu interrupt status, will unlock the thread scheduler. - * If the scheduling function is called before unlocking, it will be scheduled in this function. + * + * @note If the scheduling function is called before unlocking, it will be scheduled in this function. * * @param lock is a pointer to the spinlock. *