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

[Ian Anderson via cfe-commits]

ian-twilightcoder 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:
> 
> ```c++
> #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.

Wouldn't that just result in an error if I did this?
```
#include <modular_header_that_has_an_assert.h> // expects no NDEBUG - selects the assert_enabled module
#define NDEBUG
#include <assert.h> // selects the assert_disabled module, kaboom conflicting module error
```

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