doxygen: fixed duplicated comments for scheduler APIs

Similar to PR #10674, `src/scheduler_mp.c` and
`src/scheduler_up.c` also have similar issues.

After investigation, we found: in commit 2c98ce4605
"[HUST CSE][document] Fix some comments, invalid
grouping commands and warnings in Doxygen." This patch
excluded `src/scheduler_mp.c` and `src/scheduler_up.c`
from the Doxygen build and include
`documentation/doxygen/thread.h` (the new file path
after adjustment is `documentation/0.doxygen/core/thread.h`),
placing the Doxygen comments for some functions in this file.

However, this approach has its problems:

- The comments in `documentation/0.doxygen/core/thread.h`
  are separated from the source code, making them
  difficult to maintain. This also results in the
  comments for the newly added functions in
  `src/scheduler_mp.c` and `src/scheduler_up.c` not
  being updated in a timely manner and failing to
  be compiled into Doxygen (becoming HTML).

- For the average programmer, it's unlikely that
  they'll consider the `documentation/0.doxygen/`
  directory for function declarations and comments,
  let alone the need to maintain the Doxygen comments
  in that directory. Currently, the header files under
  `documentation/0.doxygen/` should strictly be used
  only to define Doxygen groups and should not include
  Doxygen comments for the code itself. (Similar
  issues exist in documentation/0.doxygen/3.hardware.h
  and documentation/0.doxygen/core/systeminit.h, which
  require further cleanup.)

The solution is similar to PR #10674, where only MP
documentation is generated by default. For functions
defined in MP but not in UP, we use the "@note"
directive in the function's doxygen comment to indicate
whether the function is supported in both UP and MP,
or only in MP.

After implementing this solution, the file
`documentation/0.doxygen/core/thread.h` can be deleted.

Signed-off-by: Chen Wang <[email protected]>

2 files changed, 99 insertions, 42 deletions

diff --git a/src/scheduler_mp.c b/src/scheduler_mp.c
index 1ef452cab8..c0a546cf08 100644
--- a/src/scheduler_mp.c
+++ b/src/scheduler_mp.c
@@ -175,6 +175,14 @@ void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid))
 /**@}*/
 #endif /* RT_USING_HOOK */
 
+/**
+ * @addtogroup group_thread_management
+ *
+ * @cond DOXYGEN_SMP
+ *
+ * @{
+ */
+
 #if RT_THREAD_PRIORITY_MAX > 32
 
 rt_inline rt_base_t _get_global_highest_ready_prio(void)
@@ -400,6 +408,13 @@ static void _sched_remove_thread_locked(struct rt_thread *thread)
 /**
  * @brief Initialize the system scheduler.
  *
+ * @note This function must be called before any thread scheduling can occur.
+ *       It prepares the scheduler data structures for multi-core operation.
+ *
+ * @note This function has both MP version and UP version.
+ */
+/*
+ * Don't include below in doxygen document due to they are MP version only.
  * @details This function performs the following initialization tasks:
  *          - Initializes the global scheduler spinlock for multi-core synchronization.
  *          - Initializes the global priority table for saving ready threads of all priority levels.
@@ -409,9 +424,6 @@ static void _sched_remove_thread_locked(struct rt_thread *thread)
  *            * Initializes per-CPU ready tables (if priority > 32)
  *            * Initializes per-CPU spinlock (if RT_USING_SMART is defined)
  *          - Initializes the global ready priority group and tables (if priority > 32) as bitmaps for all priorities.
- *
- * @note This function must be called before any thread scheduling can occur.
- *       It prepares the scheduler data structures for multi-core operation.
  */
 void rt_system_scheduler_init(void)
 {
@@ -462,6 +474,14 @@ void rt_system_scheduler_init(void)
 /**
  * @brief Start the system scheduler and switch to the highest priority thread.
  *
+ * @note This function will not return after successful execution.
+ *       It performs the initial thread switch during system startup.
+ *       The scheduler must be initialized before calling this function.
+ *
+ * @note This function has both MP version and UP version.
+ */
+/*
+ * Don't include below in doxygen document due to they are MP version only.
  * @details This function performs the following operations:
  *          - Releases legacy CPU lock (if any)
  *          - Disables interrupts to ensure atomic operation
@@ -470,17 +490,13 @@ void rt_system_scheduler_init(void)
  *          - Removes the selected thread from ready queue
  *          - Assigns current CPU core to the selected thread
  *          - Performs context switch to the selected thread
- *
- * @note This function will not return after successful execution.
- *       It performs the initial thread switch during system startup.
- *       The scheduler must be initialized before calling this function.
  */
 void rt_system_scheduler_start(void)
 {
     struct rt_thread *to_thread;
     rt_ubase_t highest_ready_priority;
 
-    /**
+    /*
      * legacy rt_cpus_lock. some bsp codes still use it as for it's critical
      * region. Since scheduler is never touching this, here we just release it
      * on the entry.
@@ -490,7 +506,7 @@ void rt_system_scheduler_start(void)
     /* ISR will corrupt the coherency of running frame */
     rt_hw_local_irq_disable();
 
-    /**
+    /*
      * for the accessing of the scheduler context. Noted that we don't have
      * current_thread at this point
      */
@@ -520,20 +536,15 @@ void rt_system_scheduler_start(void)
 }
 
 /**
- * @addtogroup group_thread_management
- * @cond
- */
-
-/**@{*/
-
-/**
  * @brief This function will handle IPI interrupt and do a scheduling in system.
  *
- * @param vector is the number of IPI interrupt for system scheduling.
+ * This function should be invoke or register as ISR in BSP.
  *
- * @param param is not used, and can be set to RT_NULL.
+ * @param vector The number of IPI interrupt for system scheduling.
  *
- * @note this function should be invoke or register as ISR in BSP.
+ * @param param Not used, and can be set to RT_NULL.
+ *
+ * @note This function only has MP version.
  */
 void rt_scheduler_ipi_handler(int vector, void *param)
 {
@@ -543,9 +554,13 @@ void rt_scheduler_ipi_handler(int vector, void *param)
 /**
  * @brief Lock the system scheduler
  *
- * @param plvl pointer to the object where lock level stores to
+ * @param plvl Pointer to the object where lock level stores to
  *
- * @return rt_err_t RT_EOK
+ * @return rt_err_t
+ *         - RT_EOK on success
+ *         - -RT_EINVAL if plvl is NULL
+ *
+ * @note This function has both MP version and UP version.
  */
 rt_err_t rt_sched_lock(rt_sched_lock_level_t *plvl)
 {
@@ -560,12 +575,13 @@ rt_err_t rt_sched_lock(rt_sched_lock_level_t *plvl)
 }
 
 /**
- * @brief Unlock the system scheduler
- * @note this will not cause the scheduler to do a reschedule
+ * @brief Unlock the scheduler and restore the interrupt level
+ *
+ * @param level The interrupt level to restore (previously saved by rt_sched_lock)
  *
- * @param level the lock level of previous call to rt_sched_lock()
+ * @return rt_err_t Always returns RT_EOK
  *
- * @return rt_err_t RT_EOK
+ * @note This function has both MP version and UP version.
  */
 rt_err_t rt_sched_unlock(rt_sched_lock_level_t level)
 {
@@ -577,10 +593,12 @@ rt_err_t rt_sched_unlock(rt_sched_lock_level_t level)
 /**
  * @brief Check if the scheduler is currently locked
  *
+ * This function checks the scheduler lock status in a thread-safe manner
+ * by temporarily disabling interrupts to get consistent state.
+ *
  * @return rt_bool_t Returns RT_TRUE if scheduler is locked, RT_FALSE otherwise
  *
- * @note This function checks the scheduler lock status in a thread-safe manner
- *       by temporarily disabling interrupts to get consistent state.
+ * @note This function only has MP version.
  */
 rt_bool_t rt_sched_is_locked(void)
 {
@@ -797,6 +815,8 @@ static void _sched_thread_process_signal(struct rt_thread *current_thread)
  *
  * @note Must be called in pair with rt_sched_lock()
  *       May trigger context switch if conditions met
+ *
+ * @note This function has both MP version and UP version.
  */
 rt_err_t rt_sched_unlock_n_resched(rt_sched_lock_level_t level)
 {
@@ -884,6 +904,11 @@ rt_err_t rt_sched_unlock_n_resched(rt_sched_lock_level_t level)
  *        with the highest priority level in global ready queue or local ready queue,
  *        then switch to it.
  *
+ * @note This function has both MP version and UP version.
+ */
+
+/*
+ * NOTE: not in doxygen due to these info. are special for MP version
  * @details This function performs the following operations:
  *   - Disables interrupts to enter critical section
  *   - Gets current CPU and thread context
@@ -938,7 +963,7 @@ void rt_schedule(void)
         CLR_CRITICAL_SWITCH_FLAG(pcpu, current_thread);
         pcpu->irq_switch_flag = 0;
 
-        /**
+        /*
          * take the context lock before we do the real scheduling works. Context
          * lock will be released before returning from this _schedule_locked()
          */
@@ -985,6 +1010,8 @@ void rt_schedule(void)
  *   - Performs context switch to new thread if available
  *   - Handles cases where scheduler is locked or still in interrupt context
  *   - Processes pending signals before scheduling
+ *
+ * @note This function only has MP version.
  */
 void rt_scheduler_do_irq_switch(void *context)
 {
@@ -1062,10 +1089,12 @@ 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.
+ * @param thread The thread to be inserted.
  *
  * @note  Please do not invoke this function in user application.
  *        Caller must hold the scheduler lock
+ *
+ * @note This function has both MP version and UP version.
  */
 void rt_sched_insert_thread(struct rt_thread *thread)
 {
@@ -1079,9 +1108,11 @@ void rt_sched_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.
+ * @param thread The thread to be removed.
  *
  * @note  Please do not invoke this function in user application.
+ *
+ * @note This function has both MP version and UP version.
  */
 void rt_sched_remove_thread(struct rt_thread *thread)
 {
@@ -1107,6 +1138,8 @@ void rt_sched_remove_thread(struct rt_thread *thread)
  *   - Initializes priority bitmasks (handles >32 priorities if needed)
  *   - Sets initial time slice values
  *   - For SMP systems, initializes critical section nesting counter
+ *
+ * @note This function has both MP version and UP version.
  */
 void rt_sched_thread_init_priv(struct rt_thread *thread, rt_uint32_t tick, rt_uint8_t priority)
 {
@@ -1151,6 +1184,8 @@ void rt_sched_thread_init_priv(struct rt_thread *thread, rt_uint32_t tick, rt_ui
  *
  * @note This is a lockless operation as it's called during thread creation
  *       when no concurrent access is possible
+ *
+ * @note This function has both MP version and UP version.
  */
 void rt_sched_thread_startup(struct rt_thread *thread)
 {
@@ -1180,6 +1215,8 @@ void rt_sched_thread_startup(struct rt_thread *thread)
  * @note this operation is taken as an atomic operation of the update of SP.
  *       Since the local irq is disabled, it's okay to assume that the stack
  *       will not be modified meanwhile.
+ *
+ * @note This function only has MP version.
  */
 void rt_sched_post_ctx_switch(struct rt_thread *thread)
 {
@@ -1218,6 +1255,8 @@ static volatile int _critical_error_occurred = 0;
  *   - Always calls rt_exit_critical() to ensure critical section is exited
  *
  * @note This is primarily used for debugging critical section mismatches.
+ *
+ * @note This function has both MP version and UP version.
  */
 void rt_exit_critical_safe(rt_base_t critical_level)
 {
@@ -1251,6 +1290,8 @@ void rt_exit_critical_safe(rt_base_t critical_level)
  *
  * @details This is the non-debug version that simply calls rt_exit_critical().
  *          The critical_level parameter is ignored in this implementation.
+ *
+ * @note This function has both MP version and UP version.
  */
 void rt_exit_critical_safe(rt_base_t critical_level)
 {
@@ -1288,6 +1329,8 @@ RTM_EXPORT(rt_exit_critical_safe);
  *
  * @note Must be paired with rt_exit_critical()
  *       Can be nested, each call must have matching exit call
+ *
+ * @note This function has both MP version and UP version.
  */
 rt_base_t rt_enter_critical(void)
 {
@@ -1342,6 +1385,8 @@ RTM_EXPORT(rt_enter_critical);
  * @note Must be called in pair with rt_enter_critical()
  *       Handles both hardware-assisted and software thread context cases
  *       May trigger rescheduling if conditions met
+ *
+ * @note This function has both MP version and UP version.
  */
 void rt_exit_critical(void)
 {
@@ -1397,7 +1442,9 @@ RTM_EXPORT(rt_exit_critical);
 /**
  * @brief Get the scheduler lock level.
  *
- * @return the level of the scheduler lock. 0 means unlocked.
+ * @return The level of the scheduler lock. 0 means unlocked.
+ *
+ * @note This function has both MP version and UP version.
  */
 rt_uint16_t rt_critical_level(void)
 {
@@ -1447,6 +1494,9 @@ RTM_EXPORT(rt_critical_level);
  *
  * @note Caller must ensure scheduler is not locked before calling
  *       This function will acquire scheduler lock internally
+ *
+ * @note This function has both MP version and UP version, but UP version does
+ *       nothing and always returns -RT_EINVAL.
  */
 rt_err_t rt_sched_thread_bind_cpu(struct rt_thread *thread, int cpu)
 {
@@ -1531,5 +1581,8 @@ rt_err_t rt_sched_thread_bind_cpu(struct rt_thread *thread, int cpu)
     return RT_EOK;
 }
 
-/**@}*/
-/**@endcond*/
\ No newline at end of file
+/**
+ * @}
+ *
+ * @endcond
+ */
diff --git a/src/scheduler_up.c b/src/scheduler_up.c
index 5dedb33d36..8099d3d9f3 100644
--- a/src/scheduler_up.c
+++ b/src/scheduler_up.c
@@ -93,6 +93,14 @@ void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid))
 /**@}*/
 #endif /* RT_USING_HOOK */
 
+/**
+ * @addtogroup group_thread_management
+ *
+ * @cond
+ *
+ * @{
+ */
+
 static struct rt_thread* _scheduler_get_highest_priority_thread(rt_ubase_t *highest_prio)
 {
     struct rt_thread *highest_priority_thread;
@@ -257,13 +265,6 @@ void rt_system_scheduler_start(void)
 }
 
 /**
- * @addtogroup group_thread_management
- * @cond
- */
-
-/**@{*/
-
-/**
  * @brief Perform thread scheduling once. Select the highest priority thread and switch to it.
  *
  * @details This function:
@@ -719,5 +720,8 @@ rt_err_t rt_sched_thread_bind_cpu(struct rt_thread *thread, int cpu)
     return -RT_EINVAL;
 }
 
-/**@}*/
-/**@endcond*/
\ No newline at end of file
+/**
+ * @}
+ *
+ * @endcond
+ */