doc: Fix `@file` descriptions that start with the file name
What changed, and why it matters
This commit is a pure documentation fix. It changes how Doxygen (a tool that generates documentation from source code comments) interprets file descriptions in seven header files. There is no change to actual program code, behavior, or security.
No security action required. This is a routine documentation-quality improvement.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch corrects Doxygen @file comment blocks. Previously the filename was placed on the same line as @file, causing Doxygen to treat it as the documented filename and drop it from the descriptive text. The fix uses a bare @file followed by @brief and moves the description to subsequent lines. Only comments are modified; no executable code, data structures, or interfaces change.
Changed components
src/common/messages.hsrc/common/types.hsrc/ipc/types.hsrc/kernel/types.hsrc/node/mining_types.hsrc/node/types.hsrc/wallet/types.hInspect captured patch +30 / −15
### 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/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.