[doxygen] add doxygen comment for blk.h #9947
Conversation
Signed-off-by: 1078249029 <[email protected]>
|
@1078249029 函数部分的 doxygen comment 建议还是放在 .c 文件部分，具体见：#9934 这个后面统一再整理。 |
目前rtthread的doxygen注释有的在.c有的在.h中，比较混乱。汪老师可以提个RFC，统一规划一下。可以列出参考案例，到时候大家也好统一遵守规则, 放到.c和.h本质上都可以，都不影响代码。 放到.c中方便开发者查看。 放.h中方便管理和整合doxygen需要的文件夹，这个对于后期使用lib和提供API接口也是方便的，而且目前大部分的嵌入式MCU平台都是放到.h中（比如zephyr，freertos, NXP，Nordic）。 根据我嵌入式多年经验，建议doxygen格式的放到.h中，如果觉得代码中需要直接看注释，可以在.c中拷贝一份注释的内容留给自己查看,参考NXP。 |
好的，我计划是等到 #9946 合入后就会开展这个 RFC 工作。定好规则后，大家改起来也快。 对于注释放在头文件和源文件中，其实都可以。我目前的想法是， 结构体，宏定义啥的应该还是在头文件中，区别主要是 API 函数。 我先解释一下我为什么希望函数的注释放在源文件中而不是头文件中，主要是发现当一个模块的 API extern 函数很多时，如果注释放在头文件中会导致头文件很长，可以想象一下，对于一个 API 很多的模块，注释有很多时，头文件中将充斥着大片的绿色注释，函数声明部分夹杂在中间很难区分，而且想要完整的了解这个模块导出了哪些extern 函数，需要把一个很长的文件滚动很长时间才能看个大概。特别是对于 RTT，以 include/rtthread.h 为例，大量的 API 都声明在这个头文件里，如果每个加上注释是一件很恐怖的事情啊。另外，注释放在 .c 中，对于开发人员来说看函数的实现也方便，我们代码都是开源的，直接去源文件看注释，可以方便和代码实现联合起来一起看。 但实际上根据 RTT 的实际情况，我觉得很可能最终的方案不会强制统一放在头文件或者源文件中，因为我也发现有大量的模块已经把函数注释写在头文件中了，譬如 driver 部分，譬如 所以我现在的想法可能会折中，但我觉得比较重要的是定一个编写 doxgen 的规则出来，一个编写 doxygen 的 guide 文档，作为 #9946 的补充。规则可以有一些灵活的选择，但是有规则总比没有好。 其实我们用了 doxygen，注释统一放哪里并不重要的，我们用 doxygen 的主要目的，应该是为了生成 html 吧，现在 github 的 io 已经可以自动产生网页，无论注释在哪个文件中最后其实我们推荐开发人员去看 html 体验会更好，我在 #9946 里把 markdown 的 user guide 文档和 API 集成起来，以后看 html 体验应该会更好。
这个我觉得不用担心，我觉得 doxygen 足够聪明，只要我们用正确 doxygen 的命令，其实放哪里都没有关系，目前我再 Doxyfile 中开启了 |
可以呀，可以尽快整理规则出来，有规则大家也好执行， |
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Signed-off-by: 1078249029 <[email protected]>
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Accroding to #9947 and #9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
Accroding to RT-Thread#9947 and RT-Thread#9424, adding doxygen comment for function in .c files and data structure, macro in .h file is a solution.For this pr, I encountered problem following situations. - rt_clk_unprepare function return value type is different from rt_clk_ops so I change type of rt_clk_unprepare and its dependencies. - clk_get function may be similar as rt_clk_unprepare but I'm not sure so not modify. - clk_release implements may be incomplete, so I just marked in comment. Signed-off-by: 1078249029 <[email protected]>
拉取/合并请求描述：(PR description)
[
为什么提交这份PR (why to submit this PR)
#9424
你的解决方案是什么 (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