#36704 doc: fix docs and enable `-Wdocumentation-unknown-command`
| Reviewability | Reviews | Agreement | Size | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
| #36704 doc: fix docs and enable `-Wdocumentation-unknown-command` | Ready | 0 | Crickets | 36 | ||||||
|
|
|
|
| ||||||
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
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