docs: describe where a macro comment goes

documentation/7.contribution/coding_style_cn.md

@@ -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` 后，行尾的 `/**<` 是挂在宏展开点上的**，同一个宏在多个位置展开时，注释可能出现在意料之外的地方；上方块注释则始终绑定在宏的定义处。因此当一个宏会被频繁展开时，优先用上方块注释。
+
 **函数注释**：
 
 注释以 `/**` 开头，以 `  */` 结尾，中间写入函数注释，组成元素如下，每个元素描述之间空一行，且首列对齐：

documentation/7.contribution/coding_style_en.md

@@ -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