doc: Discourage trailing doxygen comments, and fix the broken ones
What changed, and why it matters
This commit only changes documentation style guidance and moves or converts code comments. It does not alter any program logic, data handling, or network behavior, so it has no security impact.
No security action needed; this is a documentation/style-only change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch updates doc/developer-notes.md to discourage trailing Doxygen comments (//! or /// after a member) because omitting the < silently breaks Doxygen output. It then fixes existing trailing/broken Doxygen comments in three header files by moving them above the member or converting them to plain // comments where they were not meant for Doxygen. No executable code, interfaces, or serialization formats are changed.
Changed components
doc/developer-notes.mdsrc/node/blockstorage.hsrc/private_broadcast.hsrc/wallet/transaction.hInspect captured patch +20 / −16
diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index feee2702..8b1e1066 100644
--- a/doc/developer-notes.md
+++ b/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++
diff --git a/src/node/blockstorage.h b/src/node/blockstorage.h
index 4fefa86a..b1e5aca3 100644
--- a/src/node/blockstorage.h
+++ b/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 {
diff --git a/src/private_broadcast.h b/src/private_broadcast.h
index fec61907..1031c01b 100644
--- a/src/private_broadcast.h
+++ b/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} {}
};
diff --git a/src/wallet/transaction.h b/src/wallet/transaction.h
index f979d83b..29baf669 100644
--- a/src/wallet/transaction.h
+++ b/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;
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.