rt-thread
rt-thread copied to clipboard
[Feature] [doc] doxygen文档中缺少driver相关的doxygen
Describe problem solved by the proposed feature
https://github.com/RT-Thread/rt-thread/tree/master/components/drivers/include/drivers
目前driver相关的doxygen中缺少一些注释,希望能添加doxygen注释和对应的example,方便后续开发和维护
Describe your preferred solution
参考doxygen链接 https://supperthomas.github.io/RTT_doxygen_API/
Describe possible alternatives
No response
任务给我吧
- 本 issue #9424 涉及的改动比较多,所以针对特定的修改,需要将其分解,而这个 issue 来则用来 tracking 其他分解的 issue。
- 按照 device 的类型分别提 pr
- 涉及到 utest 单独提 pr
- utest 中,device/driver 依赖于具体的硬件,需要考虑一个方案,如何不依赖于硬件,打桩?模拟?模拟外设的 packge
- document 的改进方案
- 框架的整理,参考 rtems https://docs.rtems.org/docs/main/c-user/
- 如何避免 API 描述的冗余。利用 group 的链接 @ref group_ADC, markdown 中的涉及 API 的注释清理掉
- 我建议优先把 https://rt-thread.github.io/rt-thread/page_device_framework.html 相关的 API 的注释整理好,譬如
rt_device_find/rt_device_init这些。否则你会发现 markdown 中有很多地方都在反复的写rt_device_find的注释,譬如 <https://rt-thread.github.io/rt-thread/page_device_framework.html#autotoc_md254 和 https://rt-thread.github.io/rt-thread/page_device_audio.html#autotoc_md799>。而且如我们在 https://github.com/RT-Thread/rt-thread/issues/9824#issue-2756866875 的 (4) 中总结的那样,这些有关形如rt_device_find的注释应该直接引用源文件中的 doxgen 注释( markdown 中只要写成rt_device_find,生成的 html 里自动就会生成链接,可以试一下),无需在 markdown 文件中重复描述。 - [已放弃,社区维护人员建议不要做这个改进和优化] 例子的冗余,参考 #10003
Driver 相关 PR 总结:
- https://github.com/RT-Thread/rt-thread/pull/10058