From 33b0b25746a26705e2cb93b7a39e0a14ff2b76cb Mon Sep 17 00:00:00 2001 From: Maria Christakis Date: Sat, 4 Dec 2010 01:02:11 +0200 Subject: dialyzer: Update documentation --- lib/dialyzer/doc/src/dialyzer.xml | 205 ++++++++++++++++++++++++++------------ 1 file changed, 139 insertions(+), 66 deletions(-) (limited to 'lib/dialyzer/doc/src') 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 @@ ]]>

Usage:

Options:

- (or ) - use Dialyzer from the command line (no GUI) to detect defects in the - specified applications (directories or or files) - - same as only that directories are searched recursively for - subdirectories containing or files (depending on the - type of analysis) - (or ) - when using Dialyzer from the command line, send the analysis - results in the specified rather than in stdout - - override the default, which is to analyze debug compiled BEAM - bytecode, and analyze starting from Erlang source code instead + (for backwards compatibility also + as: + Use Dialyzer from the command line to detect defects in the + specified files or directories containing or + files, depending on the type of the + analysis. + + Same as the previous but the specified directories are searched + recursively for subdirectories containing or + files in them, depending on the type of + analysis. + + Option typically used when building or modifying a plt as in: + + 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: + + (or + ) + When using Dialyzer from the command line, send the analysis + results to the specified outfile rather than to stdout. 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). - (or ) - when analyzing from source, pass the define to Dialyzer (**) + 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). + + Override the default, which is to analyze BEAM files, and + analyze starting from Erlang source code instead. + (or ) + When analyzing from source, pass the define to Dialyzer. (**) - when analyzing from source, pass the to Dialyzer (**) + When analyzing from source, pass the + to Dialyzer. (**) - Include in the path for Erlang. Useful when analyzing files - that have directives. + Include in the path for Erlang (useful when + analyzing files that have + directives). - Store the PLT at the specified location after building it. + Store the plt at the specified file after building it. - Use the specified PLT as the initial persistent lookup table. + Use the specified plt as the initial plt (if the plt was built + during setup the files will be checked for consistency). + + 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: + + and then can be used in either of the following ways: + + or: + + (Note the -- delimiter in the second case) - a family of options which selectively turn on/off warnings. - (for help on the names of warnings use ) + A family of options which selectively turn on/off warnings + (for help on the names of warnings use + ). - do not disable the Erlang shell while running the GUI - - prints the Dialyzer version and some more information and exits - - prints this message and exits - - makes Dialyzer a bit more quiet + Do not disable the Erlang shell while running the GUI. + (or ) + Print the Dialyzer version and some more information and + exit. + (or ) + Print this message and exit. + (or ) + Make Dialyzer a bit more quiet. - makes Dialyzer a bit more verbose - - Only checks if the initial PLT is up to date and rebuilds it if this is not the case - - Skip the PLT integrity check when running Dialyzer. - Useful when working with installed PLTs that never change. + Make Dialyzer a bit more verbose. - 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. - - 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. + The analysis starts from an empty plt and creates a new one from + the files specified with and + . Only works for beam files. Use + or to + override the default plt location. + + The plt is extended to also include the files specified with + and . Use + to specify which plt to start from, + and 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. - 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. + The information from the files specified with + and is removed + from the plt. Note that this may cause a re-analysis of the remaining + dependent files. + + Check the plt for consistency and rebuild it if it is not + up-to-date. + + Skip the plt check when running Dialyzer. Useful when working with + installed plts that never change. + + Make Dialyzer print information about the plt and then quit. The + plt can be specified with . - 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. + Make Dialyzer emit warnings even when manipulating the plt. + Warnings are only emitted for files that are actually analyzed. + + 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. + (or ) + 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. + + Use the gs-based GUI. + + Use the wx-based GUI..

* denotes that multiple occurrences of these options are possible.

@@ -148,11 +211,14 @@

Warning options:

- Suppress warnings for functions of no return. + Suppress warnings for functions that will never return a + value. Suppress warnings for unused functions. Suppress warnings for construction of improper lists. + + Suppress warnings for using tuples instead of funs. Suppress warnings for fun applications that will fail. @@ -160,6 +226,10 @@ match. Suppress warnings for violations of opaqueness of data types. + *** + Include warnings for function calls which ignore a structured return + value or do not match against one of many possible return + value(s). *** Include warnings for functions that only return by means of an exception. @@ -168,20 +238,22 @@ *** Include warnings about behaviour callbacks which drift from the published recommended interfaces. - *** - Include warnings for function calls which ignore a structured return - value or do not match against one of many possible return value(s). *** Warn about underspecified functions - (the -spec is strictly more allowing than the success typing) + (the -spec is strictly more allowing than the success typing). + +

The following options are also available but their use is not + recommended: (they are mostly for Dialyzer developers and internal + debugging)

+ *** Warn about overspecified functions - (the -spec is strictly less allowing than the success typing) + (the -spec is strictly less allowing than the success typing). *** - Warn when the -spec is different than the success typing + Warn when the -spec is different than the success typing. -

*** These are options that turn on warnings rather than +

*** Identifies options that turn on warnings rather than turning them off.

 @@ -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()} -- cgit v1.2.3