doxygen: fix build error #10599
Merged
doxygen: fix build error #10599
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
fixed: b084503 "[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 b084503 change only modified the comments in src/cpu_up.c but not in src/cpu_mp.c, causing problems. Another drawback of the b084503 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 <unicorn_wang@outlook.com>
📌 Code Review Assignment🏷️ Tag: kernelReviewers: @GorrayLi @ReviewSun @hamburger-os @lianux-mm @wdfk-prog @xu18838022837 Changed Files (Click to expand)
📊 Current Review Status (Last Updated: 2025-08-11 22:17 CST)
📝 Review Instructions
|
10 tasks
meng-plus
approved these changes
Aug 11, 2025
Rbb666
approved these changes
Aug 12, 2025
unicornx
added a commit
to unicornx/rt-thread
that referenced
this pull request
Sep 8, 2025
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>
Rbb666
pushed a commit
that referenced
this pull request
Sep 8, 2025
Refer to the issue described in PR #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>
tomjielii
pushed a commit
to tomjielii/rt-thread
that referenced
this pull request
Sep 9, 2025
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>
tomjielii
pushed a commit
to tomjielii/rt-thread
that referenced
this pull request
Sep 11, 2025
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>
tomjielii
pushed a commit
to tomjielii/rt-thread
that referenced
this pull request
Sep 12, 2025
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>
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.
导致问题的 commit：b084503b6d "[kernel] add UP scheduler critical switch flag."
这个提交会导致 doxygen build 产生告警，导致失败：
原因分析：
src/cpu_up.c和src/cpu_mp.c定义了两套完全相同的函数，因为目前documentation/Doxyfile中的 INPUT 参数会将./src下的文件全部加入编译，这导致src/cpu_up.c和src/cpu_mp.c都会参与 doxygen 的编译，Doxygen 在处理它们的过程中如果发现这同名函数的 doxygen 注释不同的话会自动进行合并操作，导致形成多个 param 的告警。以前这两个文件中的 API 注释都是相同的，目前看上去如果注释相同，doxygen 在编译时的合并不会有问题，所以一直以来没有问题，但 b084503 的修改在修改注释时只改了
src/cpu_up.c中的rt_spin_unlock和rt_spin_unlock_irqrestore的注释，但没有改src/cpu_mp.c中对应函数的注释，从而导致问题。另外 b084503 中的修改还有一个不好的地方在于 Doxygen 的
@brief建议只写一行的，多行不是建议的写法。解决方案：
针对
@brief只写一行的要求，这个问题解决比较简单，将多加的内容作为@note列出即可。对于 warning 的解决：比较完美的解决方案暂时没有想好。一种可行的做法就是如果内核中这种一套 API 两套实现的情况，原则上 API 的 doxygen 注释应该只写一份就好了。所以一种可行的做法是只在一个文件，譬如
src/cpu_up.c中写 doxygen 注释，而另一个文件src/cpu_mp.c中的 doxygen 注释不写。还有一种解决方案是将 API 的注释写到
include/rtthread.h中去(只有一份)，但是目前include/rtthread.h这个文件本身已经很大了，如果再将注释加进去会更难看。最终我采用的是临时的解决方案，就是确保同一个 API 的 doxygen 注释在
src/cpu_up.c和src/cpu_mp.c中一样(这也是以前的做法)。这样 doxygen 编译不会有告警，而且其自动合并后只有一份在 html 中。更好的解决方案以后再考虑吧。