Merge bitcoin/bitcoin#36815: doc: Fix Doxygen attribution of file-level comments
What changed, and why it matters
This commit only fixes documentation comments in 12 source-code header files so that the Doxygen documentation generator correctly attributes file-level descriptions. No program logic, compiled code, or security behavior is changed. There is no security risk.
No security action required. Treat as a normal documentation cleanup.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The merge commit applies three documentation-only changes: adding explicit @file / @brief markers, moving a header guard above a Doxygen comment in src/util/subprocess.h, and reformatting existing prose. All modifications are inside C++ comment blocks and do not alter preprocessor directives beyond reordering the guard in one file. No executable code, interfaces, or build outputs are affected.
Changed components
src/base58.hsrc/common/messages.hsrc/common/types.hsrc/ipc/types.hsrc/kernel/types.hsrc/node/mining_types.hsrc/node/types.hsrc/torcontrol.hsrc/util/moneystr.hsrc/util/strencodings.hsrc/util/subprocess.hsrc/wallet/types.hInspect captured patch +54 / −35
### src/base58.h
@@ -3,14 +3,16 @@
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
-/**
- * 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.
- * - A string with non-alphanumeric characters is not as easily accepted as input.
- * - E-mail usually won't line-break if there's no punctuation to break at.
- * - Double-clicking selects the whole string as one word if it's all alphanumeric.
- */
+//! @file
+//! @brief 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.
+//! - A string with non-alphanumeric characters is not as easily accepted as input.
+//! - E-mail usually won't line-break if there's no punctuation to break at.
+//! - Double-clicking selects the whole string as one word if it's all alphanumeric.
+
#ifndef BITCOIN_BASE58_H
#define BITCOIN_BASE58_H
### 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 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
+//! @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
### 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 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
+//! @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
### 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 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
+//! @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
### 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 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
+//! @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
### 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 node/mining_types.h is used externally by mining IPC clients, so it should
-//! only declare simple data definitions.
+//! @file
+//! @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.
### 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 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
+//! @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
### src/torcontrol.h
@@ -2,9 +2,9 @@
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
-/**
- * Functionality for communicating with Tor.
- */
+//! @file
+//! @brief Functionality for communicating with Tor.
+
#ifndef BITCOIN_TORCONTROL_H
#define BITCOIN_TORCONTROL_H
### src/util/moneystr.h
@@ -3,9 +3,9 @@
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
-/**
- * Money parsing/formatting utilities.
- */
+//! @file
+//! @brief Money parsing/formatting utilities.
+
#ifndef BITCOIN_UTIL_MONEYSTR_H
#define BITCOIN_UTIL_MONEYSTR_H
### src/util/strencodings.h
@@ -3,9 +3,9 @@
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
-/**
- * Utilities for converting data from/to strings.
- */
+//! @file
+//! @brief Utilities for converting data from/to strings.
+
#ifndef BITCOIN_UTIL_STRENCODINGS_H
#define BITCOIN_UTIL_STRENCODINGS_H
### src/util/subprocess.h
@@ -1,6 +1,11 @@
// Based on the https://github.com/arun11299/cpp-subprocess project.
+#ifndef BITCOIN_UTIL_SUBPROCESS_H
+#define BITCOIN_UTIL_SUBPROCESS_H
+
/*!
+@file
+@brief C++ subprocessing library.
Documentation for C++ subprocessing library.
@@ -33,9 +38,6 @@ Documentation for C++ subprocessing library.
@version 1.0.0
*/
-#ifndef BITCOIN_UTIL_SUBPROCESS_H
-#define BITCOIN_UTIL_SUBPROCESS_H
-
#include <util/check.h>
#include <util/syserror.h>
### 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 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
+//! @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 externalWhy this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.