docs: describe where a macro comment goes

Closes #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.
This commit is contained in:
Yunlk authored and Rbb666 committed 2026-11-03 09:48:31 +08:00
1 parent 9e29e3246b
commit e0aa4cecaf
2 files changed
+72

No files matched your search

@@ -119,6 +119,38 @@ int rt_hw_spi_init(void)
/* 你的英文注释 */
```
**宏注释**:
宏的注释和语句注释一样,可以写在宏的**右方**或**上方**。选择哪一种,主要看这个宏需要多少说明,其次才是行长。
简单常量宏用行尾的 `/**<`,注释与宏同行,便于连续扫读一整组取值(`include/klibc/kerrno.h` 与 `include/rtdef.h` 里的错误码就是这样组织的):
```c
#define RT_EOK 0 /**< There is no error */
#define RT_ERROR 255 /**< A generic/unknown error happens */
#define RT_ETIMEOUT ETIMEDOUT /**< Timed out */
```
这类行因为保持列对齐,加上注释后往往超过 80 列(上面 `RT_ERROR` 一行是 95 列),这是可以接受的——**成组的常量宏优先保证纵向对齐,而不是单行长度**。
如果这个宏需要多行说明,例如带参数的宏要描述入参含义、展开结果或使用限制,就把注释移到宏**上方**,用 `/**` 开头的块注释,并以 `@def` 标注宏名:
```c
/**
* @ingroup group_basic_definition
*
* @def RT_ALIGN(size, align)
* Return the most contiguous size aligned at specified width. RT_ALIGN(13, 4)
* would return 16.
* @note align Must be an integer power of 2 or the result will be incorrect
*/
#define RT_ALIGN(size, align) (((size) + (align) - 1) & ~((align) - 1))
```
换句话说:**一条注释能说清就放行尾,需要一段话才能说清就放上方**。
两种写法 doxygen 都能识别为宏的文档,但有一个差别值得注意:**开启 `MACRO_EXPANSION` 后,行尾的 `/**<` 是挂在宏展开点上的**,同一个宏在多个位置展开时,注释可能出现在意料之外的地方;上方块注释则始终绑定在宏的定义处。因此当一个宏会被频繁展开时,优先用上方块注释。
**函数注释**:
注释以 `/**` 开头,以 ` */` 结尾,中间写入函数注释,组成元素如下,每个元素描述之间空一行,且首列对齐:
@@ -100,6 +100,46 @@ comments should describe what the code does. It should describe complicated
algorithms, for example. Comments for statements should be placed before the
statements or to the right of them. Any other locations are invalid.
**Macro comments**
Like statement comments, a macro can be documented either to the right of the
definition or above it. What decides it is how much explanation the macro needs,
and only then the line length.
Use a trailing `/**<` for simple constant macros, so that a group of values can
be read in one pass:
#define RT_EOK 0 /**< There is no error */
#define RT_ERROR 255 /**< A generic/unknown error happens */
Such lines are column aligned and often exceed 80 columns once the comment is
added (the `RT_ERROR` line above is 95 columns). That is accepted: for a group of
constant macros, keeping the columns aligned matters more than the line length.
When the macro needs more than one line of explanation - for example a
function-like macro whose arguments, expansion or restrictions have to be
described - move the comment above the definition, use a `/**` block and mark the
macro with `@def`:
/**
* @ingroup group_basic_definition
*
* @def RT_ALIGN(size, align)
* Return the most contiguous size aligned at specified width. RT_ALIGN(13, 4)
* would return 16.
* @note align Must be an integer power of 2 or the result will be incorrect
*/
#define RT_ALIGN(size, align) (((size) + (align) - 1) & ~((align) - 1))
In short: if a single line of comment says it, keep it trailing; if it takes a
paragraph, put it above.
Doxygen accepts both forms, but there is one difference worth knowing: with
`MACRO_EXPANSION` enabled, a trailing `/**<` is attached to the expansion site,
so a macro expanded in several places can carry its comment somewhere unexpected.
A block comment above the definition always stays with the definition, so prefer
it for macros that get expanded frequently.
# 9. Indent