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
  1. fanquake commented at 11:48 AM on October 30, 2026: member

    Prompted by #36594 (review).

  2. DrahtBot added the label Docs on Oct 30, 2026
  3. 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

    <!--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>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

    <!--174a7506f384e20aa4161008e828411d-->

    Conflicts

    No conflicts as of last run.

    <!--5faf32d7da4f0f540f40219e4f7537a3-->

  4. fanquake force-pushed on Oct 30, 2026
  5. DrahtBot added the label CI failed on Oct 30, 2026
  6. DrahtBot removed the label CI failed on Oct 30, 2026
  7. fanquake force-pushed on Nov 2, 2026
  8. fanquake force-pushed on Nov 4, 2026
  9. fanquake force-pushed on Nov 5, 2026
  10. fanquake requested review from hebasto on Nov 11, 2026
  11. 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)
    
  12. 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.

  13. 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?

  14. hebasto commented at 1:58 PM on November 11, 2026: member

    Tested 3e3ed748bf48b4643699c56e4aedaae6fa025c5c on Fedora 45 using Clang 23.

    Comments in src/util/subprocess.h are still missing @param commands.

    My main concern about this PR is that it introduces escaping in Doxygen comments to please the compiler. There are two issues with that::

    1. -Wdocumentation-unknown-command does 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.
    2. 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-command nor enforced by it, which means we can't be sure that they are complete. At least some more cases were noted by Ralph.

  15. fanquake force-pushed on Nov 12, 2026
  16. hebasto approved
  17. hebasto commented at 12:02 PM on November 12, 2026: member

    ACK 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.
    
  18. fanquake force-pushed on Nov 12, 2026
  19. DrahtBot added the label CI failed on Nov 12, 2026
  20. hebasto approved
  21. hebasto commented at 12:21 PM on November 12, 2026: member

    ACK 651d4b65cdc53c8da5983ff442ff76b8a0dc4e78.

  22. DrahtBot removed the label CI failed on Nov 12, 2026
  23. fanquake requested review from willcl-ark on Nov 12, 2026
  24. doc: fix incorrect @param annotations 6a0a221271
  25. doc: 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.
    ab7b1abc62
  26. doc: use @param and @return in subprocess.h cbd28fa468
  27. doc: 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.
    b64432d28c
  28. build: 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.
    ```
    08b6dcba33
  29. 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/append
    

    and perhaps L38 too?


    fanquake commented at 7:09 PM on November 12, 2026:

    Pushed.

  30. fanquake force-pushed on Nov 12, 2026
  31. fanquake requested review from hebasto on Nov 18, 2026

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