[clang] 3be7979 - [clang] Update documentation for `#pragma diagnostic` (#78095)
via cfe-commits
cfe-commits at lists.llvm.org
Fri Feb 2 00:21:55 PST 2024
Author: Vlad Serebrennikov
Date: 2024-02-02T12:21:51+04:00
New Revision: 3be79790ede30762f73b95218be8877c3b2c3774
URL: https://github.com/llvm/llvm-project/commit/3be79790ede30762f73b95218be8877c3b2c3774
DIFF: https://github.com/llvm/llvm-project/commit/3be79790ede30762f73b95218be8877c3b2c3774.diff
LOG: [clang] Update documentation for `#pragma diagnostic` (#78095)
GCC has changed over the past decade, and we're not implementing
everything they do.
Fixes #51472
---------
Co-authored-by: Aaron Ballman <aaron at aaronballman.com>
Added:
Modified:
clang/docs/UsersManual.rst
Removed:
################################################################################
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index ff2d4a68b8e55..7391e4cf3a9ae 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, as well as several extensions.
+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
@@ -1143,8 +1145,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,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
diff erence 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. A notable
diff erence 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
pragmas:
More information about the cfe-commits
mailing list