[Analyzer] Document a gotcha: for C++ -analyze-function requires parameters in function name

[NoQ]

Yeah, in D22856 i intended -analyze-function to work in pair with -analyzer-display-progress - you can always copy-paste the fully qualified name from there, even if it's an ObjC method or even an anonymous block. But i guess i failed to explain this in D22874.

I suggest something like: "This also works with C++ objects methods, functions in namespaces, and overloaded functions, Objective-C class and instance methods, and even blocks, but in these cases a fully qualified name should be used. Note: In C++ you always need to specify function arguments, even if it is a regular function. If you are not sure how to fully qualify the name, consult how it is displayed in the output of -analyzer-display-progress"

[NoQ]

Or maybe just add an example with blocks below your text?:

If you're not sure how to specify function name, consult how -analyzer-display-progress displays it.

It even works with blocks which are anonymous but can be identified by line numbers:

$ clang -cc1 -fblocks -analyze -analyzer-checker=core test.c -analyzer-display-progress
ANALYZE (Syntax): test.c foo
ANALYZE (Syntax): test.c block (line: 2, col: 25)
ANALYZE (Path,  Inline_Regular): test.c foo
ANALYZE (Path,  Inline_Regular): test.c block (line: 2, col: 25)
$ clang -cc1 -fblocks -analyze -analyzer-checker=core test.c -analyzer-display-progress -analyze-function "block (line: 2, col: 25)"
ANALYZE (Syntax): test.c block (line: 2, col: 25)
ANALYZE (Path,  Inline_Regular): test.c block (line: 2, col: 25)

[george.karpenkov]

@NoQ To clarify: your proposed update is to checker_dev_manual, CC1Options.td stays the same, right?

In an ideal world of course we would like to warn the user if they try to use unqualified name to resolve a C++ identifier.
Or even resolve the name if no overloads exist (which is often the case for tests).
Though that's not the top priority.

[george.karpenkov]

@NoQ is that better?

[george.karpenkov]

@NoQ ping?

[zaks.anna]

Looks great! Thanks!

include/clang/Driver/CC1Options.td

 
 def analyzer_opt_analyze_headers : Flag<["-"], "analyzer-opt-analyze-headers">,
   HelpText<"Force the static analyzer to analyze functions defined in header files">;
 def analyzer_opt_analyze_nested_blocks : Flag<["-"], "analyzer-opt-analyze-nested-blocks">,
   HelpText<"Analyze the definitions of blocks in addition to functions">;
 def analyzer_display_progress : Flag<["-"], "analyzer-display-progress">,
   HelpText<"Emit verbose output about the analyzer's progress">;
 def analyze_function : Separate<["-"], "analyze-function">,
-  HelpText<"Run analysis on specific function">;
+  HelpText<"Run analysis on specific function (for C++ include parameters in name)">;
 def analyze_function_EQ : Joined<["-"], "analyze-function=">, Alias<analyze_function>;
 def analyzer_eagerly_assume : Flag<["-"], "analyzer-eagerly-assume">,
   HelpText<"Eagerly assume the truth/falseness of some symbolic constraints">;
 def trim_egraph : Flag<["-"], "trim-egraph">,
   HelpText<"Only show error-related paths in the analysis graph">;
 def analyzer_viz_egraph_graphviz : Flag<["-"], "analyzer-viz-egraph-graphviz">,
   HelpText<"Display exploded graph using GraphViz">;
 def analyzer_viz_egraph_ubigraph : Flag<["-"], "analyzer-viz-egraph-ubigraph">,

www/analyzer/checker_dev_manual.html

 <pre class="code">
     $ <b>clang -cc1 -analyze -analyzer-checker=osx.KeychainAPI test.c</b>
 </pre>
 
 <p>If you are experiencing a crash, to see which function is failing while
 processing a large file use the  <tt><b>-analyzer-display-progress</b></tt>
 option.</p>
 
-<p>You can analyze a particular function within the file, which is often useful
-because the problem is always in a certain function:</p>
+<p>To selectively analyze only the given function, use the
+<tt><b>-analyze-function</b></tt> option:</p>
 <pre class="code">
     $ <b>clang -cc1 -analyze -analyzer-checker=core test.c -analyzer-display-progress</b>
     ANALYZE (Syntax): test.c foo
     ANALYZE (Syntax): test.c bar
     ANALYZE (Path,  Inline_Regular): test.c bar
     ANALYZE (Path,  Inline_Regular): test.c foo
     $ <b>clang -cc1 -analyze -analyzer-checker=core test.c -analyzer-display-progress -analyze-function=foo</b>
     ANALYZE (Syntax): test.c foo
     ANALYZE (Path,  Inline_Regular): test.c foo
 </pre>
 
+<b>Note: </b> a fully qualified function name has to be used when selecting
+C++ functions and methods, Objective-C methods and blocks, e.g.:
+
+<pre class="code">
+    $ <b>clang -cc1 -analyze -analyzer-checker=core test.cc -analyze-function=foo(int)</b>
+</pre>
+
+The fully qualified name can be found from the
+<tt><b>-analyzer-display-progress</b></tt> output.
+
 <p>The bug reporter mechanism removes path diagnostics inside intermediate
 function calls that have returned by the time the bug was found and contain
 no interesting pieces. Usually it is up to the checkers to produce more
 interesting pieces by adding custom <tt>BugReporterVisitor</tt> objects.
 However, you can disable path pruning while debugging with the
 <tt><b>-analyzer-config prune-paths=false</b></tt> option.
 
 <h3 id=visualizing>Visualizing the Analysis</h3>