Merge bitcoin/bitcoin#36704: doc: fix docs and enable `-Wdocumentation-pedantic`
What changed, and why it matters
This commit only changes documentation comments and enables a stricter compiler warning for documentation style. It does not alter any executable code, so it cannot introduce or fix a security vulnerability on its own.
No security action required. Treat as a normal documentation/build-hygiene change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The merge commit enables -Wdocumentation-pedantic in CMake and updates Doxygen/Javadoc-style comments across headers and source files to satisfy the stricter warning. Changes include correcting @param[in]/@param[out] direction annotations, spelling out escape sequences in prose, converting non-Doxygen block comments to Doxygen format, and fixing typos. No functional code is modified.
Changed components
CMake build configurationDoxygen documentation comments in src/httpserver.h, src/kernel/bitcoinkernel.h, src/qt/bitcoingui.h, src/qt/sendcoinsdialog.h, src/streams.h, src/util/subprocess.h, src/wallet/coinselection.cpp, src/wallet/wallet.h, and othersInspect captured patch +79 / −77
### CMakeLists.txt
@@ -503,6 +503,7 @@ try_append_cxx_flags("-Wsuggest-override" TARGET warn_interface SKIP_LINK)
try_append_cxx_flags("-Wimplicit-fallthrough" TARGET warn_interface SKIP_LINK)
try_append_cxx_flags("-Wunreachable-code-aggressive" TARGET warn_interface SKIP_LINK)
try_append_cxx_flags("-Wdocumentation" TARGET warn_interface SKIP_LINK)
+try_append_cxx_flags("-Wdocumentation-pedantic" TARGET warn_interface SKIP_LINK)
try_append_cxx_flags("-Wself-assign" TARGET warn_interface SKIP_LINK)
try_append_cxx_flags("-Wbidi-chars=any" TARGET warn_interface SKIP_LINK)
try_append_cxx_flags("-Wundef" TARGET warn_interface SKIP_LINK)
### src/httpserver.h
@@ -110,10 +110,10 @@ class HTTPHeaders
/**
* @param[in] reader A LineReader instance initialized with the client's receive buffer.
* @param[in] write Whether or not to write the parsed data to the object after validation.
- * @returns false if LineReader hits the end of the buffer before reading an
- * \n, meaning that we are still waiting on more data from the client.
+ * @returns false if LineReader hits the end of the buffer before reading a
+ * newline, meaning that we are still waiting on more data from the client.
* true after reading an entire HTTP headers section, terminated
- * by an empty line and \n.
+ * by an empty line and a newline.
* @throws on exceeded read limit and on bad headers syntax (e.g. no ":" in a line)
*/
bool Read(util::LineReader& reader, bool write = true);
### src/kernel/bitcoinkernel.h
@@ -2098,7 +2098,7 @@ BITCOINKERNEL_API btck_BlockHash* BITCOINKERNEL_WARN_UNUSED_RESULT btck_block_ha
* @brief Serializes the block hash to bytes.
*
* @param[in] block_hash Non-null.
- * @param[in] output The serialized block hash.
+ * @param[out] output The serialized block hash.
*/
BITCOINKERNEL_API void btck_block_hash_to_bytes(
const btck_BlockHash* block_hash, unsigned char output[32]) BITCOINKERNEL_ARG_NONNULL(1, 2);
### src/logging.cpp
@@ -332,7 +332,7 @@ namespace BCLog {
/** Belts and suspenders: make sure outgoing log messages don't contain
* potentially suspicious characters, such as terminal control codes.
*
- * This escapes control characters, including newline ('\n'), in C syntax,
+ * This escapes control characters, including newline, in C syntax,
* so untrusted data can't forge log lines. It escapes instead of removes
* them to still allow for troubleshooting issues where they accidentally
* end up in strings.
### src/net_processing.cpp
@@ -714,7 +714,7 @@ class PeerManagerImpl final : public PeerManager
/**
* Reconsider orphan transactions after a parent has been accepted to the mempool.
*
- * @peer[in] peer The peer whose orphan transactions we will reconsider. At most
+ * @param[in] peer The peer whose orphan transactions we will reconsider. At most
* one orphan will be reconsidered on each call of this function. If an
* accepted orphan has orphaned children, those will need to be
* reconsidered, creating more work, possibly for other peers.
### src/psbt.h
@@ -1666,8 +1666,8 @@ bool FinalizePSBT(PartiallySignedTransaction& psbtx);
/**
* Finalizes a PSBT if possible, and extracts it to a CMutableTransaction if it could be finalized.
*
- * @param[in] psbtx PartiallySignedTransaction
- * @param[out] result CMutableTransaction representing the complete transaction, if successful
+ * @param[in,out] psbtx PartiallySignedTransaction
+ * @param[out] result CMutableTransaction representing the complete transaction, if successful
* @return True if we successfully extracted the transaction, false otherwise
*/
bool FinalizeAndExtractPSBT(PartiallySignedTransaction& psbtx, CMutableTransaction& result);
### src/qt/bitcoingui.h
@@ -240,7 +240,7 @@ public Q_SLOTS:
@param[in] message the displayed text
@param[in] style modality and style definitions (icon and used buttons - buttons only for message boxes)
@see CClientUIInterface::MessageBoxFlags
- @param[in] ret pointer to a bool that will be modified to whether Ok was clicked (modal only)
+ @param[out] ret pointer to a bool that will be modified to whether Ok was clicked (modal only)
@param[in] detailed_message the text to be displayed in the details area
*/
void message(const QString& title, QString message, unsigned int style, bool* ret = nullptr, const QString& detailed_message = QString());
### src/qt/sendcoinsdialog.h
@@ -83,15 +83,15 @@ public Q_SLOTS:
void minimizeFeeSection(bool fMinimize);
// Format confirmation message
bool PrepareSendText(QString& question_string, QString& informative_text, QString& detailed_text);
- /* Sign PSBT using external signer.
+ /** Sign PSBT using external signer.
*
* @param[in,out] psbtx the PSBT to sign
- * @param[in,out] mtx needed to attempt to finalize
- * @param[in,out] complete whether the PSBT is complete (a successfully signed multisig transaction may not be complete)
+ * @param[out] mtx needed to attempt to finalize
+ * @param[out] complete whether the PSBT is complete (a successfully signed multisig transaction may not be complete)
*
* @returns false if any failure occurred, which may include the user rejection of a transaction on the device.
*/
- bool signWithExternalSigner(PartiallySignedTransaction& psbt, CMutableTransaction& mtx, bool& complete);
+ bool signWithExternalSigner(PartiallySignedTransaction& psbtx, CMutableTransaction& mtx, bool& complete);
void updateFeeMinimizedLabel();
void updateCoinControlState();
### src/streams.h
@@ -34,19 +34,21 @@
class VectorWriter
{
public:
-/*
- * @param[in] vchDataIn Referenced byte vector to overwrite/append
- * @param[in] nPosIn Starting position. Vector index where writes should start. The vector will initially
- * grow as necessary to max(nPosIn, vec.size()). So to append, use vec.size().
+/**
+ * @param[in,out] vchDataIn Referenced byte vector to overwrite/append
+ * @param[in] nPosIn Starting position. Vector index where writes should start. The vector will
+ * initially grow as necessary to max(nPosIn, vec.size()). So to append, use vec.size().
*/
VectorWriter(std::vector<unsigned char>& vchDataIn, size_t nPosIn) : vchData{vchDataIn}, nPos{nPosIn}
{
if(nPos > vchData.size())
vchData.resize(nPos);
}
-/*
- * (other params same as above)
- * @param[in] args A list of items to serialize starting at nPosIn.
+/**
+ * @param[in,out] vchDataIn Referenced byte vector to overwrite/append
+ * @param[in] nPosIn Starting position. Vector index where writes should start. The vector will
+ * initially grow as necessary to max(nPosIn, vec.size()). So to append, use vec.size().
+ * @param[in] args A list of items to serialize starting at nPosIn.
*/
template <typename... Args>
VectorWriter(std::vector<unsigned char>& vchDataIn, size_t nPosIn, Args&&... args) : VectorWriter{vchDataIn, nPosIn}
### src/torcontrol.cpp
@@ -292,7 +292,7 @@ std::map<std::string,std::string> ParseTorReplyMapping(const std::string &s)
if (ptr == s.size()) // unexpected end of line
return std::map<std::string,std::string>();
++ptr; // skip closing '"'
- /**
+ /*
* Unescape value. Per https://spec.torproject.org/control-spec section 2.1.1:
*
* For future-proofing, controller implementers MAY use the following
### src/util/fs.h
@@ -152,7 +152,7 @@ static inline bool copy_file(const path& from, const path& to, copy_options opti
* appropriate to use in applications requiring UTF-8, where
* fs::path::u8string() / fs::path::utf8string() and fs::u8path() methods should be used instead. Other
* applications could require still different encodings. For example, JSON, XML,
- * or URI applications might prefer to use higher-level escapes (\uXXXX or
+ * or URI applications might prefer to use higher-level escapes (Unicode escapes or
* &XXXX; or %XX) instead of multibyte encoding. Rust, Python, Java applications
* may require encoding paths with their respective UTF-8 derivatives WTF-8,
* PEP-383, and CESU-8 (see https://en.wikipedia.org/wiki/UTF-8#Derivatives).
### src/util/strencodings.h
@@ -154,8 +154,8 @@ constexpr bool IsDigit(char c)
/**
* Tests if the given character is a whitespace character. The whitespace characters
- * are: space, form-feed ('\f'), newline ('\n'), carriage return ('\r'), horizontal
- * tab ('\t'), and vertical tab ('\v').
+ * are: space, form-feed, newline, carriage return, horizontal tab, and vertical
+ * tab.
*
* This function is locale independent. Under the C locale this function gives the
* same result as std::isspace.
### src/util/string.h
@@ -233,7 +233,7 @@ inline std::string MakeUnorderedList(const std::vector<std::string>& items)
}
/**
- * Check if a string contains any embedded NUL (\0) characters
+ * Check if a string contains any embedded NUL characters
*/
[[nodiscard]] inline bool ContainsNUL(std::string_view str) noexcept
{
@@ -276,12 +276,12 @@ class LineReader
explicit LineReader(std::string_view str LIFETIMEBOUND, size_t max_line_length);
/**
- * Returns a string from current iterator position up to (but not including) next \n
- * and advances iterator to the character following the \n on success.
+ * Returns a string from current iterator position up to (but not including) next newline
+ * and advances iterator to the character following the newline on success.
* Will not return a line longer than max_line_length.
* @returns the next string from the buffer.
- * std::nullopt if end of buffer is reached without finding a \n.
- * @throws a std::runtime_error if max_line_length + 1 bytes are read without finding \n.
+ * std::nullopt if end of buffer is reached without finding a newline.
+ * @throws a std::runtime_error if max_line_length + 1 bytes are read without finding a newline.
*/
std::optional<std::string_view> ReadLine() LIFETIMEBOUND;
### src/util/subprocess.h
@@ -299,12 +299,11 @@ namespace util
/*!
* Function: split
- * Parameters:
- * [in] str : Input string which needs to be split based upon the
- * delimiters provided.
- * [in] deleims : Delimiter characters based upon which the string needs
- * to be split. Default constructed to ' '(space) and '\t'(tab)
- * [out] vector<string> : Vector of strings split at deleimiter.
+ * @param[in] str Input string which needs to be split based upon the
+ * delimiters provided.
+ * @param[in] delims Delimiter characters based upon which the string needs
+ * to be split. Default constructed to space and tab.
+ * @return Vector of strings split at delimiter.
*/
static inline std::vector<std::string>
split(const std::string& str, const std::string& delims=" \t")
@@ -332,10 +331,9 @@ namespace util
* Function: set_clo_on_exec
* Sets/Resets the FD_CLOEXEC flag on the provided file descriptor
* based upon the `set` parameter.
- * Parameters:
- * [in] fd : The descriptor on which FD_CLOEXEC needs to be set/reset.
- * [in] set : If 'true', set FD_CLOEXEC.
- * If 'false' unset FD_CLOEXEC.
+ * @param[in] fd The descriptor on which FD_CLOEXEC needs to be set/reset.
+ * @param[in] set If 'true', set FD_CLOEXEC.
+ * If 'false' unset FD_CLOEXEC.
*/
static inline
void set_clo_on_exec(int fd, bool set = true)
@@ -356,8 +354,7 @@ namespace util
* Function: pipe_cloexec
* Creates a pipe and sets FD_CLOEXEC flag on both
* read and write descriptors of the pipe.
- * Parameters:
- * [out] : A pair of file descriptors.
+ * @return A pair of file descriptors.
* First element of pair is the read descriptor of pipe.
* Second element is the write descriptor of pipe.
*/
@@ -382,12 +379,11 @@ namespace util
* Function: write_n
* Writes `length` bytes to the file descriptor `fd`
* from the buffer `buf`.
- * Parameters:
- * [in] fd : The file descriptotr to write to.
- * [in] buf: Buffer from which data needs to be written to fd.
- * [in] length: The number of bytes that needs to be written from
- * `buf` to `fd`.
- * [out] int : Number of bytes written or -1 in case of failure.
+ * @param[in] fd The file descriptor to write to.
+ * @param[in] buf Buffer from which data needs to be written to fd.
+ * @param[in] length The number of bytes that needs to be written from
+ * `buf` to `fd`.
+ * @return Number of bytes written or -1 in case of failure.
*/
static inline
int write_n(int fd, const char* buf, size_t length)
@@ -406,12 +402,12 @@ namespace util
* Function: read_atmost_n
* Reads at the most `read_upto` bytes from the
* file object `fp` before returning.
- * Parameters:
- * [in] fp : The file object from which it needs to read.
- * [in] buf : The buffer into which it needs to write the data.
- * [in] read_upto: Max number of bytes which must be read from `fd`.
- * [out] int : Number of bytes written to `buf` or read from `fd`
- * OR -1 in case of error.
+ * @param[in] fp The file object from which it needs to read.
+ * @param[out] buf The buffer into which it needs to write the data.
+ * @param[in] read_upto Max number of bytes which must be read from `fd`.
+ * @return Number of bytes written to `buf` or read from `fd`
+ * OR -1 in case of error.
+ *
* NOTE: In case of EINTR while reading from socket, this API
* will retry to read from `fd`, but only till the EINTR counter
* reaches 50 after which it will return with whatever data it read.
@@ -449,11 +445,10 @@ namespace util
* Function: read_all
* Reads all the available data from `fp` into
* `buf`. Internally calls read_atmost_n.
- * Parameters:
- * [in] fp : The file object from which to read from.
- * [in] buf : The buffer of type `class Buffer` into which
- * the read data is written to.
- * [out] int: Number of bytes read OR -1 in case of failure.
+ * @param[in] fp The file object from which to read from.
+ * @param[in,out] buf The buffer of type `class Buffer` into which
+ * the read data is written to.
+ * @return Number of bytes read OR -1 in case of failure.
*
* NOTE: `class Buffer` is a exposed public class. See below.
*/
@@ -497,9 +492,8 @@ namespace util
* Function: wait_for_child_exit
* Waits for the process with pid `pid` to exit
* and returns its status.
- * Parameters:
- * [in] pid : The pid of the process.
- * [out] pair<int, int>:
+ * @param[in] pid The pid of the process.
+ * @return pair<int, int>:
* pair.first : Return code of the waitpid call.
* pair.second : Exit status of the process.
*
### src/wallet/coinselection.cpp
@@ -49,7 +49,9 @@ struct {
}
} descending_effval_weight;
-/*
+static const size_t TOTAL_TRIES = 100000;
+
+/**
* This is the Branch and Bound Coin Selection algorithm designed by Murch. It searches for an input
* set that can pay for the spending target and does not exceed the spending target by more than the
* cost of creating and spending a change output. The algorithm uses a depth-first search on a binary
@@ -99,19 +101,16 @@ struct {
* The Branch and Bound algorithm is described in detail in Murch's Master Thesis:
* https://murch.one/wp-content/uploads/2016/11/erhardt2016coinselection.pdf
*
- * @param const std::vector<OutputGroup>& utxo_pool The set of UTXO groups that we are choosing from.
+ * @param[in,out] utxo_pool The set of UTXO groups that we are choosing from.
* These UTXO groups will be sorted in descending order by effective value and the OutputGroups'
* values are their effective values.
- * @param const CAmount& selection_target This is the value that we want to select. It is the lower
+ * @param[in] selection_target This is the value that we want to select. It is the lower
* bound of the range.
- * @param const CAmount& cost_of_change This is the cost of creating and spending a change output.
+ * @param[in] cost_of_change This is the cost of creating and spending a change output.
* This plus selection_target is the upper bound of the range.
- * @param int max_selection_weight The maximum allowed weight for a selection result to be valid.
+ * @param[in] max_selection_weight The maximum allowed weight for a selection result to be valid.
* @returns The result of this coin selection algorithm, or std::nullopt
*/
-
-static const size_t TOTAL_TRIES = 100000;
-
util::Result<SelectionResult> SelectCoinsBnB(std::vector<OutputGroup>& utxo_pool, const CAmount& selection_target, const CAmount& cost_of_change,
int max_selection_weight)
{
@@ -274,7 +273,7 @@ util::Result<SelectionResult> SelectCoinsBnB(std::vector<OutputGroup>& utxo_pool
}
-/*
+/**
* TL;DR: Coin Grinder is a DFS-based algorithm that deterministically searches for the minimum-weight input set to fund
* the transaction. The algorithm is similar to the Branch and Bound algorithm, but will produce a transaction _with_ a
* change output instead of a changeless transaction.
@@ -289,6 +288,7 @@ util::Result<SelectionResult> SelectCoinsBnB(std::vector<OutputGroup>& utxo_pool
* We represent UTXOs as _alias=[effective_value/weight]_ and indicate omitted UTXOs with an underscore. Given a UTXO
* pool {A=[10/2], B=[7/1], C=[5/1], D=[4/2]} sorted by descending effective value, our search tree looks as follows:
*
+ * @verbatim
* _______________________ {} ________________________
* / \
* A=[10/2] __________ {A} _________ __________ {_} _________
@@ -298,6 +298,7 @@ util::Result<SelectionResult> SelectCoinsBnB(std::vector<OutputGroup>& utxo_pool
* C=[5/1] {ABC} {AB_} {A_C} {A__} {_BC} {_B_} {__C} {___}
* / \ / \ / \ / \ / \ / \ / \ / \
* D=[4/2] {ABCD} {ABC_} {AB_D} {AB__} {A_CD} {A_C_} {A__D} {A___} {_BCD} {_BC_} {_B_D} {_B__} {__CD} {__C_} {___D} {____}
+ * @endverbatim
*
*
* CoinGrinder uses a depth-first search to walk this tree. It first tries inclusion branches, then omission branches. A
@@ -321,6 +322,7 @@ util::Result<SelectionResult> SelectCoinsBnB(std::vector<OutputGroup>& utxo_pool
*
* {A} {AB} {ABC} {ABCD} {AB_D} {A_C} {A_CD} {A__D} {_B} {_BC} {_BCD} {_B_D} {__C} {__CD} {___D}
*
+ * @verbatim
* _______________________ {} ________________________
* / \
* A=[10/2] __________ {A} _________ ___________\____________
@@ -330,6 +332,7 @@ util::Result<SelectionResult> SelectCoinsBnB(std::vector<OutputGroup>& utxo_pool
* C=[5/1] {ABC} \ {A_C} \ {_BC} \ {__C} \
* / / / / / / / /
* D=[4/2] {ABCD} {AB_D} {A_CD} {A__D} {_BCD} {_B_D} {__CD} {___D}
+ * @endverbatim
*
*
* We refer to the move from the inclusion branch {AB} via the omission branch {A_} to its inclusion-branch child {A_C}
@@ -365,6 +368,7 @@ util::Result<SelectionResult> SelectCoinsBnB(std::vector<OutputGroup>& utxo_pool
* {__CD} [9/3] Insufficient funds, leaf node: CUT
* {___D} [4/2] Insufficient funds, leaf node, cannot CUT since only one UTXO selected: done.
*
+ * @verbatim
* _______________________ {} ________________________
* / \
* A=[10/2] __________ {A} _________ ___________\____________
@@ -374,26 +378,27 @@ util::Result<SelectionResult> SelectCoinsBnB(std::vector<OutputGroup>& utxo_pool
* C=[5/1] {A_C} \ {_BC} \ {__C} \
* / / / /
* D=[4/2] {A__D} {_B_D} {__CD} {___D}
+ * @endverbatim
*
*
* We implement this tree walk in the following algorithm:
* 1. Add `next_utxo`
* 2. Evaluate candidate input set
* 3. Determine `next_utxo` by deciding whether to
- * a) EXPLORE: Add next inclusion branch, e.g. {_B} ⇒ {_B} + `next_uxto`: C
+ * a) EXPLORE: Add next inclusion branch, e.g. {_B} ⇒ {_B} + `next_utxo`: C
* b) SHIFT: Replace last selected UTXO by next higher index, e.g. {A_C} ⇒ {A__} + `next_utxo`: D
- * c) CUT: deselect last selected UTXO and shift to omission branch of penultimate UTXO, e.g. {AB_D} ⇒ {A_} + `next_utxo: C
+ * c) CUT: deselect last selected UTXO and shift to omission branch of penultimate UTXO, e.g. {AB_D} ⇒ {A_} + `next_utxo`: C
*
* The implementation then adds further optimizations by discovering further situations in which either the inclusion
* branch can be skipped, or both the inclusion and omission branch can be skipped after evaluating the candidate input
* set in the node.
*
- * @param std::vector<OutputGroup>& utxo_pool The UTXOs that we are choosing from. These UTXOs will be sorted in
+ * @param[in,out] utxo_pool The UTXOs that we are choosing from. These UTXOs will be sorted in
* descending order by effective value, with lower weight preferred as a tie-breaker. (We can think of an output
* group with multiple as a heavier UTXO with the combined amount here.)
- * @param const CAmount& selection_target This is the minimum amount that we need for the transaction without considering change.
- * @param const CAmount& change_target The minimum budget for creating a change output, by which we increase the selection_target.
- * @param int max_selection_weight The maximum allowed weight for a selection result to be valid.
+ * @param[in] selection_target This is the minimum amount that we need for the transaction without considering change.
+ * @param[in] change_target The minimum budget for creating a change output, by which we increase the selection_target.
+ * @param[in] max_selection_weight The maximum allowed weight for a selection result to be valid.
* @returns The result of this coin selection algorithm, or std::nullopt
*/
util::Result<SelectionResult> CoinGrinder(std::vector<OutputGroup>& utxo_pool, const CAmount& selection_target, CAmount change_target, int max_selection_weight)
### src/wallet/wallet.h
@@ -651,7 +651,7 @@ class CWallet final : public WalletStorage, public interfaces::Chain::Notificati
* Sets `complete` if the PSBT is now complete (i.e. has all required
* signatures or signature-parts, and is ready to finalize.)
*
- * @param[in] psbtx PartiallySignedTransaction to fill in
+ * @param[in,out] psbtx PartiallySignedTransaction to fill in
* @param[in] options options for filling or signing
* @param[out] complete indicates whether the PSBT is now complete
* @param[out] n_signed the number of inputs signed by this walletWhy 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.