RT-Thread / RT-Thread/rt-thread
[Feature] RTT doxygen 文档改进
Open
Doc
- Dominant language
- C
- Stars
- 12.2k
- Forks
- 5.4k
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 40
Description
NOTE:这是一个用于长期 Tracking Feature 的 issue,所以在相关工作完成之前,请不要关闭。
Describe problem solved by the proposed feature
需求来源:
- 见 #9871 中的 ”问题 1“
- 2025 RT-Thread 全球技术大会演讲:
B 站视频回放:RT-Thread 内核仓库文档改进工作介绍_汪辰,slides
这个 issue 用于搜集 RTT 代码仓库中和 doxygen 文档维护改进相关的 issue,相关工作可以分为下面几大部分:
-
(1)基础框架和支持工作
- #9880 resolved by #9946
- #9970 resolved by #9975
- #9989
- #9991
- #10001
- #10007
- #10015
- #10016
- #10026
- #10082
- #10183
- #10197
- #10408
-
(2)API 的 group 组织整理,缺的需要补上。(issue 还没有提,待定 TBD)
- #10336
-
(3)特定 group 的 API 的 doxygen 注释。依赖于 (1)和 (2)
- #9950
- #10006
- #9263
- #9424
- #10015
- #10058 pr 的标题迷惑,实际是针对 driver 的 audio 模块的文档优化
- #10066
- #10104
- 其他具体条目有待进一步收集,issue 待整理和提交。
- 看 https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-smart/introduction/rt-smart-lwp/rt-smart-lwp 中提到 “RT-Thread 用户态版本 API 和原系统 API 的差异" 的问题,是说 RTT 支持 smart 后,对于原先 RTT 提供的 API,用户态程序还可以有一部分可以直接调用,如果在 RTT 上有一部分可以直接调用,那怎么区分?用户编程时怎么知道哪些 API 是可以直接调用的?习惯上我理解用户态的程序,只能通过 system call 和内核交互的吧,直接调用内核提供的 api 感觉有点怪怪的。
-
(4)Markdown 文档中涉及 API 的描述部分应尽可能复用 source 源代码中的 doxygen comment 描述,避免在 markdown 文档中重复再写一份。这部分工作依赖于 (3)并且需要分解为小的 issue 来 track(TBD)。
-
(5)此外,我建议在 doxygen 整理这项工作开展的同时 (即 (2)和 (3)),我建议也同步开展 utest 的整理工作。具体来说,就是每梳理一个模块(对应 doxygen 中的一个 group),同时整理这个 group 对应的 utest。也就是说下面这两项工作会同步协调开展。有关 utest 的讨论,参考 #9775
-
(6) 其他相关改进
- #9994
- #10003
Describe your preferred solution
No response
Describe possible alternatives
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.