[clang] [clang] Update documentation for `#pragma diagnostic` (PR #78095)

[Aaron Ballman via cfe-commits]

================
@@ -1157,23 +1158,34 @@ existed.
   #if foo
   #endif foo // warning: extra tokens at end of #endif directive
 
-  #pragma clang diagnostic push
-  #pragma clang diagnostic ignored "-Wextra-tokens"
+  #pragma GCC diagnostic push
+  #pragma GCC diagnostic ignored "-Wextra-tokens"
 
   #if foo
   #endif foo // no warning
 
-  #pragma clang diagnostic pop
+  #pragma GCC diagnostic pop
 
 The push and pop pragmas will save and restore the full diagnostic state
-of the compiler, regardless of how it was set. That means that it is
-possible to use push and pop around GCC compatible diagnostics and Clang
-will push and pop them appropriately, while GCC will ignore the pushes
-and pops as unknown pragmas. It should be noted that while Clang
+of the compiler, regardless of how it was set. It should be noted that while Clang
 supports the GCC pragma, Clang and GCC do not support the exact same set
 of warnings, so even when using GCC compatible #pragmas there is no
 guarantee that they will have identical behaviour on both compilers.
 
+Clang also doesn't yet support GCC behavior for ``#pragma diagnostic pop``
+that doesn't have a corresponding ``#pragma diagnostic push``. In this case
+GCC pretends that there is a ``#pragma diagnostic push`` at the very beginning
+of the source file, so "unpaired" ``#pragma diagnostic pop`` matches that
+implicit push. This makes a difference for ``#pragma GCC diagnostic ignored``
+which are not guarded by push and pop. Refer to
+`GCC documentation <https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html>`_
+for details.
+
+Like GCC, Clang accepts ``ignored``, ``warning``, ``error``, and ``fatal``
+severity levels. They can be used to change severity of a particular diagnostic
+for a region of source file. Notable difference from GCC is that diagnostic
+not enabled via CLI arguments can't be enabled this way yet.
----------------
AaronBallman wrote:

```suggestion
for a region of source file. A notable difference from GCC is that diagnostic
not enabled via command line arguments can't be enabled this way yet.
```

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