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

facaeb9c76 doc: Discourage trailing doxygen comments, and fix the broken ones (MarcoFalke)

Pull request description:

  The trailing doxygen comments are problematic:

  * They are often wrong and need to be fixed up manually, see e.g https://github.com/bitcoin/bitcoin/pull/7793, https://github.com/bitcoin/bitcoin/pull/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)

ACKs for top commit:
  l0rinc:
    ACK facaeb9c76
  stickies-v:
    ACK facaeb9c76

Tree-SHA512: db725140bd907ac61f2fe58681d4a23f392ef712ef8772564f3a3d83ed446e068bb390907ee30c2015d8b396a42a31817f56b8dcb2d86d1314aed9208a86e2bd

doc/developer-notes.md

@@ -225,16 +225,15 @@ To describe a class, use the same construct above the class definition:
 class CAlert
 ```
 
-To describe a member or variable use:
+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++
-int var; //!< Description after the member
-```
+Avoid trailing (inline) member comments like `int var; //!< Description after the member`.
+
+  - *Rationale*: Forgetting the `<` silently breaks Doxygen output.
 
 Also OK:
 ```c++

src/node/blockstorage.h

@@ -145,7 +145,8 @@ struct CBlockIndexHeightOnlyComparator {
 };
 
 struct PruneLockInfo {
-    int height_first{std::numeric_limits<int>::max()}; //! Height of earliest block that should be kept and not pruned
+    /// Height of earliest block that should be kept and not pruned
+    int height_first{std::numeric_limits<int>::max()};
 };
 
 enum BlockfileType {

src/private_broadcast.h

@@ -126,10 +126,14 @@ public:
 private:
     /// Status of a transaction sent to a given node.
     struct SendStatus {
-        const NodeId nodeid; /// Node to which the transaction will be sent (or was sent).
-        const CService address; /// Address of the node.
-        const NodeClock::time_point picked; ///< When was the transaction picked for sending to the node.
-        std::optional<NodeClock::time_point> confirmed; ///< When was the transaction reception confirmed by the node (by PONG).
+        /// Node to which the transaction will be sent (or was sent).
+        const NodeId nodeid;
+        /// Address of the node.
+        const CService address;
+        /// When was the transaction picked for sending to the node.
+        const NodeClock::time_point picked;
+        /// When was the transaction reception confirmed by the node (by PONG).
+        std::optional<NodeClock::time_point> confirmed;
 
         SendStatus(const NodeId& nodeid, const CService& address, const NodeClock::time_point& picked) : nodeid{nodeid}, address{address}, picked{picked} {}
     };

src/wallet/transaction.h

@@ -294,9 +294,9 @@ public:
             mapValueCopy["timesmart"] = strprintf("%u", nTimeSmart);
         }
 
-        std::vector<uint8_t> dummy_vector1; //!< Used to be vMerkleBranch
-        std::vector<uint8_t> dummy_vector2; //!< Used to be vtxPrev
-        bool dummy_bool = false; //!< Used to be fFromMe, and fSpent
+        std::vector<uint8_t> dummy_vector1; // Used to be vMerkleBranch
+        std::vector<uint8_t> dummy_vector2; // Used to be vtxPrev
+        bool dummy_bool = false; // Used to be fFromMe, and fSpent
         uint32_t dummy_int = 0; // Used to be fTimeReceivedIsTxTime
         uint256 serializedHash = TxStateSerializedBlockHash(m_state);
         int serializedIndex = TxStateSerializedIndex(m_state);
@@ -308,9 +308,9 @@ public:
     {
         Init();
 
-        std::vector<uint256> dummy_vector1; //!< Used to be vMerkleBranch
-        std::vector<CMerkleTx> dummy_vector2; //!< Used to be vtxPrev
-        bool dummy_bool; //! Used to be fFromMe, and fSpent
+        std::vector<uint256> dummy_vector1; // Used to be vMerkleBranch
+        std::vector<CMerkleTx> dummy_vector2; // Used to be vtxPrev
+        bool dummy_bool; // Used to be fFromMe, and fSpent
         uint32_t dummy_int; // Used to be fTimeReceivedIsTxTime
         uint256 serialized_block_hash;
         int serializedIndex;