Merge bitcoin/bitcoin#34319: Drop some IWYU pragma: export and document IWYU usage

d938947b3a89a61784a72c533df623f9eb2fec49 doc: Add "Using IWYU" to Developer Notes (Hennadii Stepanov)
e1a90bcecc823a4abaa2a57f393cad675a2ccbc0 iwyu: Do not export `crypto/hex_base.h` header (Hennadii Stepanov)
19a2edde50c38412712306bf527faad6cbf81c2c iwyu: Do not export C++ headers in most cases (Hennadii Stepanov)

Pull request description:

  First two commits address comments from discussion in https://github.com/bitcoin/bitcoin/pull/33779:
  - https://github.com/bitcoin/bitcoin/pull/33779#discussion_r2697579248
  - https://github.com/bitcoin/bitcoin/pull/33779#discussion_r2697707343

  The last commit adds a new section to the Developer Notes to document IWYU usage.

ACKs for top commit:
  maflcko:
    re-ACK d938947b3a89a61784a72c533df623f9eb2fec49 🚀

Tree-SHA512: 8d6c63e9d2fd190815211d80e654cb7379d16b6611b8851444f49bbbaa0fbc93557675fbcc558afd9a1cdf643570fba5eff9c1aecb5530f978797387b10b9a11

doc/developer-notes.md

@@ -558,6 +558,21 @@ llvm-cov show \
 
 The generated coverage report can be accessed at `build/coverage_report/index.html`.
 
+### Using IWYU
+
+The [`include-what-you-use`](https://github.com/include-what-you-use/include-what-you-use) tool (IWYU)
+helps to enforce the source code organization [policy](#source-code-organization) in this repository.
+
+To ensure consistency, it is recommended to run the IWYU CI job locally rather than running the tool directly.
+
+In some cases, IWYU might suggest headers that seem unnecessary at first glance, but are actually required.
+For example, a macro may use a symbol that requires its own include. Another example is passing a string literal
+to a function that accepts a `std::string` parameter. An implicit conversion occurs at the callsite using the
+`std::string` constructor, which makes the corresponding header required. We accept these suggestions as is.
+
+Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers
+and undermines the specific purpose of IWYU.
+
 ### Performance profiling with perf
 
 Profiling is a good way to get a precise idea of where time is being spent in
@@ -1057,7 +1072,7 @@ Write scripts in Python or Rust rather than bash, when possible.
 
   - *Rationale*: Excluding headers because they are already indirectly included results in compilation
     failures when those indirect dependencies change. Furthermore, it obscures what the real code
-    dependencies are.
+    dependencies are. The [Using IWYU](#using-iwyu) section describes a tool to help enforce this.
 
 - Don't import anything into the global namespace (`using namespace ...`). Use
   fully specified types such as `std::string`.

src/core_io.cpp

@@ -9,6 +9,7 @@
 #include <consensus/amount.h>
 #include <consensus/consensus.h>
 #include <consensus/validation.h>
+#include <crypto/hex_base.h>
 #include <key_io.h>
 // IWYU incorrectly suggests replacing this header
 // with forward declarations.

src/kernel/chainparams.cpp

@@ -9,6 +9,7 @@
 #include <consensus/amount.h>
 #include <consensus/merkle.h>
 #include <consensus/params.h>
+#include <crypto/hex_base.h>
 #include <hash.h>
 #include <kernel/messagestartchars.h>
 #include <logging.h>

src/node/blockstorage.cpp

@@ -7,6 +7,7 @@
 #include <arith_uint256.h>
 #include <chain.h>
 #include <consensus/params.h>
+#include <crypto/hex_base.h>
 #include <dbwrapper.h>
 #include <flatfile.h>
 #include <hash.h>

src/util/strencodings.h

@@ -9,7 +9,7 @@
 #ifndef BITCOIN_UTIL_STRENCODINGS_H
 #define BITCOIN_UTIL_STRENCODINGS_H
 
-#include <crypto/hex_base.h> // IWYU pragma: export
+#include <crypto/hex_base.h>
 #include <span.h>
 #include <util/string.h>
 
@@ -20,8 +20,8 @@
 #include <cstdint>
 #include <limits>
 #include <optional>
-#include <string>      // IWYU pragma: export
-#include <string_view> // IWYU pragma: export
+#include <string>
+#include <string_view>
 #include <system_error>
 #include <type_traits>
 #include <vector>

src/util/string.h

@@ -12,8 +12,8 @@
 #include <cstring>
 #include <locale>
 #include <sstream>
-#include <string>      // IWYU pragma: export
-#include <string_view> // IWYU pragma: export
+#include <string>
+#include <string_view>
 #include <vector>
 
 namespace util {