mirror of
https://github.com/RT-Thread/rt-thread.git
synced 2026-11-16 01:05:15 +08:00
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:
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
|
||||
|
||||
|
||||
Reference in new issue
Block a user