doc: Document rationale for using `IWYU pragma: export`
What the developer wrote
Authored by Hennadii Stepanov
doc: Document rationale for using `IWYU pragma: export`
What changed, and why it matters
This commit only adds documentation to the developer notes. It explains when and why developers may use a specific code-comment directive (`IWYU pragma: export`) for header files. There is no code change, no bug fix, and no security relevance.
No action needed. This is a documentation-only change with no security implications.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The patch appends a short rationale to doc/developer-notes.md describing acceptable cases for IWYU pragma: export (facade headers, drop-in replacement headers, and presenting a complete interface across multiple headers). It is purely a documentation update with no source-code modifications.
Changed components
doc/developer-notes.mdInspect captured patch +7 / −0
diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index d8ce01c8..399fcbd0 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -542,6 +542,13 @@ to a function that accepts a `std::string` parameter. An implicit conversion occ
Use `IWYU pragma: export` very sparingly, as this enforces transitive inclusion of headers
and undermines the specific purpose of IWYU.
+The acceptable cases for using `IWYU pragma: export` are:
+1. Facade headers. For example, see [`compat/compat.h`](/src/compat/compat.h).
+2. Drop-in replacement headers. For example, see [`util/time.h`](/src/util/time.h).
+3. Presenting a complete interface across multiple headers.
+
+A comment explaining the rationale is required for every use of `IWYU pragma: export`.
+
### Performance profiling with perf
Profiling is a good way to get a precise idea of where time is being spent in
Why 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.