RT-Thread / RT-Thread/rt-thread

[Feature] RTT doxygen 文档改进

Open
#9,824 12 comments 0 reactions 1 assignee View on GitHub

@unicornx is already working on this.

Since Dec 23, 2024.

  • #9859 by @supperthomas — merged
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

需求来源:

这个 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.