From: Anna Zaks <ganna@apple.com>
Date: Sat, 16 Jun 2012 00:30:21 +0000 (+0000)
Subject: Make the analyzer site a single point of reference for info
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=843f0e87e5ab9b5b5c36b60e99a350d15679683a;p=clang

Make the analyzer site a single point of reference for info
on controlling diagnostics.

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

diff --git a/docs/UsersManual.html b/docs/UsersManual.html
index a0e5ed8e8c..ae9ebfa394 100644
--- a/docs/UsersManual.html
+++ b/docs/UsersManual.html
@@ -708,36 +708,11 @@ treated as a system header.</p>
 
 <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 been 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 of which can already be done using <a
-href="#analyzer_annotations">annotations</a>).</li>
-
+by the user via changes to the source code. See the avaliable 
+<a href = "http://clang-analyzer.llvm.org/annotations.html" >annotations</a> and 
+the analyzer's 
+<a href= "http://clang-analyzer.llvm.org/faq.html#exclude_code" >FAQ page</a> for 
+more information.
 </ul>
 
 <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
diff --git a/www/analyzer/faq.html b/www/analyzer/faq.html
index 3633e8ee26..5c132b57f2 100644
--- a/www/analyzer/faq.html
+++ b/www/analyzer/faq.html
@@ -28,6 +28,7 @@ pointer is never null. How can I tell the analyzer that a pointer can never be
 null?</a></li>
   <li><a href="#use_assert">The analyzer assumes that a loop body is never entered.  How can I tell it that the loop body will be entered at least once?</a></li>
   <li><a href="#suppress_issue">How can I suppress a specific analyzer warning?</a></li>
+  <li><a href="#exclude_code">How can I selectively exclude code the analyzer examines?</a></li>
 </ol>
 
 
@@ -87,9 +88,30 @@ int foo(int length) {
 
 <h4 id="suppress_issue" class="faq">Q: How can I suppress a specific analyzer warning?</h4>
 
-<p>There is currently no mechanism for suppressing the analyzer warning,
-although this is currently being investigated. If you encounter an analyzer
-bug/false positive, please <a href = "filing_bugs.html">report it</a>.</p>
+<p>There is currently no solid mechanism for suppressing an analyzer warning,
+although this is currently being investigated. When you encounter an analyzer
+bug/false positive, check if it's one of the issues discussed above or if the
+analyzer <a href = "annotations.html#custom_assertions" >annotations</a> can 
+resolve the issue. Second, please <a href = "filing_bugs.html">report it</a> to 
+help us improve user experience. As the last resort, consider using <tt>__clang_analyzer__</tt> macro
+<a href = "faq.html#exclude_code" >described below</a>.</p>
+
+<h4 id="exclude_code" class="faq">Q: How can I selectively exclude code the analyzer examines?</h4>
+
+<p>When the static analyzer is using clang to parse source files, it implicitly 
+defines the preprocessor macro <tt>__clang_analyzer__</tt>. One can use this 
+macro to selectively exclude code the analyzer examines. Here is an example:
+
+<pre class="code_example">
+#ifndef __clang_analyzer__
+// Code not to be analyzed
+#endif
+</pre>
+
+This usage is discouraged because it makes the code dead to the analyzer from 
+now on. Instead, we prefer that users file bugs against the analyzer when it flags 
+false positives.
+</p>
 
 </div>
 </div>