From: Ted Kremenek <kremenek@apple.com>
Date: Thu, 12 Jun 2008 18:39:02 +0000 (+0000)
Subject: Added an "important notes" section.  Tweaked formatting.
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=bc757865cd5442e91303d17fa9e2304a9bec54c1;p=clang

Added an "important notes" section.  Tweaked formatting.


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

diff --git a/www/StaticAnalysis.html b/www/StaticAnalysis.html
index d5dcfed8f7..76e85e10ba 100644
--- a/www/StaticAnalysis.html
+++ b/www/StaticAnalysis.html
@@ -32,25 +32,43 @@
 <p>This documents provides some notes on using the LLVM/clang static analyzer to
 find bugs in C and Objective-C programs.</p>
 
-<p>Please note that this tool is <b>very early</b> in development, and there are
-<b>many planned enhancements</b> to improve both the precision and scope of its
-analysis algorithms as well as the kinds bugs it will find.</p>
-
-<h3>High-Level Summary</h3>
-
 <p>Currently the analyzer is invoked as a command-line tool. It is intended to
-run in synchronous with a build of a project or code base. Analysis results are
+run in tandem with a build of a project or code base. Analysis results are
 deposited in a directory as HTML files, which can then viewed using a web
-browser.</p>
+browser (open the generated <tt>index.html</tt> file to view a list of flagged
+errors).</p>
+
+<h3>Important Notes (Please Read)</h3>
+
+<p>Here are some important points we ask you to consider when using the static
+analyzer:</p>
+
+<ul>
 
-<p>The analyzer performs a variety of checks on code, each requiring different
-levels of analysis precision (more precision = more CPU time). While the
-analyzer is being designed to be as fast and light-weight as possible, please
-<b>do not expect it to be as fast as compiling a program</b> (even with
-optimizations enabled). Some of the algorithms needed to find bugs require in
-the worst case exponential time. The analyzer runs in a reasonable amount of
-time by both bounding the amount of checking work it will do as well as using
-clever algorithms to reduce the amount of work it must do to find bugs.</p>
+<li><b>This tool is <b>very early</b> in development.</b> There are many planned
+enhancements to improve both the precision and scope of its analysis algorithms
+as well as the kinds bugs it will find.</li>
+
+<li><b>False positives.</b> Static analysis reasons about the run-time behavior
+of a program without actually running the program. Static analysis is not
+perfect, and can falsely flag bugs in a program where the code behaves
+correctly. Because some code checks performed by the analyzer require more
+analysis than others, the frequency of false positives can vary widely between
+different checks. Our goal is to have the analyzer have a low false positive
+rate for most code on all checks, and we will reach this goal by gradually
+improving over time the analysis precision of the tool.</li>
+
+<li><b>Static analysis can be much slower than compilation.</b> The analyzer
+performs a variety of checks on code, each requiring different levels of
+analysis precision (more precision = more CPU time). While the analyzer is being
+designed to be as fast and light-weight as possible, please do not expect it to
+be as fast as compiling a program (even with optimizations enabled). Some of the
+algorithms needed to find bugs require in the worst case exponential time. The
+analyzer runs in a reasonable amount of time by both bounding the amount of
+checking work it will do as well as using clever algorithms to reduce the amount
+of work it must do to find bugs.</li>
+
+</ul>
 
 <h3>Organization</h3>
 
@@ -61,7 +79,8 @@ clever algorithms to reduce the amount of work it must do to find bugs.</p>
   <li><a href="#BasicUsage">Basic Usage</a></li> 
   <li><a href="#Output">Output of the Analyzer</a></li>
   <li><a href="#RecommendedUsageGuidelines">Recommended Usage Guidelines</a></li>
-  <li><a href="#Debugging">Debugging the Analyzer</a>
+  <li><a href="#Debugging">Debugging the Analyzer</a></li>
+  <li><a href="#filingbugs">Filing Bugs</a></li>
 </ul>
 
 <h2 id="ReleaseContents">Obtaining the Analyzer</h2>
@@ -77,19 +96,17 @@ other special installation is needed.</p>
 
 <h3>Packaged Builds (Mac OS X)</h3>
 
-<p>Semi-regular pre-built binaries of the analyzer(packaged as a gzipped tar
-file) are available on Mac OS X (10.5).</p>
+<p>Semi-regular pre-built binaries of the analyzer are available on Mac OS X
+(10.5).</p>
 
 <p>The latest build is: <b><a
-href="http://keeda.stanford.edu/~kremenek/checker/checker-36.tar.gz">checker-36</a></b></p>
+href="http://keeda.stanford.edu/~kremenek/checker/checker-36.tar.gz">checker-36.tar.gz</a></b> (built June 11, 2008)</p>
 
-<p>The entire set of previous builds can be found <a
-href="http://keeda.stanford.edu/~kremenek/checker">here</a>. Packaged builds for
-other platforms may eventually be provided, but as the tool is in its early
-stages we are not actively promoting releases yet. If you wish to help
-contribute regular builds of the analyzer on other platforms, please email the
-<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang Developers'
-mailing list</a>.</p>
+Packaged builds for other platforms may eventually be provided, but as the tool
+is in its early stages we are not actively promoting releases yet. If you wish
+to help contribute regular builds of the analyzer on other platforms, please
+email the <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang
+Developers' mailing list</a>.</p>
 
 <p>Packaged builds of the analyzer expand to the following files:</p>
 
@@ -236,10 +253,10 @@ Here are a few recommendations with running the analyzer:
 
 <h3>Always Analyze a Project in its "Debug" Configuration</h3>
 
-Most projects can be built in a "debug" mode that enables assertions. Assertions
-are picked up by the static analyzer to prune infeasible paths, which in some
-cases can greatly reduce the number of false positives (bogus error reports)
-emitted by the tool.
+<p>Most projects can be built in a "debug" mode that enables assertions.
+Assertions are picked up by the static analyzer to prune infeasible paths, which
+in some cases can greatly reduce the number of false positives (bogus error
+reports) emitted by the tool.</p>
 
 <h3>Pass -k to <tt>scan-build</tt></h3>
 
@@ -254,24 +271,24 @@ compile-debug cycle.</p>
 
 <h3>Use Verbose Output when Debugging <tt>scan-build</tt></h3>
 
-<tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about what
-it's doing; two <b>-v</b> options emit more information. Redirecting the output
-of <tt>scan-build</tt> to a text file (make sure to redirect standard error) is
-useful for filing bug reports against <tt>scan-build</tt> or the analyzer, as we
-can see the exact options (and files) passed to the analyzer. For more
-comprehendible logs, don't perform a parallel build.
+<p><tt>scan-build</tt> takes a <b>-v</b> option to emit verbose output about
+what it's doing; two <b>-v</b> options emit more information. Redirecting the
+output of <tt>scan-build</tt> to a text file (make sure to redirect standard
+error) is useful for filing bug reports against <tt>scan-build</tt> or the
+analyzer, as we can see the exact options (and files) passed to the analyzer.
+For more comprehendible logs, don't perform a parallel build.</p>
 
 <h2 id="Debugging">Debugging the Analyzer</h2>
 
-This section provides information on debugging the analyzer, and troubleshooting
-it when you have problems analyzing a particular project.
+<p>This section provides information on debugging the analyzer, and troubleshooting
+it when you have problems analyzing a particular project.</p>
 
 <h3>How it Works</h3>
 
-To analyze a project, <tt>scan-build</tt> simply sets the environment variable
+<p>To analyze a project, <tt>scan-build</tt> simply sets the environment variable
 <tt>CC</tt> to the full path to <tt>ccc-analyzer</tt>. It also sets a few other
 environment variables to communicate to <tt>ccc-analyzer</tt> where to dump HTML
-report files.
+report files.</p>
 
 <p>Some Makefiles (or equivalent project files) hardcode the compiler; for such
 projects simply overriding <tt>CC</tt> won't cause <tt>ccc-analyzer</tt> to be
@@ -298,18 +315,21 @@ calling <tt>clang</tt>). <tt>ccc-analyzer</tt> tries to correctly forward all
 the arguments over to <tt>gcc</tt>, but this may not work perfectly (please
 report bugs of this kind).
 
-<h3>Filing Bugs</h3>
+<h2 id="filingbugs">Filing Bugs</h2>
 
-We encourage users to file bug reports for any problems that they encounter.
+<p>We encourage users to file bug reports for any problems that they
+encounter.</p>
 
-<p><b>Outside Apple</b>: Please <a
-href="http://llvm.org/bugs/enter_bug.cgi?product=clang">file bugs</a> (against
-Clang) in LLVM's Bugzilla database.</p>
+<h3>Outside Apple</h3>
 
-<p><b>Apple-internal</b>:  Please file bugs in Radar against the <b>llvm - clang</b>
-component.</p>
+<p>Please <a href="http://llvm.org/bugs/enter_bug.cgi?product=clang">file
+bugs</a> (against Clang) in LLVM's Bugzilla database.</p>
 
-</div>
+<h3>Apple-internal Users</h3>
 
+<p>Please file bugs in Radar against the <b>llvm - clang</b> component.</p>
+
+
+</div>
 </body>
 </html>
\ No newline at end of file
diff --git a/www/content.css b/www/content.css
index 7cb3b7f986..1dac1d5159 100644
--- a/www/content.css
+++ b/www/content.css
@@ -5,6 +5,10 @@ html, body {
 
 h1, h2, h3, tt { color: #000; }
 
+h2 { padding-top: 1em; }
+h3 { padding-top: 0.5em; margin-bottom: -0.25em; }
+li { padding-bottom: 0.5em; }
+
 /* Slides */
 IMG.img_slide {
     display: block;