[cfe-commits] r111935 - /cfe/trunk/docs/UsersManual.html

[Ted Kremenek]

Author: kremenek
Date: Tue Aug 24 13:12:35 2010
New Revision: 111935

URL: http://llvm.org/viewvc/llvm-project?rev=111935&view=rev
Log:
Document '__clang_analyzer__'.

Modified:
    cfe/trunk/docs/UsersManual.html

Modified: cfe/trunk/docs/UsersManual.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.html?rev=111935&r1=111934&r2=111935&view=diff
==============================================================================
--- cfe/trunk/docs/UsersManual.html (original)
+++ cfe/trunk/docs/UsersManual.html Tue Aug 24 13:12:35 2010
@@ -39,6 +39,7 @@
    <li><a href="#diagnostics_categories">Diagnostic Categories</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>
+   <li><a href="#analyzer_diagnositics">Controlling Static Analyzer Diagnostics</a></li>
    </ul>
   <li><a href="#precompiledheaders">Precompiled Headers</a></li>
   <li><a href="#codegen">Controlling Code Generation</a></li>
@@ -591,6 +592,42 @@
 compatible #pragmas there is no guarantee that they will have identical behaviour
 on both compilers. </p>
 
+<h4 id="analyzer_diagnositics">Controlling Static Analyzer Diagnostics</h4>
+
+<p>While not strictly part of the compiler, the diagnostics from Clang's <a
+href="http://clang-analyzer.llvm.org">static analyzer</a> can also be influenced
+by the user via changes to the source code.  This can be done in two ways:
+
+<ul>
+
+<li id="analyzer_annotations"><b>Annotations</b>: The static analyzer recognizes various GCC-style
+attributes (e.g., <tt>__attribute__((nonnull)))</tt>) that can either suppress
+static analyzer warnings or teach the analyzer about code invariants which
+enable it to find more bugs. While many of these attributes are standard GCC
+attributes, additional ones have added to Clang to specifically support the
+static analyzer. Detailed information on these annotations can be found in the
+<a href="http://clang-analyzer.llvm.org/annotations.html">analyzer's
+documentation</a>.</li>
+
+<li><b><tt>__clang_analyzer__</tt></b>: When the static analyzer is using Clang
+to parse source files, it implicitly defines the preprocessor macro
+<tt>__clang_analyzer__</tt>. While discouraged, code can use this macro to
+selectively exclude code the analyzer examines.  Here is an example:
+
+<pre>
+#ifndef __clang_analyzer__
+// Code not to be analyzed
+#endif
+</pre>
+
+In general, this usage is discouraged. Instead, we prefer that users file bugs
+against the analyzer when it flags false positives. There is also active
+discussion of allowing users in the future to selectively silence specific
+analyzer warnings (some which can already be done using <a
+href="analyzer_annotations">annotations</a>).</li>
+
+</ul>
+
 <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
 <h3 id="precompiledheaders">Precompiled Headers</h3>
 <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->