[clang] [Clang] Add #pragma clang deprecated_header (PR #168041)

[Aaron Ballman via cfe-commits]

https://github.com/AaronBallman commented:

Overall, I like the idea, but I wonder if a pragma is really the best way forward in 2025. I can imagine standards committees wanting this functionality, and a pragma would likely be just fine in C, but not acceptable in C++.

Did you consider using an attribute instead? e.g., `[[clang::deprecated("this header is deprecated")]];` on a null statement in a header file could be a viable approach that both committees would be interested in standardizing under the existing `[[deprecated]]` attribute.

Some things the PR needs to consider:

* This needs documentation in the language extensions file. In particular, where within a header does the marking show up? Can it be anywhere? Just the "first semantic line" (non-comment, non-header guard)?
* What should happen if the deprecated header ends up including another deprecated header? Normally, deprecated things can reference other deprecated things on the assumption they're all being deprecated together. So perhaps the same is true here? Is it true if deprecated header A includes non-deprecated header B which then includes deprecated header C though?
* We usually suppress diagnostics coming from system headers but this one kind of spans the idea. The system header specifies the diagnostic should happen but the diagnostic itself happens on the inclusion line which may be user code. We need test coverage to make sure user code does get the diagnostic and system headers do not.
* What happens if the marking is used in a module that is imported? I would imagine we'd want the same diagnostic behavior? Perhaps another reason the name should be under `deprecated` rather than `deprecated_header`?

https://github.com/llvm/llvm-project/pull/168041