doxygen: add documentation for doxygen #9975
Conversation
unicornx
force-pushed
the
dev-9970-doxygen-guide
branch
from
25ab79e to
2b6abda
Compare
|
doxygen.yml的ci相关的路径加一下，触发doxygen的ci rt-thread/.github/workflows/doxygen.yml Lines 6 to 26 in d3d33ff |
unicornx
force-pushed
the
dev-9970-doxygen-guide
branch
from
2b6abda to
2ce7c1d
Compare
Done, path 信息保持和 documentation/Doxyfile 的 INPUT 值同步了 |
unicornx
force-pushed
the
dev-9970-doxygen-guide
branch
from
2ce7c1d to
8442aa6
Compare
| /** | ||
| * @page page_howto_function How to write doxygen documentation for function. | ||
| * | ||
| * Function comments can be placed in the header file (before the |
There was a problem hiding this comment.
请问这里所说的注释指的是非doxygen注释么？doxygen注释统一放在c文件中吧？
There was a problem hiding this comment.
"comments" 指的都是符合 doxygen 语法的注释，对于函数(function), doxygen 注释可以放在头文件中也可以放在源文件中。
There was a problem hiding this comment.
下面不是推荐了函数注释要放在源文件中么？为什么这里还说可以放在头文件里？头文件只放数据结构和宏的注释吧？
There was a problem hiding this comment.
下面不是推荐了函数注释要放在源文件中么？为什么这里还说可以放在头文件里？头文件只放数据结构和宏的注释吧？
不矛盾啊，你也get 了这是 ”推荐“，本身不强制，因为现在已有很多模块的函数注释已经放在头文件中，我觉得也没有必要再整改一遍了吧，所以下面
So, it is strongly recommended to put comments in the source file when writing new functions or annotating functions.
这句话是有前提条件的：翻译过来是：
因此，强烈建议在编写新函数或注释函数时在源文件中添加注释。
所以是对 新写的 注释我们 强烈建议。已经存在的就尽量保持现状好了，除非出现我列举的因为头文件中 API 太多，导致注释写在头文件中不方便查看的原因出现，我们再去整改。
p.s. 这个 PR 本身所有的内容也就是一个指导规范（Guide），尽量统一大家思路而已，代码规范都很难 100% 统一，何况文档格式？所以我也这是说 recommended， 没有用 ”must“ :)
| * define a group anywhere, not necessarily in the same file as the members | ||
| * of the group. Generally, we define a group in a header file. | ||
| * | ||
| * To make an entity (structure, function etc. or another group) a menber of |
There was a problem hiding this comment.
是拼写错误么？
“menber” 应该是 “member", I will fix it. Thanks.
Documentation is provided to clarify how to write doxygen documentation for RT-Thread. This document is also integrated as part of RT-Thread doxygen documentation. An example is also provided. The original README.md is removed and integrated into this document. Updated github actions for doxygen too. Signed-off-by: Chen Wang <[email protected]>
unicornx
force-pushed
the
dev-9970-doxygen-guide
branch
from
8442aa6 to
74396b7
Compare
Fixed #9970
如果要查看最终的效果，可以参考修改后的 documentation/0.doxygen/INDEX.md 中 ubuntu 的环境编译方式，在本地查看修改效果。新建的具体页面 url 是：http://localhost:8000/howto_doxygen.html
Documentation is provided to clarify how to write
doxygen documentation for RT-Thread. This document is also integrated as part of RT-Thread doxygen
documentation.
An example is also provided.
The original README.md is removed and integrated into this document.
拉取/合并请求描述：(PR description)
[
为什么提交这份PR (why to submit this PR)
你的解决方案是什么 (what is your solution)
请提供验证的bsp和config (provide the config and bsp)
]
当前拉取/合并请求的状态 Intent for your PR
必须选择一项 Choose one (Mandatory):
代码质量 Code Quality：
我在这个拉取/合并请求中已经考虑了 As part of this pull request, I've considered the following:
#if 0代码，不包含已经被注释了的代码 All redundant code is removed and cleaned up