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

The C standard behavior of `assert` cannot be accomplished with clang
modules, either as a normal modular header, or a textual header.

As a normal modular header:
#define NDEBUG
#include <assert.h>
This pattern doesn't work, NDEBUG has to be passed on the command line
to take effect, and then will effect all `assert`s in the includer.

As a textual header:
#define NDEBUG
#include <modular_header_that_has_an_assert.h>
This pattern doesn't work for similar reasons,
modular_header_that_has_an_assert.h captured the value of NDEBUG when
its module built and won't pick it up from the includer. -DNDEBUG can be
passed when building the module, but will similarly effect the entire
module. This has the additional problem that every module will contain a
declaration for `assert`, which can possibly conflict with each other if
they use different values of NDEBUG.

So really <assert.h> just doesn't work properly with clang modules.
Avoid the issue by not mentioning it in the Modules documentation, and
use "X macros" as the example for textual headers.

Don't use [extern_c] in the example modules, that should very rarely be
used. Don't put multiple `header` declarations in a submodule, that has
the confusing effect of "fusing" the headers. e.g. <sys/errno.h> does
not include <errno.h>, but if it's in the same submodule, then an
`#include <sys/errno.h>` will mysteriously also include <errno.h>.

0 files changed, 0 insertions, 0 deletions