doxygen: fixed duplicated comments for cpu APIs #10674
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
Refer to the issue described in PR RT-Thread#10599. This was a temporary fix at that time. After further research, we discovered that this issue can be addressed using the "@cond" command supported by Doxygen. Since we currently do not intend to generate two sets of documentation for UP and MP when generating Doxygen documentation, the current solution is to generate only MP documentation by default. For functions defined in MP but not in UP, we will use the "@note" command in the function's Doxygen comment to indicate whether the function supports both UP and MP, or only MP. 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-08 15:25 CST)
📝 Review Instructions
|
unicornx
requested review from
Rbb666
and removed request for
Cathy-lulu and
mysterywolf
Contributor
|
lgtm |
Rbb666
approved these changes
Sep 8, 2025
unicornx
added a commit
to unicornx/rt-thread
that referenced
this pull request
Sep 9, 2025
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>
Rbb666
pushed a commit
that referenced
this pull request
Sep 9, 2025
Similar to PR #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 #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>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 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 #10599 描述的问题。当时只是一个临时的解决。
经研究后，发现可以使用 Doxygen 支持的 “@cond” 命令解决。
由于在目前生成 doxygen 文档时我们并不打算为 UP 和 MP 生成两套文档。所以目前的解决方案是，默认只生成 MP 的文档。对于那些在 MP 中定义了的函数，而 UP 中没有定义的函数，我们会在函数的 doxygen 注释中采用 “@note” 命令说明该函数是否是 UP 和 MP 都支持还是只支持 MP。
总之，目前这样改动后，
cpu_mp.c和cpu_up.c中的注释可以随意改动，互不影响，但 doxygen 创建文档时将以cpu_mp.c中的内容为准。考虑到 mp 应该兼容 up，所以这么做也是合理的。