[clang] [clang][docs] assert.h is not a good candidate for a textual header (PR #165057)

[Michael Spencer via cfe-commits]

Bigcheese wrote:

The problem is that there's a lot of code that uses `<assert.h>` in a modular way, only defining `NDEBUG` on the command line, but there's also a lot of code that does `#define NDEBUG`. Only one of these ways can practicably work in a module.

Maybe it would be best if we had a way to keep `<assert.h>` textual, but error if the state of `NDEBUG` has changed in a context where that breaks things. I think we could do that without any compiler changes by defining the two versions of the `assert` macro in different modules which `conflict` each other, and then using `<assert.h>` to select which one to import. This wouldn't handle the case of only indirect import via other modules though. To handle that we would need a stronger form of `config_macros` that handles the transitive case, so:

```cpp
#define NDEBUG // or #undef NDEBUG
#include <modular_header_that_has_an_assert.h>
```

can emit an error if `NDEBUG` doesn't match what's in the module.

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