#36704 doc: fix docs and enable `-Wdocumentation-unknown-command`

ReviewabilityReviewsAgreementSize
#36704 fanquake doc: fix docs and enable `-Wdocumentation-unknown-command`Ready0Crickets36
  • Catch misspelled and unrecognized Doxygen tags automatically during compilation
  • Fix existing Doxygen syntax mistakes and formatting errors across the codebase
  • Ready for review
  • Nothing known that would invalidate a review now
  • No review verdicts recorded
  • No substantive review comments or feedback yet
  • Awaiting initial community review
  • 36 lines added or modified outside tests
  • 0 lines added or modified in tests
  • 30 lines removed in total
  • 13 files, 3 commits
Build and CI#51 of 56
P4 · cleanup
  • P4 because documentation warning hygiene is minor compared to build integrity
  • Adds a compiler warning flag without altering build output or platform support
Documentation#8 of 9
P4 · cleanup
  • P4 because syntax cleanup and typo fixes do not change underlying technical meaning
  • Ensures comments are correctly formatted and parsed by documentation tooling
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

Corrects Doxygen comment syntax across the codebase and enables Clang's `-Wdocumentation-unknown-command` compiler warning in CMake. It escapes literal backslashes in comments, converts standard `/*` comment blocks containing tags into Doxygen `/**` blocks, wraps ASCII diagrams in `@verbatim`, and fixes misspelled or inaccurate `@param` directions.

Problem: Misspelled Doxygen tags (such as `@peer[in]`) and unescaped backslashes in documentation comments are not flagged by Clang's `-Wdocumentation` warning alone. Additionally, Doxygen tags located inside plain `/*` comment blocks are skipped entirely by both Doxygen and compiler diagnostics, leaving documentation mistakes undetected.

Evidence of importance:

  • Commit 2c8c91c5a0 demonstrates that `-Wdocumentation-unknown-command` catches misspelled tags like `@peer[in]` in `src/net_processing.cpp:717` that `-Wdocumentation` alone ignored.

Risk of a mistake: low (build, docs). Only comments and warning flags are touched; mistakes could at most cause unexpected build warnings on specific Clang versions.

Changed since the previous assessment: Diff inspected; the commits match the previous description across 12 source files and CMakeLists.txt.

Reviewability

Ready

Nothing known that would invalidate a review now.

Agreement

Crickets

no substantive comment either way

Objections, suggestions, and questions: none recorded.

Files

0 lines under test/bench/ci.

  • src/wallet/coinselection.cpp +20/-15
  • src/psbt.h +2/-2
  • src/qt/sendcoinsdialog.h +2/-2
  • src/streams.h +2/-2
  • src/util/strencodings.h +2/-2
  • src/kernel/bitcoinkernel.h +1/-1
  • src/net_processing.cpp +1/-1
  • src/qt/bitcoingui.h +1/-1
  • src/torcontrol.cpp +1/-1
  • src/util/fs.h +1/-1
  • src/util/subprocess.h +1/-1
  • src/wallet/wallet.h +1/-1
  • CMakeLists.txt +1/-0

Card

The short text the ranking pass compares across PRs.

Fixes malformed Doxygen comment tags and enables the Clang compiler warning flag -Wdocumentation-unknown-command in CMake. Previously, misspelled tags like @peer[in], unescaped backslashes, or tags in standard C comments silently bypassed compiler checks and generated broken documentation. This change corrects existing comment errors across 12 files and ensures future syntax issues are caught at build time.

Data

dossier JSON · extract JSON · model ledger, generated 2026-11-01T01:16, confidence high, input hash a225324ec32f4b42
labels: Docs

Categories

Build and CI

P4 · cleanup

Enables an extra Clang warning flag in the build system to catch unknown Doxygen commands. Compiler warning hygiene for documentation tags is low priority in the build system compared to platform support or build integrity.

Membership: Adds `-Wdocumentation-unknown-command` compiler warning to `CMakeLists.txt`.

Factors: security/stability 0, bug 0, performance 0, user value 0, leverage 0

Documentation

P4 · cleanup

Corrects formatting and syntax errors in Doxygen tags to satisfy compiler checks. In the documentation category, comment syntax and typo fixes that do not change underlying technical meaning rank as P4.

Membership: Labeled 'Docs' and updates Doxygen comment syntax across 12 source files.

Factors: security/stability 0, bug 0, performance 0, user value 0, leverage 0