doc: languages: add new section "headers and C/C++ compatibility"

Writing headers compatible with both C and C++ _and_ a range of
toolchains can be very challenging, see for instance long discussions in
commit c15f029a ("init.h: restore designated initializers in
SYS_INIT_NAMED()"), PR #69411 and a few others linked from there.

Signed-off-by: Marc Herbert <marc.herbert@intel.com>