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

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

@@ -116,10 +116,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;