[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
----------------
cjappl wrote:

Yes, I'm amenable to this, but I started down this path then aborted.

My worry was providing too much low level unnecessary detail to the user, when a high level overview would suffice.

Given the info about what the actual cost is (vs "very low") how would I, the user, behave differently? Is additional (possibly complex to understand) knowledge about what is happening under the hood helpful? (honest question, I originally decided "no" but have definitely been turning this over in my head.

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