[Feature] RTT doxygen 文档改进

[unicornx]

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

Describe problem solved by the proposed feature

需求来源：

• 见 [Feature] RTT 文档优化 #9871 中的 ”问题 1“

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

• （1）基础框架和支持工作

  • [Feature] 初始的统一 doxgen 框架 #9880 resolved by doxygen: create framework to unify markdown and source code part #9946
  • [Feature] provde guide on how to add doxygen style comment for API #9970 resolved by doxygen: add documentation for doxygen #9975
  • doxygen: add prefix for page name #9989
  • doxygen: add prefix for groups #9991
  • [doc]Add recommanded script and extension for writing doxygen comments on … #10001
  • doxygen: More strict checks on build results #10007
  • doxygen: Improve the text description of the introduction section #10015
  • doxygen: support running from the root directory #10016
  • doxygen: reorganize directory structure #10026
  • doxygen: group examples in subpages #10082
  • doxygen: cleanup and re-org files #10183
  • doxygen: re-org module groups #10197

• （2）API 的 group 组织整理，缺的需要补上。（issue 还没有提，待定 TBD）

  • Doxygen: move device/driver under to components #10336

• （3）特定 group 的 API 的 doxygen 注释。依赖于 （1）和 （2）

  • [doxygen] add doxygen comment for clk.c and clk.h #9950
  • doxygen: finsh: Normalize macro definitions #10006
  • [Feature] lwp, dm 等组件需要补充 doxygen 注释 | Add Doxygen Comments for Components #9263
  • [Feature] [doc] doxygen文档中缺少driver相关的doxygen #9424
  • doxygen: Improve the text description of the introduction section #10015
  • [RFC][doxygen]Doxygen comment standard processing #10058 pr 的标题迷惑，实际是针对 driver 的 audio 模块的文档优化
  • doxygen: improve doc for kernel basics section #10066
  • doxygen: update doc for kenrel object model #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 的讨论，参考 [Feature] 改进自动化测试以及 ci 看护 #9775

• (6) 其他相关改进

  • [Feature] 建立一种机制，能否方便地获取两个特定版本之间内核 API 的 diff 列表 #9994
  • [Bug] components/drivers/ 中的 examples 和 documentation 中的 example 重复了 #10003

Describe your preferred solution

No response

Describe possible alternatives

No response

[unicornx]

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

[BernardXiong]

文档中心

[BernardXiong]

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

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

[supperthomas]

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

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

[unicornx]

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

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

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

[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/

[unicornx]

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