dialyzer: Introduce module local suppression of warnings

The -dialyzer() attribute can be used for suppressing warnings in a
module by specifying functions or warning options. It can also be used
for requesting warnings in a module.

1 files changed, 71 insertions, 2 deletions

diff --git a/lib/dialyzer/doc/src/dialyzer.xml b/lib/dialyzer/doc/src/dialyzer.xml
index e482b1e6f8..b52c1edebf 100644
--- a/lib/dialyzer/doc/src/dialyzer.xml
+++ b/lib/dialyzer/doc/src/dialyzer.xml
@@ -139,7 +139,11 @@
       <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>
+        <c><![CDATA[dialyzer -Whelp]]></c>).
+        Note that the options can also be given in the file with a
+        <c>-dialyzer()</c> attribute. See <seealso
+        marker="#suppression">Requesting or Suppressing Warnings in
+        Source Files</seealso> below for details.</item>
       <tag><c><![CDATA[--shell]]></c></tag>
       <item>Do not disable the Erlang shell while running the GUI.</item>
       <tag><c><![CDATA[--version]]></c> (or <c><![CDATA[-v]]></c>)</tag>
@@ -269,6 +273,71 @@
       given from the command line, so please refer to the sections above for
       a description of these.</p>
   </section>
+
+  <section>
+    <marker id="suppression"></marker>
+    <title>Requesting or Suppressing Warnings in Source Files</title>
+    <p>
+      The <c>-dialyzer()</c> attribute can be used for turning off
+      warnings in a module by specifying functions or warning options.
+      For example, to turn off all warnings for the function
+      <c>f/0</c>, include the following line:
+    </p>
+<code type="none">
+-dialyzer({nowarn_function, f/0}).
+</code>
+    <p>To turn off warnings for improper lists, add the following line
+      to the source file:
+    </p>
+<code type="none">
+-dialyzer(no_improper_lists).
+</code>
+    <p>The <c>-dialyzer()</c> attribute is allowed after function
+    declarations. Lists of warning options or functions are allowed:
+    </p>
+<code type="none">
+-dialyzer([{nowarn_function, [f/0]}, no_improper_lists]).
+</code>
+    <p>
+      Warning options can be restricted to functions:
+    </p>
+<code type="none">
+-dialyzer({no_improper_lists, g/0}).
+</code>
+<code type="none">
+-dialyzer({[no_return, no_match], [g/0, h/0]}).
+</code>
+    <p>
+      For help on the warning options use <c>dialyzer -Whelp</c>. The
+      options are also enumerated <seealso
+      marker="#gui/1">below</seealso> (<c>WarnOpts</c>).
+    </p>
+    <note>
+      <p>
+        The <c>-dialyzer()</c> attribute is not checked by the Erlang
+              Compiler, but by the Dialyzer itself.
+      </p>
+    </note>
+    <note>
+      <p>
+        The warning option <c>-Wrace_conditions</c> has no effect when
+        set in source files.
+      </p>
+    </note>
+    <p>
+      The <c>-dialyzer()</c> attribute can also be used for turning on
+      warnings. For instance, if a module has been fixed regarding
+      unmatched returns, adding the line
+    </p>
+<code type="none">
+-dialyzer(unmatched_returns).
+</code>
+    <p>
+      can help in assuring that no new unmatched return warnings are
+      introduced.
+    </p>
+  </section>
+
   <funcs>
     <func>
       <name>gui() -> ok | {error, Msg}</name>
@@ -283,7 +352,7 @@
 OptList  :: [Option]
 Option   :: {files,          [Filename :: string()]}
           | {files_rec,      [DirName :: string()]}
-          | {defines,        [{Macro: atom(), Value : term()}]}
+          | {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