From: Ted Kremenek <kremenek@apple.com>
Date: Tue, 24 Aug 2010 18:12:35 +0000 (+0000)
Subject: Document '__clang_analyzer__'.
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2fb11ebc36a6604adb1e0f0331aeae48a95df212;p=clang

Document '__clang_analyzer__'.

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

diff --git a/docs/UsersManual.html b/docs/UsersManual.html
index 205c95d309..75241610a3 100644
--- a/docs/UsersManual.html
+++ b/docs/UsersManual.html
@@ -39,6 +39,7 @@ td {
    <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 @@ 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>
 
+<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>
 <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->