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 <[email protected]>

2 files changed, 8 insertions, 2 deletions

diff --git a/src/cpu_mp.c b/src/cpu_mp.c
index a10e35f479..0ef5a868a4 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 d1720c9459..b2531b0be4 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.
  *