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

[Aaron Ballman via cfe-commits]

================
@@ -1315,6 +1319,32 @@ with its corresponding `Wno-` option.
 Note that when combined with :option:`-w` (which disables all warnings),
 disabling all warnings wins.
 
+.. _warning_suppression_mappings:
+
+Controlling Diagnostics via Suppression Mappings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Warning suppression mappings enable 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 some headers.
+
+.. code-block:: console
+
+  $ cat mappings.txt
+  [unused]
+  src:foo/*
+
+  $ clang --warning-suppression-mappings=mapping.txt -Wunused foo/bar.cc
+  # This compilation won't emit any unused findings for sources under foo/
+  # directory. But it'll still complain for all the other sources, e.g:
+  $ cat foo/bar.cc
+  #include "dir/include.h" // clang flags unused declarations here.
+  #include "foo/include.h" // but unused warnings under this source is omitted.
+
+
----------------
AaronBallman wrote:

```suggestion
  $ cat foo/bar.cc
  #include "dir/include.h" // Clang flags unused declarations here
  #include "foo/include.h" // but unused warnings from this header are omitted
  #include "next_to_bar_cc.h" // as are unused warnings from this header file.
  // Further, unused warnings in the remainder of bar.cc are also omitted.


```

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