Merge branch 'mc/dialyzer-doc' into dev

* mc/dialyzer-doc:
  dialyzer: Update documentation

1 files changed, 139 insertions, 66 deletions

diff --git a/lib/dialyzer/doc/src/dialyzer.xml b/lib/dialyzer/doc/src/dialyzer.xml
index 29308885fd..01a7e478bc 100644
--- a/lib/dialyzer/doc/src/dialyzer.xml
+++ b/lib/dialyzer/doc/src/dialyzer.xml
@@ -64,81 +64,144 @@
     ]]></code>
     <p>Usage:</p>
     <code type="none"><![CDATA[
-   dialyzer [--help] [--version] [--shell] [--quiet] [--verbose]
-		[-pa dir]* [--plt plt] [-Ddefine]* [-I include_dir]* 
-		[--output_plt file] [-Wwarn]* [--src] 
-		[-c applications] [-r applications] [-o outfile]
+       dialyzer [--help] [--version] [--shell] [--quiet] [--verbose]
+		[-pa dir]* [--plt plt] [--plts plt*] [-Ddefine]*
+                [-I include_dir]* [--output_plt file] [-Wwarn]*
+                [--src] [--gui | --wx] [files_or_dirs] [-r dirs]
+                [--apps applications] [-o outfile]
 		[--build_plt] [--add_to_plt] [--remove_from_plt]
 		[--check_plt] [--no_check_plt] [--plt_info] [--get_warnings]
+                [--no_native]
     ]]></code>
     <p>Options:</p>
     <taglist>
-      <tag><c><![CDATA[-c applications]]></c>(or <c><![CDATA[--command-line applications]]></c>)</tag>
-      <item>use Dialyzer from the command line (no GUI) to detect defects in the
-       specified applications (directories or <c><![CDATA[.erl]]></c> or <c><![CDATA[.beam]]></c> files)</item>
-      <tag><c><![CDATA[-r applications]]></c></tag>
-      <item>same as <c><![CDATA[-c]]></c> only that directories are searched recursively for 
-       subdirectories containing <c><![CDATA[.erl]]></c> or <c><![CDATA[.beam]]></c> files (depending on the 
-       type of analysis)</item>
-      <tag><c><![CDATA[-o outfile]]></c>(or <c><![CDATA[--output outfile]]></c>)</tag>
-      <item>when using Dialyzer from the command line, send the analysis
-       results in the specified <c><![CDATA[outfile]]></c> rather than in stdout</item>
-      <tag><c><![CDATA[--src]]></c></tag>
-      <item>override the default, which is to analyze debug compiled BEAM 
-       bytecode, and analyze starting from Erlang source code instead</item>
+      <tag><c><![CDATA[files_or_dirs]]></c> (for backwards compatibility also
+        as: <c><![CDATA[-c files_or_dirs]]></c></tag>
+      <item>Use Dialyzer from the command line to detect defects in the
+        specified files or directories containing <c><![CDATA[.erl]]></c> or
+         <c><![CDATA[.beam]]></c> files, depending on the type of the
+         analysis.</item>
+      <tag><c><![CDATA[-r dirs]]></c></tag>
+      <item>Same as the previous but the specified directories are searched
+        recursively for subdirectories containing <c><![CDATA[.erl]]></c> or
+        <c><![CDATA[.beam]]></c> files in them, depending on the type of
+        analysis.</item>
+      <tag><c><![CDATA[--apps applications]]></c></tag>
+      <item>Option typically used when building or modifying a plt as in:
+        <code type="none"><![CDATA[
+           dialyzer --build_plt --apps erts kernel stdlib mnesia ...
+        ]]></code>
+        to conveniently refer to library applications corresponding to the
+        Erlang/OTP installation. However, the option is general and can also
+        be used during analysis in order to refer to Erlang/OTP applications.
+        In addition, file or directory names can also be included, as in:
+        <code type="none"><![CDATA[
+           dialyzer --apps inets ssl ./ebin ../other_lib/ebin/my_module.beam
+        ]]></code></item>
+      <tag><c><![CDATA[-o outfile]]></c> (or
+        <c><![CDATA[--output outfile]]></c>)</tag>
+      <item>When using Dialyzer from the command line, send the analysis
+        results to the specified outfile rather than to stdout.</item>
       <tag><c><![CDATA[--raw]]></c></tag>
       <item>When using Dialyzer from the command line, output the raw analysis
-       results (Erlang terms) instead of the formatted result.
-       The raw format is easier to post-process (for instance, to filter
-       warnings or to output HTML pages).</item>
-      <tag><c><![CDATA[-Dname]]></c>(or <c><![CDATA[-Dname=value]]></c>)</tag>
-      <item>when analyzing from source, pass the define to Dialyzer (**)</item>
+        results (Erlang terms) instead of the formatted result. The raw format
+        is easier to post-process (for instance, to filter warnings or to
+        output HTML pages).</item>
+      <tag><c><![CDATA[--src]]></c></tag>
+      <item>Override the default, which is to analyze BEAM files, and
+        analyze starting from Erlang source code instead.</item>
+      <tag><c><![CDATA[-Dname]]></c> (or <c><![CDATA[-Dname=value]]></c>)</tag>
+      <item>When analyzing from source, pass the define to Dialyzer. (**)</item>
       <tag><c><![CDATA[-I include_dir]]></c></tag>
-      <item>when analyzing from source, pass the <c><![CDATA[include_dir]]></c> to Dialyzer (**)</item>
+      <item>When analyzing from source, pass the <c><![CDATA[include_dir]]></c>
+        to Dialyzer. (**)</item>
       <tag><c><![CDATA[-pa dir]]></c></tag>
-      <item>Include <c><![CDATA[dir]]></c> in the path for Erlang. Useful when analyzing files
-       that have <c><![CDATA[-include_lib()]]></c> directives.</item>
+      <item>Include <c><![CDATA[dir]]></c> in the path for Erlang (useful when
+        analyzing files that have <c><![CDATA['-include_lib()']]></c>
+        directives).</item>
       <tag><c><![CDATA[--output_plt file]]></c></tag>
-      <item>Store the PLT at the specified location after building it.</item>
+      <item>Store the plt at the specified file after building it.</item>
       <tag><c><![CDATA[--plt plt]]></c></tag>
-      <item>Use the specified PLT as the initial persistent lookup table.</item>
+      <item>Use the specified plt as the initial plt (if the plt was built
+        during setup the files will be checked for consistency).</item>
+      <tag><c><![CDATA[--plts plt*]]></c></tag>
+      <item>Merge the specified plts to create the initial plt -- requires
+        that the plts are disjoint (i.e., do not have any module
+        appearing in more than one plt).
+        The plts are created in the usual way:
+        <code type="none"><![CDATA[
+           dialyzer --build_plt --output_plt plt_1 files_to_include
+           ...
+           dialyzer --build_plt --output_plt plt_n files_to_include
+        ]]></code>
+        and then can be used in either of the following ways:
+        <code type="none"><![CDATA[
+           dialyzer files_to_analyze --plts plt_1 ... plt_n
+        ]]></code>
+        or:
+        <code type="none"><![CDATA[
+           dialyzer --plts plt_1 ... plt_n -- files_to_analyze
+        ]]></code>
+        (Note the -- delimiter in the second case)</item>
       <tag><c><![CDATA[-Wwarn]]></c></tag>
-      <item>a family of options which selectively turn on/off warnings.
-       (for help on the names of warnings use <c><![CDATA[dialyzer -Whelp]]></c>)</item>
+      <item>A family of options which selectively turn on/off warnings
+        (for help on the names of warnings use
+        <c><![CDATA[dialyzer -Whelp]]></c>).</item>
       <tag><c><![CDATA[--shell]]></c></tag>
-      <item>do not disable the Erlang shell while running the GUI</item>
-      <tag><c><![CDATA[--version (or -v)]]></c></tag>
-      <item>prints the Dialyzer version and some more information and exits</item>
-      <tag><c><![CDATA[--help (or -h)]]></c></tag>
-      <item>prints this message and exits</item>
-      <tag><c><![CDATA[--quiet (or -q)]]></c></tag>
-      <item>makes Dialyzer a bit more quiet</item>
+      <item>Do not disable the Erlang shell while running the GUI.</item>
+      <tag><c><![CDATA[--version]]></c> (or <c><![CDATA[-v]]></c>)</tag>
+      <item>Print the Dialyzer version and some more information and
+        exit.</item>
+      <tag><c><![CDATA[--help]]></c> (or <c><![CDATA[-h]]></c>)</tag>
+      <item>Print this message and exit.</item>
+      <tag><c><![CDATA[--quiet]]></c> (or <c><![CDATA[-q]]></c>)</tag>
+      <item>Make Dialyzer a bit more quiet.</item>
       <tag><c><![CDATA[--verbose]]></c></tag>
-      <item>makes Dialyzer a bit more verbose</item>
-      <tag><c><![CDATA[--check_plt]]></c></tag>
-      <item>Only checks if the initial PLT is up to date and rebuilds it if this is not the case</item>
-      <tag><c><![CDATA[--no_check_plt (or -n)]]></c></tag>
-      <item>Skip the PLT integrity check when running Dialyzer.
-       Useful when working with installed PLTs that never change.</item>
+      <item>Make Dialyzer a bit more verbose.</item>
       <tag><c><![CDATA[--build_plt]]></c></tag>
-      <item>The analysis starts from an empty PLT and creates a new one from
-       the files specified with -c and -r. Only works for beam files.
-       Use --plt or --output_plt to override the default PLT location.</item>
-      <tag><c><![CDATA[--add_to_plt]]></c></tag>   
-      <item> The PLT is extended to also include the files specified with 
-       -c and -r. Use --plt to specify which PLT to start from, and --output_plt 
-       to specify where to put the PLT. Note that the analysis might include 
-       files from the PLT if they depend on the new files. 
-       This option only works with beam files.</item>
+      <item>The analysis starts from an empty plt and creates a new one from
+        the files specified with <c><![CDATA[-c]]></c> and
+        <c><![CDATA[-r]]></c>. Only works for beam files. Use
+        <c><![CDATA[--plt]]></c> or <c><![CDATA[--output_plt]]></c> to
+        override the default plt location.</item>
+       <tag><c><![CDATA[--add_to_plt]]></c></tag>
+       <item>The plt is extended to also include the files specified with
+         <c><![CDATA[-c]]></c> and <c><![CDATA[-r]]></c>. Use
+         <c><![CDATA[--plt]]></c> to specify which plt to start from,
+         and <c><![CDATA[--output_plt]]></c> to specify where to put the plt.
+         Note that the analysis might include files from the plt if they depend
+         on the new files. This option only works with beam files.</item>
        <tag><c><![CDATA[--remove_from_plt]]></c></tag>
-       <item>The information from the files specified with -c and -r is removed
-       from the PLT. Note that this may cause a re-analysis of the remaining
-       dependent files.</item>
+       <item>The information from the files specified with
+         <c><![CDATA[-c]]></c> and <c><![CDATA[-r]]></c> is removed
+         from the plt. Note that this may cause a re-analysis of the remaining
+         dependent files.</item>
+       <tag><c><![CDATA[--check_plt]]></c></tag>
+       <item>Check the plt for consistency and rebuild it if it is not
+         up-to-date.</item>
+       <tag><c><![CDATA[--no_check_plt]]></c></tag>
+       <item>Skip the plt check when running Dialyzer. Useful when working with
+         installed plts that never change.</item>
+       <tag><c><![CDATA[--plt_info]]></c></tag>
+       <item>Make Dialyzer print information about the plt and then quit. The
+         plt can be specified with <c><![CDATA[--plt(s)]]></c>.</item>
        <tag><c><![CDATA[--get_warnings]]></c></tag>
-       <item>Makes Dialyzer emit warnings even when manipulating the PLT. Only 
-       emits warnings for files that are actually analyzed. The default is to
-       not emit any warnings when manipulating the PLT. This option has no 
-       effect when performing a normal analysis.</item>
+       <item>Make Dialyzer emit warnings even when manipulating the plt.
+         Warnings are only emitted for files that are actually analyzed.</item>
+       <tag><c><![CDATA[--dump_callgraph file]]></c></tag>
+       <item>Dump the call graph into the specified file whose format is
+         determined by the file name extension. Supported extensions are: raw,
+         dot, and ps. If something else is used as file name extension, default
+         format '.raw' will be used.</item>
+       <tag><c><![CDATA[--no_native]]></c> (or <c><![CDATA[-nn]]></c>)</tag>
+       <item>Bypass the native code compilation of some key files that Dialyzer
+         heuristically performs when dialyzing many files; this avoids the
+         compilation time but it may result in (much) longer analysis
+         time.</item>
+       <tag><c><![CDATA[--gui]]></c></tag>
+       <item>Use the gs-based GUI.</item>
+       <tag><c><![CDATA[--wx]]></c></tag>
+       <item>Use the wx-based GUI..</item>
     </taglist>
     <note>
       <p>* denotes that multiple occurrences of these options are possible.</p>
@@ -148,11 +211,14 @@
     <p>Warning options:</p>
     <taglist>
       <tag><c><![CDATA[-Wno_return]]></c></tag>
-      <item>Suppress warnings for functions of no return.</item>
+      <item>Suppress warnings for functions that will never return a
+        value.</item>
       <tag><c><![CDATA[-Wno_unused]]></c></tag>
       <item>Suppress warnings for unused functions.</item>
       <tag><c><![CDATA[-Wno_improper_lists]]></c></tag>
       <item>Suppress warnings for construction of improper lists.</item>
+      <tag><c><![CDATA[-Wno_tuple_as_fun]]></c></tag>
+      <item>Suppress warnings for using tuples instead of funs.</item>
       <tag><c><![CDATA[-Wno_fun_app]]></c></tag>
       <item>Suppress warnings for fun applications that will fail.</item>
       <tag><c><![CDATA[-Wno_match]]></c></tag>
@@ -160,6 +226,10 @@
        match.</item>
       <tag><c><![CDATA[-Wno_opaque]]></c></tag>
       <item>Suppress warnings for violations of opaqueness of data types.</item>
+      <tag><c><![CDATA[-Wunmatched_returns]]></c>***</tag>
+      <item>Include warnings for function calls which ignore a structured return
+        value or do not match against one of many possible return
+        value(s).</item>
       <tag><c><![CDATA[-Werror_handling]]></c>***</tag>
       <item>Include warnings for functions that only return by means of an
        exception.</item>
@@ -168,20 +238,22 @@
       <tag><c><![CDATA[-Wbehaviours]]></c>***</tag>
       <item>Include warnings about behaviour callbacks which drift from the
        published recommended interfaces.</item>
-      <tag><c><![CDATA[-Wunmatched_returns]]></c>***</tag>
-      <item>Include warnings for function calls which ignore a structured return
-       value or do not match against one of many possible return value(s).</item>
       <tag><c><![CDATA[-Wunderspecs]]></c>***</tag>
       <item>Warn about underspecified functions 
-      (the -spec is strictly more allowing than the success typing)</item>
+      (the -spec is strictly more allowing than the success typing).</item>
+    </taglist>
+    <p>The following options are also available but their use is not
+      recommended: (they are mostly for Dialyzer developers and internal
+      debugging)</p>
+    <taglist>
       <tag><c><![CDATA[-Woverspecs]]></c>***</tag>
       <item>Warn about overspecified functions 
-      (the -spec is strictly less allowing than the success typing)</item>
+      (the -spec is strictly less allowing than the success typing).</item>
       <tag><c><![CDATA[-Wspecdiffs]]></c>***</tag>
-      <item>Warn when the -spec is different than the success typing</item>
+      <item>Warn when the -spec is different than the success typing.</item>
     </taglist>
     <note>
-      <p>*** These are options that turn on warnings rather than
+      <p>*** Identifies options that turn on warnings rather than
       turning them off.</p>
     </note>
   </section>
@@ -210,6 +282,7 @@ Option   : {files,          [Filename : string()]}
          | {defines,        [{Macro: atom(), Value : term()}]}
          | {from,           src_code | byte_code} %% Defaults to byte_code
          | {init_plt,       FileName : string()}  %% If changed from default
+         | {plts,           [FileName :: string()]} %% If changed from default
          | {include_dirs,   [DirName : string()]} 
          | {output_file,    FileName : string()}
          | {output_plt,     FileName :: string()}