doc: Discourage trailing doxygen comments, and fix the broken ones #34967

1. 
   maflcko commented at 4:40 pm on March 31, 2026: member

   The trailing doxygen comments are problematic:

   • They are often wrong and need to be fixed up manually, see e.g #7793, #14331, …, and this pull
   • Also, changing any type or name in a way that changes the max line length may require reflowing the whole struct with clang-format.
   • Also, once they become multi-line, they will read even more confusingly.

   Fix all issues by tolerating them, but favoring descriptions before the described item.

   Also, fix the broken ones.

   Example doxygen rendering: https://doxygen.bitcoincore.org/struct_private_broadcast_1_1_send_status.html (broken before this pull, fixed in this pull)

2. DrahtBot added the label Docs on Mar 31, 2026
3. 
   DrahtBot commented at 4:40 pm on March 31, 2026: contributor

   The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

   Reviews

   See the guideline for information on the review process.

   Type	Reviewers
   ACK	stickies-v

   If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.

4. maflcko force-pushed on Mar 31, 2026
5. in doc/developer-notes.md:1 in fa378842fc outdated

   ---

   ---

   

   stickies-v commented at 1:21 pm on April 2, 2026:

   I think we should be more explicit about discouraging inline comments, and provide the rationale for it. Having two “Description before the member” examples also seems a bit unnecessary, so suggested alternative to address all of that:

    0diff --git a/doc/developer-notes.md b/doc/developer-notes.md
    1index 820483f746..804755f49b 100644
    2--- a/doc/developer-notes.md
    3+++ b/doc/developer-notes.md
    4@@ -225,17 +225,16 @@ To describe a class, use the same construct above the class definition:
    5 class CAlert
    6 ```
    7 
    8-To describe a member or variable, you can use the same delimiters (`/**` and `*/`), or use a prefix of `//!`, or three slashes `///` (the styles are generally exchangeable):
    9+To describe a member or variable, place the comment on the line(s) before it, using `/**` and `*/`, `//!`, or `///`:
   10 ```c++
   11 //! Description before the member
   12 int var;
   13 ```
   14 
   15-or
   16-```c++
   17-/// Description before the member
   18-int var;
   19-```
   20+Avoid trailing (inline) member comments like `int var; //!< Description after the member`.
   21+
   22+  - *Rationale*: Forgetting the `<` silently breaks Doxygen output, they do not
   23+    support multi-line comments, and changing types or names requires reflowing.
   24 
   25 Also OK:
   26 ```c++
   

   ---

   

   maflcko commented at 1:50 pm on April 2, 2026:

   Thx, done. Though, I left out the style stuff, because trailing multi-line comments are supported, they just look ugly. Also, some devs may not care about having to re-flow.

   For reference, I also don’t like /** */, because devs often forget the second star (*), turning it into a code comment, not a doxygen comment. Also, they are inconsistently used (even in the same class):

    0/** one */
    1
    2/**
    3 * two */
    4
    5/** three_a
    6 * three_b
    7 */
    8
    9/**
   10 * four
   11 */
   

   Though, at least they are not actively wrong, like the trailing comments, so I don’t really mind too much.

6. 
   stickies-v commented at 1:21 pm on April 2, 2026: contributor

   Approach ACK, I think we should be a bit more explicit in developer-notes.
7. doc: Discourage trailing doxygen comments, and fix the broken ones facaeb9c76
8. maflcko force-pushed on Apr 2, 2026
9. stickies-v approved
10. 
    stickies-v commented at 2:04 pm on April 2, 2026: contributor

    ACK facaeb9c762d29a573a9c19b3617699136b133e8

Contributors
maflcko DrahtBot stickies-v

Labels
Docs