[clang] [clang-tools-extra] [llvm] [clang] Introduce diagnostics suppression mappings (PR #112517)

[Aaron Ballman via cfe-commits]

================
@@ -0,0 +1,92 @@
+============================
+Warning suppression mappings
+============================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+Warning suppression mappings enables users to suppress clang's diagnostics in a
+per-file granular manner. Enabling enforcement of diagnostics in specific parts
+of the project, even if there are violations in dependencies or other parts of
+the codebase.
+
+Goal and usage
+==============
+
+Clang allows diagnostics to be configured at a translation-unit granularity.
+If a foo.cpp is compiled with -Wfoo, all transitively included headers also need
+to be clean. Hence turning on new warnings at large codebases is quite difficult
+today:
+- It requires cleaning up all the existing warnings, which might not be possible
+  when some dependencies aren't in project owner's control.
+- Preventing backsliding in the meanwhile as the diagnostic can't be enforced at
+  all until codebase is cleaned up.
+
+Warning suppression mappings aims to alleviate some of these concerns by making
+diagnostic configuration granularity finer, at a source file level.
+
+To achieve this, user may create a file listing which diagnostic groups to
+suppress in which files, and pass it as a command line argument to clang with
+``--warning-suppression-mappings`` flag.
+
+Note that this mechanism won't enable any diagnostics on its own. Users should
+still turn on warnings in their compilations with explicit ``-Wfoo`` flags.
+
+Example
+=======
+
+.. code-block:: bash
+
+  $ cat my/user/code.cpp
+  #include <foo/bar.h>
+  namespace { void unused_func1(); }
+
+  $ cat foo/bar.h
+  namespace { void unused_func2(); }
+
+  $ cat suppression_mappings.txt
+  # Suppress -Wunused warnings in all files, apart from the ones under `foo/`.
+  [unused]
+  src:*
+  src:*foo/*=emit
+  $ clang -Wunused --warning-suppression-mappings=suppression_mappings.txt my/user/code.cpp
+  # prints warning: unused function 'unused_func2', but no warnings for `unused_func1`.
+
+Format
+======
+
+Warning suppression mappings uses a format similar to
----------------
AaronBallman wrote:

"similar to" really worries me; if it's not "the same as" then it's adding a truly custom format.

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