rt-thread [Feature] RTT doxygen 文档改进

NOTE：这是一个用于长期 Tracking Feature 的 issue，所以在相关工作完成之前，请不要关闭。

Describe problem solved by the proposed feature

需求来源：

见 #9871 中的 ”问题 1“

这个 issue 用于搜集 RTT 代码仓库中和 doxygen 文档维护改进相关的 issue，相关工作可以分为下面几大部分：

（1）基础框架和支持工作
- #9880 resolved by #9946
- #9970 resolved by #9975
- #9989
- #9991
- #10001
- #10007
- #10015
- #10016
- #10026
- #10082
- #10183
- #10197
（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

Dec 23 '24 23:12 unicornx

有关文档改进的工作我也很有兴趣，希望能在相关方面做些工作，推进一下。

Dec 24 '24 00:12 unicornx

文档中心

Dec 24 '24 01:12 BernardXiong

英文documentation的部署是在这里： https://www.rt-thread.io/document/site/

不清楚是否是机器人自动化部署的了，可能不是。

Dec 24 '24 01:12 BernardXiong

#9424

这个doxygen还有很多未更新的地方，汪老师可以PR维护一下。

Dec 24 '24 01:12 supperthomas

[Feature] [doc] doxygen文档中缺少driver相关的doxygen #9424

这个doxygen还有很多未更新的地方，汪老师可以PR维护一下。

谢谢补充，我更新到 issue 的问题 2 中了

Dec 24 '24 07:12 unicornx

Modules 的层次结构设计

- Basic Definitions
- Device Virtual File System
- finsh shell
- Hardware Related Package
- RT-Thread Kernel API
  - Thread Management
  - Clock and Timer Management
  - Kernel Object Management
  - Inter-Thread Communication
    - Semaphore
    - Mutex
    - Event
    - Mailbox
    - Messagequeue
  - Signal
  - Memory Management
  - Device System
  - Runtime Trace and Record
  - Other useful kernel service
  - Error Code
- Application Module
- System Initialization
- RTTHREAD Driver
  - ADC
  - DAC
  - ...

是否可以和 documentation 下的文档结合起来，结构的安排尽量和其对齐。

就是有没有可能将下面两个网站的内容统一起来？

https://www.rt-thread.io/document/site/
https://supperthomas.github.io/RTT_doxygen_API/

Dec 27 '24 08:12 unicornx

@supperthomas 这个 issue 列举了很多其他的问题，不是单个 #9859 就完全解决的，所以重新打开

Jan 03 '25 08:01 unicornx

[Feature] [doc] doxygen文档中缺少driver相关的doxygen #9424

这个doxygen还有很多未更新的地方，汪老师可以PR维护一下。

请问这个还需要补充doxygen么？我看到熊大在 https://github.com/RT-Thread/rt-thread/pull/9924#issuecomment-2599753468 说最好先梳理lwp模块，之后再补充doxygen注释。driver是否也有类似的问题？

Jan 19 '25 04:01 1078249029

http://rt-thread.github.io/rt-thread/group___drivers.html

我觉得这部分应该还是不是很完善的。

参考下面链接中的文件

https://github.com/RT-Thread/rt-thread/tree/master/components/drivers https://github.com/RT-Thread/rt-thread/tree/master/components/drivers/include/drivers

Jan 19 '25 07:01 supperthomas

以下几部分的文档可以稍微暂缓些的，因为这块的代码大概率是需要进行梳理，甚至重构：

components/lwp的代码，即smart的代码，整体是相对混乱的；
- vdso需要加入多架构的设计；
components/drivers/hwtimer、components/drivers/ktime、components/drivers/cputime的代码，各种time/timer，缺乏一个完整的设计；

Jan 30 '25 09:01 BernardXiong

https://jothepro.github.io/doxygen-awesome-css/ 这个doxygen挺漂亮的。

Feb 21 '25 01:02 supperthomas

看到一个中英文的readthedoc，可以参考一下。

https://github.com/hpmicro/hpm_sdk/tree/main/docs

英文 https://hpm-sdk.readthedocs.io/en/latest/ 中文 https://hpm-sdk.readthedocs.io/zh-cn/latest/

仅供参考，没有其他建议。

Apr 01 '25 12:04 supperthomas

rt-thread rt-thread copied to clipboard

[Feature] RTT doxygen 文档改进

Describe problem solved by the proposed feature

Describe your preferred solution

Describe possible alternatives

rt-thread
rt-thread copied to clipboard