doxygen: fixed duplicated comments for scheduler APIs #10677
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Similar to PR RT-Thread#10674, `src/scheduler_mp.c` and `src/scheduler_up.c` also have similar issues. After investigation, we found: in commit 2c98ce4 "[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 RT-Thread#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>
github-actions
bot
added
Doc
📌 Code Review Assignment🏷️ Tag: documentationReviewers: @CXSforHPU @GorrayLi @lianux-mm @unicornx Changed Files (Click to expand)
🏷️ Tag: kernelReviewers: @GorrayLi @ReviewSun @hamburger-os @lianux-mm @wdfk-prog @xu18838022837 Changed Files (Click to expand)
📊 Current Review Status (Last Updated: 2025-09-09 14:25 CST)
📝 Review Instructions
|
unicornx
requested review from
Rbb666
and removed request for
Cathy-lulu and
mysterywolf
Rbb666
approved these changes
Sep 9, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
和 PR #10674 类似，src/scheduler_mp.c 和 src/scheduler_up.c 也有类似的问题。
经研究发现：commit 2c98ce4 "[HUST CSE][document] Fix some comments, invalid grouping commands and warnings in Doxygen." 曾经对这个问题做过修复。当时的解法是将
src/scheduler_mp.c和src/scheduler_up.c排除出 Doxygen 的构建，并引入documentation/doxygen/thread.h(现经调整后新的文件路径是documentation/0.doxygen/core/thread.h), 将一部分函数的 doxygen 注释放在这个文件中。但这么做存在问题，体现在：documentation/0.doxygen/core/thread.h这里的注释脱离了源码存在，很难维护，这也导致了src/scheduler_mp.c和src/scheduler_up.c中新增的其他函数的注释因为没有及时更新，也不能进入 Doxygen 编译（成为 html）documentation/0.doxygen/目录下看函数的声明和注释，更不太可能想到要去持续地维护整个目录下的 doxygen 注释。目前documentation/0.doxygen/下的 header 文件严格意义上应该只用于定义 doxygen 的 group，而不应该包括代码的 doxygen 注释。（类似的问题还有一些，譬如 documentation/0.doxygen/3.hardware.h 和 documentation/0.doxygen/core/systeminit.h， 有待进一步清理。）解决方案类似 PR #10674，默认只生成 MP 的文档。对于那些在 MP 中定义了的函数，而 UP 中没有定义的函数，我们会在函数的 doxygen 注释中采用 “@note” 命令说明该函数是否是 UP 和 MP 都支持还是只支持 MP。
采用以上解决方案后
documentation/0.doxygen/core/thread.h这个文件可以删除。