1 files changed, 114 insertions, 0 deletions
diff --git a/lib/dialyzer/doc/warnings.txt b/lib/dialyzer/doc/warnings.txt
new file mode 100644
index 0000000000..fd8cc0dc60
--- /dev/null
+++ b/lib/dialyzer/doc/warnings.txt
@@ -0,0 +1,114 @@
+##----------------------------------------------------------------------------
+## File:      doc/warnings.txt
+## Author(s): Tobias Lindahl <[email protected]>
+##            Kostis Sagonas <[email protected]>
+##
+## $Id$
+##----------------------------------------------------------------------------
+
+
+The discrepancies currently identified by Dialyzer can be classified
+in the following categories:
+
+TYPE ERRORS
+===========
+
+* Match failure
+   - Warnings:
+       "The clause matching on X will never match; argument is of type T"
+       "The clause matching on tuple with arity N will never match; "
+	    " argument is of type T!"
+   - Description:
+       The function or case clause will never match since the calling
+       argument has a different type than the expected one.
+       Note that due to pattern-matching compilation the X above may be
+       an argument enclosed in some structured term (tuple or list).
+
+* Function call with wrong arguments
+   - Warning:
+       "Call to function X with signature S will fail since the arguments are of type T!"
+   - Description:
+       The arguments which the function is called with are
+       not what the function implicitly expects.
+
+* Closure of wrong type
+   - Warnings:
+       "Fun application using type T instead of a fun!"
+       "Trying to use fun with type T with arguments AT"
+   - Description:
+       The variable that is used in the fun application is either not 
+       a closure (fun entry) or a closure with the wrong domain.
+
+* Improper list construction
+   - Warnings:
+       "Cons will produce a non-proper list since its 2nd arg is of type T!"
+       "Call to '++'/2 will produce a non-proper list since its 2nd arg is of type T!"
+   - Description:
+       This is a place where an improper list (i.e., a list whose last
+       element is not the empty list []) is constructed. Strictly, these
+       are not discrepancies in Erlang, but we strongly recommend that
+       you fix these; there is ABSOLUTELY NO reason to create improper lists.
+
+* Function of no return
+   - Warning:
+       "Function will never return a proper value!"
+   - Description:
+       This is a function that never returns. Strictly speaking, this
+       is not a function and the code is OK only if this is used as a
+       point where an exception is thrown when handling an error.
+
+REDUNDANT OR UNREACHABLE CODE
+=============================
+
+* Unreachable case clause
+   - Warning:
+       "Type guard X will always fail since variable is of type T!"
+   - Description:
+       The case clause is redundant since the input argument is of a
+       different type.
+
+* Unreachable function clause
+   - Warning:
+       "The guard X will always fail since the arguments are of type T!"
+   - Description:
+       The clause is made redundant due to one of its guards always failing.
+
+* Term comparison failure
+   - Warnings:
+       "=:= between T1 and T2 will always fail!"
+       "=/= between T1 and T2 will always fail!"
+   - Description:
+       The term comparison will always fail making the test always return
+       'false' or, in a guard context, making the clause redundant.
+
+* Unused function
+   - Warning:
+       "Function will never be called!"
+   - Description:
+       The function is unused; no need to have it uncommented in the code.
+
+
+CODE RELICS
+===========
+
+* Tuple used as fun
+   - Warnings:
+       "Unsafe use of tuple as a fun in call to X"
+       "Tuple used as fun will fail in native compiled code"
+   - Description:
+       A 2-tuple is used as a function closure. The modern way of
+       calling higher-order code in Erlang is by using proper funs.
+       The code should be rewritten using a proper 'fun' rather than
+       a 2-tuple since among other things makes the code cleaner and
+       is safer for execution in native code.
+
+* Unsafe BEAM code
+   - Warning:
+       "Unsafe BEAM code! Please recompile with a newer BEAM compiler."
+   - Description:
+       The analysis has encountered BEAM bytecode which will fail in a
+       really bad way (even with a seg-fault) if used in an impoper way.
+       Such code was produced by the BEAM compiler of R9C-0 (and prior)
+       for some record expressions. The recommended action is to
+       generate a new .beam file using a newer version of the BEAM
+       compiler.