Files
rt-thread/documentation
Yunlk e0aa4cecaf 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.
2026-11-03 09:48:31 +08:00
..
…
…
…