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

[Vlad Serebrennikov via cfe-commits]

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

>From 1aca1cd3be8209675b8aa3b79b2d626ad9f3c559 Mon Sep 17 00:00:00 2001
From: Vlad Serebrennikov <serebrennikov.vladislav at gmail.com>
Date: Sun, 14 Jan 2024 14:11:16 +0300
Subject: [PATCH 1/4] [clang] Remove outdated parts of documentation for
 #pragma diagnostic

GCC has changed over the past decade.
Fixes #51472
---
 clang/docs/UsersManual.rst | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index c6a6b06fc04be..22fbb6764e2f0 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1132,7 +1132,7 @@ Controlling Diagnostics via Pragmas
 Clang can also control what diagnostics are enabled through the use of
 pragmas in the source code. This is useful for turning off specific
 warnings in a section of source code. Clang supports GCC's pragma for
-compatibility with existing source code, as well as several extensions.
+compatibility with existing source code.
 
 The pragma may control any warning that can be used from the command
 line. Warnings may be set to ignored, warning, error, or fatal. The
@@ -1143,8 +1143,7 @@ warnings:
 
   #pragma GCC diagnostic ignored "-Wall"
 
-In addition to all of the functionality provided by GCC's pragma, Clang
-also allows you to push and pop the current warning state. This is
+Clang also allows you to push and pop the current warning state. This is
 particularly useful when writing a header file that will be compiled by
 other people, because you don't know what warning flags they build with.
 
@@ -1157,19 +1156,16 @@ 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.

>From 005db51edbe76f48b2097444f77b0ea48d541212 Mon Sep 17 00:00:00 2001
From: Vlad Serebrennikov <serebrennikov.vladislav at gmail.com>
Date: Wed, 17 Jan 2024 11:36:41 +0300
Subject: [PATCH 2/4] Clarify that we don't support some of GCC behavior

---
 clang/docs/UsersManual.rst | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 22fbb6764e2f0..9e8ffa760af92 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1132,7 +1132,9 @@ Controlling Diagnostics via Pragmas
 Clang can also control what diagnostics are enabled through the use of
 pragmas in the source code. This is useful for turning off specific
 warnings in a section of source code. Clang supports GCC's pragma for
-compatibility with existing source code.
+compatibility with existing source code, so ``#pragma GCC diagnostic``
+and ``#pragma clang diagnostic`` are synonyms for Clang. GCC will ignore
+``#pragma clang diagnostic``, though.
 
 The pragma may control any warning that can be used from the command
 line. Warnings may be set to ignored, warning, error, or fatal. The
@@ -1170,6 +1172,15 @@ 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 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 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.
+
 In addition to controlling warnings and errors generated by the compiler, it is
 possible to generate custom warning and error messages through the following
 pragmas:

>From e285dc23ede59979bbf2659cfeebf347e3247784 Mon Sep 17 00:00:00 2001
From: Vlad Serebrennikov <serebrennikov.vladislav at gmail.com>
Date: Wed, 17 Jan 2024 12:48:10 +0300
Subject: [PATCH 3/4] Clarify that diagnostics not enabled via CLI can't be
 enabled via pragma yet

---
 clang/docs/UsersManual.rst | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 9e8ffa760af92..b68dc4c8a9864 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1172,15 +1172,20 @@ 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 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 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
+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.
+
 In addition to controlling warnings and errors generated by the compiler, it is
 possible to generate custom warning and error messages through the following
 pragmas:

>From bee5bd07c834c6cd333cfb4506ca5f8d99db96f7 Mon Sep 17 00:00:00 2001
From: Vlad Serebrennikov <serebrennikov.vladislav at gmail.com>
Date: Thu, 1 Feb 2024 16:40:15 +0400
Subject: [PATCH 4/4] Accept Aaron's edits

Co-authored-by: Aaron Ballman <aaron at aaronballman.com>
---
 clang/docs/UsersManual.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index b68dc4c8a9864..3b6e3b6e66427 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1183,8 +1183,8 @@ 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.
+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.
 
 In addition to controlling warnings and errors generated by the compiler, it is
 possible to generate custom warning and error messages through the following