doc: Fix Doxygen attribution of file-level comments #36815

hebasto commented at 2:13 PM on November 9, 2026: member

Doxygen attaches a comment block that lacks a @file command to the next declaration rather than to the file.

For example: <img width="742" height="265" alt="image" src="https://github.com/user-attachments/assets/eb555197-eb33-41e8-abcb-3a03afa8a5ff" />

This PR fixes that.

Requested in #36805 (review):

... they are wrong, ... it may be best to fix them instead of ignoring them?

Required for #36805.

hebasto added the label Docs on Nov 9, 2026

DrahtBot commented at 2:13 PM on November 9, 2026: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

External sites

Code coverage & benchmarks: https://corecheck.dev/bitcoin/bitcoin/pulls/36815
Ralph review <img src=https://review.fish.foo/assets/bitcoin/bitcoin/36815.png alt="Ralph review status"> https://git.fish.foo/bitcoin/bitcoin/pulls/36815#author-ralph

Reviews

See the guideline and AI policy for information on the review process.

Type	Reviewers
ACK	fanquake
Stale ACK	maflcko

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.

maflcko commented at 2:35 PM on November 9, 2026: member

review ACK b8a07768e2b479b008e027fc13ccb379f022dada 🏡

<details><summary>Show signature</summary>

Signature:

untrusted comment: signature from minisign secret key on empty file; verify via: minisign -Vm "${path_to_any_empty_file}" -P RWTRmVTMeKV5noAMqVlsMugDDCyyTSbA3Re5AkUrhvLVln0tSaFWglOw -x "${path_to_this_whole_four_line_signature_blob}"
RUTRmVTMeKV5npGrKx1nqXCw5zeVHdtdYURB/KlyA/LMFgpNCs+SkW9a8N95d+U4AP1RJMi+krxU1A3Yux4bpwZNLvVBKy0wLgM=
trusted comment: review ACK b8a07768e2b479b008e027fc13ccb379f022dada 🏡
pbPL/v/FX8CFRTOzW0HoWs0XDUrtD8jqOKV6/lhw+nFarBgcYimivnuBp4pYtFwnIU7pDQzrRdXICTmVmvKvBg==

</details>

in src/base58.h:6 in b8a07768e2

   9 | - *      could be used to create visually identical looking data.
  10 | - * - A string with non-alphanumeric characters is not as easily accepted as input.
  11 | - * - E-mail usually won't line-break if there's no punctuation to break at.
  12 | - * - Double-clicking selects the whole string as one word if it's all alphanumeric.
  13 | - */
  14 | +// Why base-58 instead of standard base-64 encoding?

fanquake commented at 2:46 PM on November 9, 2026:

Forgot about this one?

hebasto commented at 2:49 PM on November 9, 2026:

If you mean @file, then I didn't. I see this comment as a design note rather than a file description.

fanquake commented at 2:58 PM on November 9, 2026:

Sure, but we could include the design note in the docs, rather than hiding it? i.e something like:

diff --git a/src/base58.h b/src/base58.h
index bca3c07701..65ac61f1ac 100644
--- a/src/base58.h
+++ b/src/base58.h
@@ -4,6 +4,9 @@
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
 /**
+ * [@file](/bitcoin-bitcoin/contributor/file/)
+ * Base58 and Base58Check encoding and decoding.
+ *
  * Why base-58 instead of standard base-64 encoding?
  * - Don't want 0OIl characters that look the same in some fonts and
  *      could be used to create visually identical looking data.

fanquake commented at 2:47 PM on November 9, 2026: member

If the idea is to consolidate these (onto one style?) looks like a number were missed, i.e: https://github.com/bitcoin/bitcoin/blob/44901d8f64cb617714707bd025ecd83f108353c2/src/util/task_runner.h#L13

https://github.com/bitcoin/bitcoin/blob/44901d8f64cb617714707bd025ecd83f108353c2/src/common/types.h#L5

https://github.com/bitcoin/bitcoin/blob/44901d8f64cb617714707bd025ecd83f108353c2/src/wallet/types.h#L6

hebasto commented at 2:53 PM on November 9, 2026: member

If the idea is to consolidate these (onto one style?) looks like a number were missed...

The initial motivation was to remove all comments that start with /* from between a copyright banner and an include guard to simplify the linter code in #36805.

This PR provides the minimal diff to achieve that aim.

And these changes are real fixes for the Doxygen-generated docs rather than pure style changes.

fanquake commented at 3:07 PM on November 9, 2026: member

And these changes are real fixes for the Doxygen-generated docs rather than pure style changes.

The @file instances I linked to (plus others) also need fixing. i.e master: <img width="1400" height="171" alt="master" src="https://github.com/user-attachments/assets/892fcd4e-616c-4086-8745-b0de98deb972" />

vs the below diff:

diff --git a/src/common/messages.h b/src/common/messages.h
index 6a2752521f..eb9f19a77c 100644
--- a/src/common/messages.h
+++ b/src/common/messages.h
@@ -3,9 +3,11 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-//! [@file](/bitcoin-bitcoin/contributor/file/) common/messages.h is a home for simple string functions returning
-//! descriptive messages that are used in RPC and GUI interfaces or log
-//! messages, and are called in different parts of the codebase across
+//! [@file](/bitcoin-bitcoin/contributor/file/)
+//! [@brief](/bitcoin-bitcoin/contributor/brief/) Home for simple string functions returning descriptive messages.
+//!
+//! The messages are used in RPC and GUI interfaces or log messages, and the
+//! functions are called in different parts of the codebase across
 //! node/wallet/gui boundaries.
 
 #ifndef BITCOIN_COMMON_MESSAGES_H
diff --git a/src/common/types.h b/src/common/types.h
index 1ffcd392d6..e570089601 100644
--- a/src/common/types.h
+++ b/src/common/types.h
@@ -2,8 +2,10 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-//! [@file](/bitcoin-bitcoin/contributor/file/) common/types.h is a home for simple enum and struct type definitions
-//! that can be used internally by functions in the libbitcoin_common library,
+//! [@file](/bitcoin-bitcoin/contributor/file/)
+//! [@brief](/bitcoin-bitcoin/contributor/brief/) Home for simple enum and struct type definitions.
+//!
+//! These can be used internally by functions in the libbitcoin_common library,
 //! but also used externally by node, wallet, and GUI code.
 //!
 //! This file is intended to define only simple types that do not have external
diff --git a/src/ipc/types.h b/src/ipc/types.h
index ac89a9bf43..f8ba2fb628 100644
--- a/src/ipc/types.h
+++ b/src/ipc/types.h
@@ -2,8 +2,10 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-//! [@file](/bitcoin-bitcoin/contributor/file/) ipc/types.h is a home for public enum and struct type definitions
-//! that are used internally by ipc code, but also used externally by wallet,
+//! [@file](/bitcoin-bitcoin/contributor/file/)
+//! [@brief](/bitcoin-bitcoin/contributor/brief/) Home for public enum and struct type definitions.
+//!
+//! These are used internally by ipc code, but also used externally by wallet,
 //! mining or GUI code.
 //!
 //! This file is intended to define only simple types that do not have external
diff --git a/src/kernel/types.h b/src/kernel/types.h
index 164d4cfda8..6c5ee5b2d9 100644
--- a/src/kernel/types.h
+++ b/src/kernel/types.h
@@ -2,8 +2,10 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-//! [@file](/bitcoin-bitcoin/contributor/file/) kernel/types.h is a home for simple enum and struct type definitions
-//! that can be used internally by functions in the libbitcoin_kernel library,
+//! [@file](/bitcoin-bitcoin/contributor/file/)
+//! [@brief](/bitcoin-bitcoin/contributor/brief/) Home for simple enum and struct type definitions.
+//!
+//! These can be used internally by functions in the libbitcoin_kernel library,
 //! but also used externally by node, wallet, and GUI code.
 //!
 //! This file is intended to define only simple types that do not have external
diff --git a/src/node/mining_types.h b/src/node/mining_types.h
index 6e4eb82aa9..319341f562 100644
--- a/src/node/mining_types.h
+++ b/src/node/mining_types.h
@@ -2,8 +2,11 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-//! [@file](/bitcoin-bitcoin/contributor/file/) node/mining_types.h is used externally by mining IPC clients, so it should
-//! only declare simple data definitions.
+//! [@file](/bitcoin-bitcoin/contributor/file/)
+//! [@brief](/bitcoin-bitcoin/contributor/brief/) Simple data definitions used by mining IPC clients.
+//!
+//! This file is used externally by mining IPC clients, so it should only
+//! declare simple data definitions.
 //!
 //! Avoid declaring functions or classes with methods here unless they are
 //! header-only or provided by the util library.
diff --git a/src/node/types.h b/src/node/types.h
index 1003b42ca7..8e0bb29578 100644
--- a/src/node/types.h
+++ b/src/node/types.h
@@ -2,8 +2,10 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-//! [@file](/bitcoin-bitcoin/contributor/file/) node/types.h is a home for public enum and struct type definitions
-//! that are used internally by node code, but also used externally by wallet,
+//! [@file](/bitcoin-bitcoin/contributor/file/)
+//! [@brief](/bitcoin-bitcoin/contributor/brief/) Home for public enum and struct type definitions.
+//!
+//! These are used internally by node code, but also used externally by wallet,
 //! mining or GUI code.
 //!
 //! This file is intended to define only simple types that do not have external
diff --git a/src/wallet/types.h b/src/wallet/types.h
index 6ba9a1dbde..0b565fc402 100644
--- a/src/wallet/types.h
+++ b/src/wallet/types.h
@@ -3,8 +3,10 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-//! [@file](/bitcoin-bitcoin/contributor/file/) wallet/types.h is a home for public enum and struct type definitions
-//! that are used by internally by wallet code, but also used externally by node
+//! [@file](/bitcoin-bitcoin/contributor/file/)
+//! [@brief](/bitcoin-bitcoin/contributor/brief/) Home for public enum and struct type definitions.
+//!
+//! These are used internally by wallet code, but also used externally by node
 //! or GUI code.
 //!
 //! This file is intended to define only simple types that do not have external

doc: Fix Doxygen attribution of file-level comments

Without an explicit @file command, Doxygen attached these comments to
the next declaration.

c7ebbbba6c

doc: Fix `@file` descriptions that start with the file name

Doxygen treats the word after `@file` as the name of the documented
file and drops it from the text. Use a bare `@file` and `@brief`
instead.

Co-Authored-By: fanquake <fanquake@gmail.com>

4cb432772c

doc: Attach `subprocess.h` header comment to the file

Add `@file` and `@brief` so Doxygen documents the file rather than the
`subprocess_close` macro.

Also move the whole comment block inside the include guard. This
simplifies upcoming changes to the include guard linter.

c4a68cc5ce

hebasto force-pushed on Nov 9, 2026

hebasto commented at 3:32 PM on November 9, 2026: member

@fanquake

Thank you for the review! Your feedback has been addressed.

fanquake commented at 4:41 PM on November 9, 2026: member

ACK c4a68cc5ceb62ac160b7adc44ebf6388aa803ed5

DrahtBot requested review from maflcko on Nov 9, 2026