Repository navigation
docs: describe where a macro comment goes - #11973
Conversation
Closes RT-Thread#10097. The coding style only said that comments go above or to the right of the code, without saying which applies to a macro. The repository already follows a consistent rule, it just was not written down: - 135 macro comments in include/ use a trailing /**< - a further set of function-like macros use a /** block above the definition with @def The rule is about how much explanation the macro needs, not about line length. A single line goes trailing; a paragraph goes above. That distinction matters because the column-aligned groups of constant macros routinely exceed 80 columns once the comment is appended - 87 of those 135 lines (64%) are longer than 80 columns, and shortening them would break the alignment that makes them readable. Both language versions get the same section, with the real examples from include/klibc/kerrno.h and include/rtdef.h, plus a note that with MACRO_EXPANSION enabled a trailing /**< follows the expansion site while a block comment stays with the definition - which is why frequently expanded macros should use the block form.
📌 Code Review Assignment🏷️ Tag: documentationReviewers: @CXSforHPU @GorrayLi @lianux-mm Changed Files (Click to expand)
📊 Current Review Status (Last Updated: 2026-11-02 16:06 CST)
📝 Review Instructions
|
|
👋 感谢您对 RT-Thread 的贡献！Thank you for your contribution to RT-Thread! 为确保代码符合 RT-Thread 的编码规范，请在你的仓库中执行以下步骤运行代码格式化工作流（如果格式化CI运行失败）。 🛠 操作步骤 | Steps
完成后，提交将自动更新至 如有问题欢迎联系我们，再次感谢您的贡献！💐 |
拉取/合并请求描述：(PR description)
[
为什么提交这份PR (why to submit this PR)
闭合 #10097。
现有规范只说了"语句注释只能写在上方或右方"（
coding_style_cn.md:116），没有说明宏该选哪一种、依据是什么，于是同一份代码里两种写法并存，新人无从判断。先查了仓库现状，规则其实是自洽的，只是一直没写下来：
include/下 135 处宏注释用行尾/**<@def你的解决方案是什么 (what is your solution)
在中英文两份
coding_style的第 8 节各补一节「宏注释」，给出判断标准与真实示例。判断依据是"需要多少说明"，不是行长——这一点我一开始写错了，查了数据才改过来：
统计
include/下 135 处行尾宏注释，其中 87 处（64.4%）超过 80 列，例如kerrno.h:24是 95 列。也就是说成组的常量宏是故意保持列对齐、接受超长的；如果按"超 80 列就移到上方"来写，会和现有大半个代码库冲突。所以最终写的是：
@def（带参数的宏，要描述入参/展开结果/使用限制）两份文档都用了仓库里真实存在的例子（
include/klibc/kerrno.h:23-25的错误码组、include/rtdef.h:248-257的RT_ALIGN），不是编的示例。另外补了一条实践上的差别：开启
MACRO_EXPANSION后，行尾/**<是挂在宏展开点上的，同一宏多处展开时注释位置可能出乎意料；上方块注释始终绑定定义处。因此频繁展开的宏优先用上方块注释。请提供验证的bsp和config (provide the config and bsp)
纯文档改动，不涉及编译。文中所有示例均逐字核对过源文件：
include/klibc/kerrno.h:23-25—— 三行错误码，行尾/**<include/rtdef.h:248-257——RT_ALIGN的/**+@def块，该行 81 列]
当前拉取/合并请求的状态 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