From 76672a967aaf6a197520ea9868d8a524fb39330d Mon Sep 17 00:00:00 2001
From: willcl-ark <will@256k1.dev>
Date: Sun, 13 Oct 2024 08:59:33 +0100
Subject: [PATCH] doc: doxygen comment for m_args usage in tests

Closes: #25055

Add doxygen comment to the m_args member in the unit test framework,
clarifying its purpose and providing usage guidelines.
---
 src/test/util/setup_common.h | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/test/util/setup_common.h b/src/test/util/setup_common.h
index f5a3c0dcee17c3..25289bfc75b010 100644
--- a/src/test/util/setup_common.h
+++ b/src/test/util/setup_common.h
@@ -75,6 +75,23 @@ struct BasicTestingSetup {
     fs::path m_path_root;
     fs::path m_path_lock;
     bool m_has_custom_datadir{false};
+    /**
+     * @brief Test-specific arguments and settings.
+     *
+     * This member is intended to be the primary source of settings for code being
+     * tested by unit tests. It exists to make tests more self-contained and reduce
+     * reliance on global state.
+     *
+     * Usage guidelines:
+     * 1. Prefer using m_args where possible in test code.
+     * 2. If m_args is not accessible, use m_node.args as a fallback.
+     * 3. Avoid direct references to gArgs in test code.
+     *
+     * Note: Currently, m_node.args points to gArgs for backwards compatibility.
+     * In the future, it will point to m_args to further isolate test environments.
+     *
+     * @see https://github.com/bitcoin/bitcoin/pull/21244#discussion_r615307465 for additional context.
+     */
     ArgsManager m_args;
 };