mirror of
https://github.com/RT-Thread/rt-thread.git
synced 2025-10-17 16:32:14 +08:00
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 <unicorn_wang@outlook.com>
This commit is contained in:
@@ -1,89 +0,0 @@
|
||||
/*
|
||||
* This file is only used for doxygen document generation.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @addtogroup group_thread_management
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @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);
|
||||
|
||||
/**@}*/
|
Reference in New Issue
Block a user