document the diagnostics pragmas, patch by Louis Gerbarg!

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@75432 91177308-0d34-0410-b5e6-96231b3b80d8

docs/UsersManual.html

@@ -33,6 +33,12 @@ td {
 <li><a href="#general_features">Language and Target-Independent Features</a>
  <ul>
   <li><a href="#diagnostics">Controlling Errors and Warnings</a></li>
+   <ul>
+   <li><a href="#diagnostics_display">Controlling How Clang Displays Diagnostics</a></li>
+   <li><a href="#diagnostics_mappings">Diagnostic Mappings</a></li>
+   <li><a href="#diagnostics_commandline">Controlling Diagnostics via Command Line Flags</a></li>
+   <li><a href="#diagnostics_pragmas">Controlling Diagnostics via Pragmas</a></li>
+   </ul>
   <li><a href="#precompiledheaders">Precompiled Headers</a></li>
   </ul>
 </li>
@@ -362,7 +368,7 @@ by commenting them out.</p>
 <p>Clang provides a number of ways to control which code constructs cause it to
 emit errors and warning messages, and how they are displayed to the console.</p>
 
-<h4>Controlling How Clang Displays Diagnostics</h4>
+<h4 id="diagnostics_display">Controlling How Clang Displays Diagnostics</h4>
 
 <p>When Clang emits a diagnostic, it includes rich information in the output,
 and gives you fine-grain control over which information is printed.  Clang has
@@ -394,18 +400,64 @@ it:</p>
 <p>For more information please see <a href="#cl_diag_formatting">Formatting of
 Diagnostics</a>.</p>
 
-<h4>Controlling Which Diagnostics Clang Generates</h4>
+<h4 id="diagnostics_mappings">Diagnostic Mappings</h4>
 
-<p>mappings: ignore, note, warning, error, fatal</p>
+<p>All diagnostics are mapped into one of these 5 classes:</p>
 
 <p>
-The two major classes are control from the command line and control via pragmas
-in your code.</p>
+<ul>
+<li>Ignored</li>
+<li>Note</li>
+<li>Warning</li>
+<li>Error</li>
+<li>Fatal</li>
+</ul></p>
 
+<h4 id="diagnostics_commandline">Controlling Diagnostics via Command Line Flags</h4>
 
 <p>-W flags, -pedantic, etc</p>
 
-<p>pragma GCC diagnostic</p>
+<h4 id="diagnostics_pragmas">Controlling Diagnostics via Pragmas</h4>
+
+<p>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. </p>
+
+<p>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 following 
+example code will tell Clang or GCC to ignore the -Wall warnings:</p>
+
+<pre>
+#pragma GCC diagnostic ignored "-Wall"
+</pre>
+
+<p>In addition to all of the functionality of provided by GCC's pragma, 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.</p>
+
+<p>In the below example
+-Wmultichar is ignored for only a single line of code, after which the
+diagnostics return to whatever state had previously existed.</p>
+
+<pre>
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wmultichar"
+
+char b = 'df'; // no warning.
+
+#pragma clang diagnostic pop
+</pre>
+
+<p>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 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. </p>
 
 <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
 <h3 id="precompiledheaders">Precompiled Headers</h3>