compilers: improve a comment describing why we add a silly clang workaround

Clang is such a great compiler! Not.

Compilers have enhanced diagnostics for some kinds of "well known"
undeclared identifiers, telling you exactly which header you might have
forgotten to include. The reason why clang needs an option GCC doesn't
need is because clang's fixit suggestions, unlike GCC's actually
*changes the type of the error*, as a result of a fixit of all things.

After the fixit suggestion grants this error the right to be ignored,
we start having to add clang-specific options.

Follow-up to https://github.com/mesonbuild/meson/issues/9140

Upstream clang bug, which appears to be going nowhere:
https://github.com/llvm/llvm-project/issues/33905

1 files changed, 17 insertions, 3 deletions

diff --git a/mesonbuild/compilers/mixins/clang.py b/mesonbuild/compilers/mixins/clang.py
index f982509..a9bf566 100644
--- a/mesonbuild/compilers/mixins/clang.py
+++ b/mesonbuild/compilers/mixins/clang.py
@@ -77,9 +77,23 @@ class ClangCompiler(GnuLikeCompiler):
 
     def get_compiler_check_args(self, mode: CompileCheckMode) -> T.List[str]:
         # Clang is different than GCC, it will return True when a symbol isn't
-        # defined in a header. Specifically this seems to have something to do
-        # with functions that may be in a header on some systems, but not all of
-        # them. `strlcat` specifically with can trigger this.
+        # defined in a header. Specifically this is caused by a functionality
+        # both GCC and clang have: for some "well known" functions, arbitrarily
+        # chosen, they provide fixit suggestions for the header you should try
+        # including.
+        #
+        # - With GCC, this is a note appended to the prexisting diagnostic
+        #   "error: undeclared identifier"
+        #
+        # - With clang, the error is converted to a c89'ish implicit function
+        #   declaration instead, which can be disabled with -Wno-error and on
+        #   clang < 16, simply passes compilation by default.
+        #
+        # One example of a clang fixit suggestion is for `strlcat`, which
+        # triggers this.
+        #
+        # This was reported in 2017 and promptly fixed. Just kidding!
+        # https://github.com/llvm/llvm-project/issues/33905
         myargs: T.List[str] = ['-Werror=implicit-function-declaration']
         if mode is CompileCheckMode.COMPILE:
             myargs.extend(['-Werror=unknown-warning-option', '-Werror=unused-command-line-argument'])