Prompted by #36594 (review).
doc: fix docs and enable `-Wdocumentation-unknown-command` #36704
pull fanquake wants to merge 5 commits into bitcoin:master from fanquake:doc_param_direction_fixes changing 16 files +79 −77-
fanquake commented at 11:48 AM on October 30, 2026: member
- DrahtBot added the label Docs on Oct 30, 2026
-
DrahtBot commented at 11:48 AM on October 30, 2026: contributor
<!--e57a25ab6845829454e8d69fc972939a-->
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.
<!--006a51241073e994b41acfe9ec718e94-->
External sites
- Code coverage & benchmarks: https://corecheck.dev/bitcoin/bitcoin/pulls/36704
- Ralph review <img src=https://review.fish.foo/assets/bitcoin/bitcoin/36704.png alt="Ralph review status"> https://git.fish.foo/bitcoin/bitcoin/pulls/36704#author-ralph
<!--021abf342d371248e50ceaed478a90ca-->
Reviews
See the guideline and AI policy for information on the review process.
Type Reviewers Stale ACK hebasto If your review is incorrectly listed, please copy-paste <code><!--meta-tag:bot-skip--></code> into the comment that the bot should ignore.
<!--174a7506f384e20aa4161008e828411d-->
Conflicts
No conflicts as of last run.
<!--5faf32d7da4f0f540f40219e4f7537a3-->
- fanquake force-pushed on Oct 30, 2026
- DrahtBot added the label CI failed on Oct 30, 2026
- DrahtBot removed the label CI failed on Oct 30, 2026
- fanquake force-pushed on Nov 2, 2026
- fanquake force-pushed on Nov 4, 2026
- fanquake force-pushed on Nov 5, 2026
- fanquake requested review from hebasto on Nov 11, 2026
-
in CMakeLists.txt:506 in 3e3ed748bf
502 | @@ -503,6 +503,7 @@ try_append_cxx_flags("-Wsuggest-override" TARGET warn_interface SKIP_LINK) 503 | try_append_cxx_flags("-Wimplicit-fallthrough" TARGET warn_interface SKIP_LINK) 504 | try_append_cxx_flags("-Wunreachable-code" TARGET warn_interface SKIP_LINK) 505 | try_append_cxx_flags("-Wdocumentation" TARGET warn_interface SKIP_LINK) 506 | +try_append_cxx_flags("-Wdocumentation-unknown-command" TARGET warn_interface SKIP_LINK)
hebasto commented at 12:56 PM on November 11, 2026:A broader warning group works as well:
try_append_cxx_flags("-Wdocumentation-pedantic" TARGET warn_interface SKIP_LINK)in src/torcontrol.cpp:303 in 3e3ed748bf
299 | @@ -300,7 +300,7 @@ std::map<std::string,std::string> ParseTorReplyMapping(const std::string &s) 300 | * rules to be compatible with buggy Tor implementations and with 301 | * future ones that implement the spec as intended: 302 | * 303 | - * Read \n \t \r and \0 ... \377 as C escapes. 304 | + * Read \\n \\t \\r and \\0 ... \\377 as C escapes.
hebasto commented at 12:58 PM on November 11, 2026:The entire comment shouldn't be a Doxygen one in the first place.
in src/qt/sendcoinsdialog.h:88 in 3e3ed748bf
82 | @@ -83,9 +83,9 @@ public Q_SLOTS: 83 | void minimizeFeeSection(bool fMinimize); 84 | // Format confirmation message 85 | bool PrepareSendText(QString& question_string, QString& informative_text, QString& detailed_text); 86 | - /* Sign PSBT using external signer. 87 | + /** Sign PSBT using external signer. 88 | * 89 | - * @param[in,out] psbtx the PSBT to sign 90 | + * @param[in,out] psbt the PSBT to sign
hebasto commented at 1:05 PM on November 11, 2026:Wouldn't it be better to rename the parameter in the declaration to
psbtx, matching the function definition, instead?hebasto commented at 1:58 PM on November 11, 2026: memberTested 3e3ed748bf48b4643699c56e4aedaae6fa025c5c on Fedora 45 using Clang 23.
Comments in
src/util/subprocess.hare still missing@paramcommands.My main concern about this PR is that it introduces escaping in Doxygen comments to please the compiler. There are two issues with that::
-Wdocumentation-unknown-commanddoes not trigger on\n. So a few cases remain in the code. And it is rendered simply as a line break, which is wrong: https://doxygen.bitcoincore.org/classutil_1_1_line_reader.html#a36462c325f3e18b1ceb453e6a7282bce.- Escaping may confuse anyone who reads the comments in the code. We can replace all escape sequences in the Doxygen comments with their names: "tab", "newline" etc, where possible.
The changes to the parameter direction attributes are correct. However, they are neither necessary for enabling
-Wdocumentation-unknown-commandnor enforced by it, which means we can't be sure that they are complete. At least some more cases were noted by Ralph.fanquake force-pushed on Nov 12, 2026hebasto approvedhebasto commented at 12:02 PM on November 12, 2026: memberACK 2c21beac909d45d7ef8491fca3291abfd063a8e1.
A Doxygen rendering nit:
--- a/src/util/subprocess.h +++ b/src/util/subprocess.h @@ -407,6 +407,7 @@ namespace util * [@param](/bitcoin-bitcoin/contributor/param/)[in] read_upto Max number of bytes which must be read from `fd`. * [@return](/bitcoin-bitcoin/contributor/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.fanquake force-pushed on Nov 12, 2026DrahtBot added the label CI failed on Nov 12, 2026hebasto approvedhebasto commented at 12:21 PM on November 12, 2026: memberACK 651d4b65cdc53c8da5983ff442ff76b8a0dc4e78.
DrahtBot removed the label CI failed on Nov 12, 2026fanquake requested review from willcl-ark on Nov 12, 2026doc: fix incorrect @param annotations 6a0a221271ab7b1abc62doc: use doxygen comments for blocks containing @param
Plain /* comments are ignored by Doxygen and by clang's -Wdocumentation, so mistakes in them go unnoticed. Also wrap the CoinGrinder ASCII trees in @verbatim so Doxygen keeps their layout.
doc: use @param and @return in subprocess.h cbd28fa468b64432d28cdoc: spell out escape sequences in doxygen comments
Doxygen interprets a backslash followed by a letter as a command, so '\n' renders as a line break and '\t' etc. are unknown commands.
08b6dcba33build: enable -Wdocumentation-pedantic
Catches misspelled doxygen commands such as '@peer[in]' (for '@param[in]'), which -Wdocumentation alone does not report. i.e ```bash ../src/net_processing.cpp:717:8: warning: unknown command tag name [-Wdocumentation-unknown-command] 717 | * @peer[in] peer The peer whose orphan transactions we will reconsider. Generally only | ^~~~~ 1 warning generated. ```in src/streams.h:48 in 651d4b65cd
43 | @@ -44,8 +44,10 @@ class VectorWriter 44 | if(nPos > vchData.size()) 45 | vchData.resize(nPos); 46 | } 47 | -/* 48 | - * (other params same as above) 49 | +/** 50 | + * @param[in] vchDataIn Referenced byte vector to overwrite/append
willcl-ark commented at 5:29 PM on November 12, 2026:Might this be:
* [@param](/bitcoin-bitcoin/contributor/param/)[in,out] vchDataIn Referenced byte vector to overwrite/appendand perhaps L38 too?
fanquake commented at 7:09 PM on November 12, 2026:Pushed.
fanquake force-pushed on Nov 12, 2026fanquake requested review from hebasto on Nov 18, 2026ContributorsLabels
github-metadata-mirror
This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-11-20 15:51 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me