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

[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 disable 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
+
+   * - Method
+     - Specified at?
+     - Scope
+     - Run-time cost
+     - Description
+   * - ``ScopedDisabler``
+     - Compile-time
+     - Stack
+     - Very low
+     - Violations are ignored for the lifetime of the ``ScopedDisabler`` object.
+   * - ``function-name-matches`` suppression
+     - Run-time
+     - Single function
+     - Medium
+     - Suppresses intercepted and ``[[clang::blocking]]`` function calls by name.
+   * - ``call-stack-contains`` suppression
+     - Run-time
+     - Stack
+     - High
+     - Suppresses any stack trace contaning the specified pattern.
+    
+
+``ScopedDisabler``
+##################
+
+At compile time, RealtimeSanitizer may be disabled using ``__rtsan::ScopedDisabler``. Within the scope where the ``ScopedDisabler`` object is instantiated, all potential RTSan errors are ignored for that thread including all invoked functions, and any functions called transitively.
----------------
davidtrevelyan wrote:

Minor nits: not sure the word "potential" adds value here (it raises questions), and I think "for that thread" and "invoked functions" are a given as we're already talking about a variable scope. I'd propose a simplification as follows:

_All RTSan errors originating within the ``ScopedDisabler`` instance variable scope are ignored._

I don't feel strongly though, if you feel this is less clear - no worries.

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