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

[Boaz Brickner via cfe-commits]

================
@@ -0,0 +1,90 @@
+============================
+Warning suppression mappings
+============================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+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.
+
+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 in large codebases can be
+difficult today. Since it requires cleaning up all the existing warnings,
----------------
bricknerb wrote:

RE "today": If this documentation should describe what the feature is and how to use, I wouldn't refer to "today" as if we don't have the feature.

Also, instead of "difficult" I would just continue to the next sentence to say it requires cleaning ...

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