[clang] [rtsan][NFC] Documentation of suppression flag (PR #112727)

[Chris Apple via cfe-commits]

================
@@ -194,12 +198,43 @@ Some issues with flags can be debugged using the ``verbosity=$NUM`` flag:
    misspelled_flag
    ...
 
-Disabling
----------
+Disabling and suppressing
+-------------------------
 
-In some circumstances, you may want to suppress error reporting in a specific scope.
+There are multiple ways to suppress error reporting when using RealtimeSanitizer.
 
-In C++, this is achieved via  ``__rtsan::ScopedDisabler``. Within the scope where the ``ScopedDisabler`` object is instantiated, all sanitizer error reports are suppressed. This suppression applies to the current scope as well as all invoked functions, including any functions called transitively.
+In general, ``ScopedDisabler`` should be preferred, as it is the most performant.
+
+.. list-table:: Suppression methods
+   :widths: 30 15 15 10 70
+   :header-rows: 1
+
+   * - Suppression method
+     - Specified at?
+     - Scope
+     - Run-time cost
+     - Description
+   * - ``ScopedDisabler``
+     - Compile-time
+     - Stack
+     - Very low
+     - Suppresses all sanitizer error reports in the current scope and all invoked functions.
----------------
cjappl wrote:

Great thought. I'm not sure where I come down on it, but I'm also amenable to this change.

I guess the question is (similar to the above) "Is there a difference between suppressing and ignoring an issue? As a user do I care?"

I could see one case for calling everything suppressing (which is what I inadvertently did in this PR), or make the differentiation between suppressing (what a suppression file does) and ignoring (what the Disabler does).

To the end user, they do the same thing, to us, we behave differently and go through different mechanisms to achieve that same result. 

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