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

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:

<details> <summary>git diff on fa378842fc</summary>

diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index 820483f746..804755f49b 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -225,17 +225,16 @@ To describe a class, use the same construct above the class definition:
 class CAlert
 ```
 
-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):
+To describe a member or variable, place the comment on the line(s) before it, using `/**` and `*/`, `//!`, or `///`:
 ```c++
 //! Description before the member
 int var;
 ```
 
-or
-```c++
-/// Description before the member
-int var;
-```
+Avoid trailing (inline) member comments like `int var; //!< Description after the member`.
+
+  - *Rationale*: Forgetting the `<` silently breaks Doxygen output, they do not
+    support multi-line comments, and changing types or names requires reflowing.
 
 Also OK:
 ```c++

</details>

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):

/** one */

/**
 * two */

/** three_a
 * three_b
 */

/**
 * four
 */

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