Merge branch 'ks/dialyzer' into dev

* ks/dialyzer:
  dialyzer: Build the PLT even if there are unresolved remote types
  proplists: Export the type property()
  erl_lint: Issue warnings for undefined exported types
  Minor fix in a print message
  Add handling of unknown types
  Add declaration for exported types
  Add types and specs; performed some cleanups also
  erl_scan: Add declarations for exported types
  stdlib: Add declarations for exported types
  hipe: Add declarations for exported types
  compiler: Add declarations for exported types
  syntax_tools: Add declarations for exported types
  kernel: Add declaration for exported types
  Support -export_type() in dialyzer and erl_types
  Add infrastructure for the -export_type() attribute

OTP-8678 ks/dialyzer

13 files changed, 244 insertions, 127 deletions

diff --git a/lib/stdlib/src/beam_lib.erl b/lib/stdlib/src/beam_lib.erl
index c71dad6163..91ff2438c6 100644
--- a/lib/stdlib/src/beam_lib.erl
+++ b/lib/stdlib/src/beam_lib.erl
@@ -41,6 +41,8 @@
 	 terminate/2,code_change/3]).
 -export([make_crypto_key/2, get_crypto_key/1]).	%Utilities used by compiler
 
+-export_type([attrib_entry/0, compinfo_entry/0, labeled_entry/0]).
+
 -import(lists, [append/1, delete/2, foreach/2, keysort/2, 
 		member/2, reverse/1, sort/1, splitwith/2]).
 
diff --git a/lib/stdlib/src/dets.erl b/lib/stdlib/src/dets.erl
index 7f1c13770b..4584b8184f 100644
--- a/lib/stdlib/src/dets.erl
+++ b/lib/stdlib/src/dets.erl
@@ -1,19 +1,19 @@
 %%
 %% %CopyrightBegin%
-%% 
-%% Copyright Ericsson AB 1996-2009. All Rights Reserved.
-%% 
+%%
+%% Copyright Ericsson AB 1996-2010. All Rights Reserved.
+%%
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
 %% compliance with the License. You should have received a copy of the
 %% Erlang Public License along with this software. If not, it can be
 %% retrieved online at http://www.erlang.org/.
-%% 
+%%
 %% Software distributed under the License is distributed on an "AS IS"
 %% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 %% the License for the specific language governing rights and limitations
 %% under the License.
-%% 
+%%
 %% %CopyrightEnd%
 %%
 -module(dets).
@@ -88,6 +88,7 @@
 %% Not documented, or not ready for publication.
 -export([lookup_keys/2]).
 
+-export_type([tab_name/0]).
 
 -compile({inline, [{einval,2},{badarg,2},{undefined,1},
                    {badarg_exit,2},{lookup_reply,2}]}).
diff --git a/lib/stdlib/src/digraph.erl b/lib/stdlib/src/digraph.erl
index 9bdea671a9..b5f52da921 100644
--- a/lib/stdlib/src/digraph.erl
+++ b/lib/stdlib/src/digraph.erl
@@ -1,19 +1,19 @@
 %%
 %% %CopyrightBegin%
-%% 
-%% Copyright Ericsson AB 1996-2009. All Rights Reserved.
-%% 
+%%
+%% Copyright Ericsson AB 1996-2010. All Rights Reserved.
+%%
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
 %% compliance with the License. You should have received a copy of the
 %% Erlang Public License along with this software. If not, it can be
 %% retrieved online at http://www.erlang.org/.
-%% 
+%%
 %% Software distributed under the License is distributed on an "AS IS"
 %% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 %% the License for the specific language governing rights and limitations
 %% under the License.
-%% 
+%%
 %% %CopyrightEnd%
 %%
 -module(digraph).
@@ -36,6 +36,8 @@
 
 -export([get_short_path/3, get_short_cycle/2]).
 
+-export_type([d_type/0, vertex/0]).
+
 -record(digraph, {vtab = notable :: ets:tab(),
 		  etab = notable :: ets:tab(),
 		  ntab = notable :: ets:tab(),
diff --git a/lib/stdlib/src/erl_compile.erl b/lib/stdlib/src/erl_compile.erl
index d9d15e05f8..abff37e4bc 100644
--- a/lib/stdlib/src/erl_compile.erl
+++ b/lib/stdlib/src/erl_compile.erl
@@ -1,19 +1,19 @@
 %%
 %% %CopyrightBegin%
-%% 
-%% Copyright Ericsson AB 1997-2009. All Rights Reserved.
-%% 
+%%
+%% Copyright Ericsson AB 1997-2010. All Rights Reserved.
+%%
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
 %% compliance with the License. You should have received a copy of the
 %% Erlang Public License along with this software. If not, it can be
 %% retrieved online at http://www.erlang.org/.
-%% 
+%%
 %% Software distributed under the License is distributed on an "AS IS"
 %% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 %% the License for the specific language governing rights and limitations
 %% under the License.
-%% 
+%%
 %% %CopyrightEnd%
 %%
 -module(erl_compile).
@@ -23,6 +23,8 @@
 
 -export([compile_cmdline/1]).
 
+-export_type([cmd_line_arg/0]).
+
 %% Mapping from extension to {M,F} to run the correct compiler.
 
 compiler(".erl") ->    {compile,         compile};
diff --git a/lib/stdlib/src/erl_lint.erl b/lib/stdlib/src/erl_lint.erl
index 229d455e06..6bbb52ebae 100644
--- a/lib/stdlib/src/erl_lint.erl
+++ b/lib/stdlib/src/erl_lint.erl
@@ -40,7 +40,7 @@
 %%              Value.
 %%  The option handling functions.
 
--spec bool_option(atom(), atom(), boolean(), [_]) -> boolean().
+-spec bool_option(atom(), atom(), boolean(), [compile:option()]) -> boolean().
 
 bool_option(On, Off, Default, Opts) ->
     foldl(fun (Opt, _Def) when Opt =:= On -> true;
@@ -72,6 +72,10 @@ value_option(Flag, Default, On, OnVal, Off, OffVal, Opts) ->
 %%-define(DEBUGF(X,Y), io:format(X, Y)).
 -define(DEBUGF(X,Y), void).
 
+-type line() :: erl_scan:line().     % a convenient alias
+-type fa()   :: {atom(), arity()}.   % function+arity
+-type ta()   :: {atom(), arity()}.   % type+arity
+
 %% Usage of records, functions, and imports. The variable table, which
 %% is passed on as an argument, holds the usage of variables.
 -record(usage, {
@@ -97,8 +101,8 @@ value_option(Flag, Default, On, OnVal, Off, OffVal, Opts) ->
                locals=gb_sets:empty()	:: gb_set(),	%All defined functions (prescanned)
 	       no_auto=gb_sets:empty()	:: gb_set(),	%Functions explicitly not autoimported
                defined=gb_sets:empty()	:: gb_set(),	%Defined fuctions
-	       on_load=[] :: [{atom(),integer()}], 	%On-load function
-	       on_load_line=0 :: integer(),		%Line for on_load
+	       on_load=[] :: [fa()],		%On-load function
+	       on_load_line=0 :: line(),	%Line for on_load
 	       clashes=[],			%Exported functions named as BIFs
                not_deprecated=[],               %Not considered deprecated
                func=[],                         %Current function
@@ -112,13 +116,14 @@ value_option(Flag, Default, On, OnVal, Off, OffVal, Opts) ->
 						%outside any fun or lc
                xqlc= false :: boolean(),	%true if qlc.hrl included
                new = false :: boolean(),	%Has user-defined 'new/N'
-               called= [],			%Called functions
+               called= [] :: [{fa(),line()}],		%Called functions
                usage = #usage{}		:: #usage{},
 	       specs = dict:new()	:: dict(),	%Type specifications
-	       types = dict:new()	:: dict()	%Type definitions
+	       types = dict:new()	:: dict(),	%Type definitions
+	       exp_types=gb_sets:empty():: gb_set()	%Exported types
               }).
 
-%% -type lint_state() :: #lint{}.
+-type lint_state() :: #lint{}.
 
 %% format_error(Error)
 %%  Return a string describing the error.
@@ -303,6 +308,8 @@ format_error({ill_defined_behaviour_callbacks,Behaviour}) ->
 %% --- types and specs ---
 format_error({singleton_typevar, Name}) ->
     io_lib:format("type variable ~w is only used once (is unbound)", [Name]);
+format_error({duplicated_export_type, {T, A}}) ->
+    io_lib:format("type ~w/~w already exported", [T, A]);
 format_error({undefined_type, {TypeName, Arity}}) ->
     io_lib:format("type ~w~s undefined", [TypeName, gen_type_paren(Arity)]);
 format_error({unused_type, {TypeName, Arity}}) ->
@@ -684,6 +691,8 @@ attribute_state({attribute,L,extends,_M}, St) ->
     add_error(L, invalid_extends, St);
 attribute_state({attribute,L,export,Es}, St) ->
     export(L, Es, St);
+attribute_state({attribute,L,export_type,Es}, St) ->
+    export_type(L, Es, St);
 attribute_state({attribute,L,import,Is}, St) ->
     import(L, Is, St);
 attribute_state({attribute,L,record,{Name,Fields}}, St) ->
@@ -1093,7 +1102,7 @@ check_unused_records(Forms, St0) ->
 %% For storing the import list we use the orddict module.
 %% We know an empty set is [].
 
-%% export(Line, Exports, State) -> State.
+-spec export(line(), [fa()], lint_state()) -> lint_state().
 %%  Mark functions as exported, also as called from the export line.
 
 export(Line, Es, #lint{exports = Es0, called = Called} = St0) ->
@@ -1101,7 +1110,8 @@ export(Line, Es, #lint{exports = Es0, called = Called} = St0) ->
         foldl(fun (NA, {E,C,St2}) ->
                       St = case gb_sets:is_element(NA, E) of
                                true ->
-                                   add_warning(Line, {duplicated_export, NA}, St2);
+                                   Warn = {duplicated_export,NA},
+                                   add_warning(Line, Warn, St2);
                                false ->
                                    St2
                            end,
@@ -1110,8 +1120,27 @@ export(Line, Es, #lint{exports = Es0, called = Called} = St0) ->
               {Es0,Called,St0}, Es),
     St1#lint{exports = Es1, called = C1}.
 
-%% import(Line, Imports, State) -> State.
-%% imported(Name, Arity, State) -> {yes,Module} | no.
+-spec export_type(line(), [ta()], lint_state()) -> lint_state().
+%%  Mark types as exported; also mark them as used from the export line.
+
+export_type(Line, ETs, #lint{usage = Usage, exp_types = ETs0} = St0) ->
+    UTs0 = Usage#usage.used_types,
+    {ETs1,UTs1,St1} =
+	foldl(fun (TA, {E,U,St2}) ->
+		      St = case gb_sets:is_element(TA, E) of
+			       true ->
+				   Warn = {duplicated_export_type,TA},
+				   add_warning(Line, Warn, St2);
+			       false ->
+				   St2
+			   end,
+		      {gb_sets:add_element(TA, E), dict:store(TA, Line, U), St}
+	      end,
+	      {ETs0,UTs0,St0}, ETs),
+    St1#lint{usage = Usage#usage{used_types = UTs1}, exp_types = ETs1}.
+
+-type import() :: {module(), [fa()]} | module().
+-spec import(line(), import(), lint_state()) -> lint_state().
 
 import(Line, {Mod,Fs}, St) ->
     Mod1 = package_to_string(Mod),
@@ -1200,13 +1229,15 @@ check_imports(_Line, Fs, Is) ->
 add_imports(Mod, Fs, Is) ->
     foldl(fun (F, Is0) -> orddict:store(F, Mod, Is0) end, Is, Fs).
 
+-spec imported(atom(), arity(), lint_state()) -> {'yes',module()} | 'no'.
+
 imported(F, A, St) ->
     case orddict:find({F,A}, St#lint.imports) of
         {ok,Mod} -> {yes,Mod};
         error -> no
     end.
 
-%% on_load(Line, Val, State) -> State.
+-spec on_load(line(), fa(), lint_state()) -> lint_state().
 %%  Check an on_load directive and remember it.
 
 on_load(Line, {Name,Arity}=Fa, #lint{on_load=OnLoad0}=St0)
@@ -1238,7 +1269,7 @@ check_on_load(#lint{defined=Defined,on_load=[{_,0}=Fa],
     end;
 check_on_load(St) -> St.
 
-%% call_function(Line, Name, Arity, State) -> State.
+-spec call_function(line(), atom(), arity(), lint_state()) -> lint_state().
 %%  Add to both called and calls.
 
 call_function(Line, F, A, #lint{usage=Usage0,called=Cd,func=Func}=St) ->
@@ -1258,7 +1289,7 @@ function(Line, Name, Arity, Cs, St0) ->
     St1 = define_function(Line, Name, Arity, St0#lint{func={Name,Arity}}),
     clauses(Cs, St1#lint.global_vt, St1).
 
-%% define_function(Line, Name, Arity, State) -> State.
+-spec define_function(line(), atom(), arity(), lint_state()) -> lint_state().
 
 define_function(Line, Name, Arity, St0) ->
     St1 = keyword_warning(Line, Name, St0),
@@ -2744,10 +2775,12 @@ add_missing_spec_warnings(Forms, St0, Type) ->
 		  add_warning(L, {missing_spec,FA}, St)
 	  end, St0, Warns).
 
-check_unused_types(Forms, St = #lint{usage=Usage, types=Types}) ->
+check_unused_types(Forms, #lint{usage=Usage, types=Ts, exp_types=ExpTs}=St) ->
     case [File || {attribute,_L,file,{File,_Line}} <- Forms] of
 	[FirstFile|_] ->
-	    UsedTypes = Usage#usage.used_types,
+	    D = Usage#usage.used_types,
+	    L = gb_sets:to_list(ExpTs) ++ dict:fetch_keys(D),
+	    UsedTypes = gb_sets:from_list(L),
 	    FoldFun =
 		fun(_Type, -1, AccSt) ->
 			%% Default type
@@ -2755,19 +2788,18 @@ check_unused_types(Forms, St = #lint{usage=Usage, types=Types}) ->
 		   (Type, FileLine, AccSt) ->
                         case loc(FileLine) of
 			    {FirstFile, _} ->
-				case dict:is_key(Type, UsedTypes) of
+				case gb_sets:is_member(Type, UsedTypes) of
 				    true -> AccSt;
 				    false ->
-					add_warning(FileLine,
-                                                    {unused_type, Type},
-						    AccSt)
+					Warn = {unused_type,Type},
+					add_warning(FileLine, Warn, AccSt)
 				end;
 			    _ ->
-				%% Don't warn about unused types in include file
+				%% No warns about unused types in include files
 				AccSt
 			end
 		end,
-	    dict:fold(FoldFun, St, Types);
+	    dict:fold(FoldFun, St, Ts);
 	[] ->
 	    St
     end.
diff --git a/lib/stdlib/src/erl_scan.erl b/lib/stdlib/src/erl_scan.erl
index c179c3d067..18f64c46d0 100644
--- a/lib/stdlib/src/erl_scan.erl
+++ b/lib/stdlib/src/erl_scan.erl
@@ -55,18 +55,13 @@
          token_info/1,token_info/2,
          attributes_info/1,attributes_info/2,set_attribute/3]).
 
-%%% Local record.
--record(erl_scan,
-        {resword_fun=fun reserved_word/1,
-         ws=false,
-         comment=false,
-         text=false}).
+-export_type([error_info/0, line/0, tokens_result/0]).
 
 %%%
-%%% Exported functions
+%%% Defines and type definitions
 %%%
 
--define(COLUMN(C), is_integer(C), C >= 1).
+-define(COLUMN(C), (is_integer(C) andalso C >= 1)).
 %% Line numbers less than zero have always been allowed:
 -define(ALINE(L), is_integer(L)).
 -define(STRING(S), is_list(S)).
@@ -95,6 +90,15 @@
 -type error_description() :: term().
 -type error_info() :: {location(), module(), error_description()}.
 
+%%% Local record.
+-record(erl_scan,
+        {resword_fun = fun reserved_word/1 :: resword_fun(),
+         ws          = false               :: boolean(),
+         comment     = false               :: boolean(),
+         text        = false               :: boolean()}).
+
+%%----------------------------------------------------------------------------
+
 -spec format_error(Error :: term()) -> string().
 format_error({string,Quote,Head}) ->
     lists:flatten(["unterminated " ++ string_thing(Quote) ++
@@ -307,10 +311,10 @@ options(Opt) ->
     options([Opt]).
 
 opts(Options, [Key|Keys], L) ->
-    V = case lists:keysearch(Key, 1, Options) of
-            {value,{reserved_word_fun,F}} when ?RESWORDFUN(F) ->
+    V = case lists:keyfind(Key, 1, Options) of
+            {reserved_word_fun,F} when ?RESWORDFUN(F) ->
                 {ok,F};
-            {value,{Key,_}} ->
+            {Key,_} ->
                 badarg;
             false ->
                 {ok,default_option(Key)}
@@ -333,12 +337,13 @@ expand_opt(O, Os) ->
     [O|Os].
 
 attr_info(Attrs, Item) ->
-    case catch lists:keysearch(Item, 1, Attrs) of
-        {value,{Item,Value}} ->
-            {Item,Value};
+    try lists:keyfind(Item, 1, Attrs) of
+        {_Item, _Value} = T ->
+            T;
         false ->
-            undefined;
-        _ ->
+            undefined
+    catch
+	_:_ ->
             erlang:error(badarg, [Attrs, Item])
     end.
 
diff --git a/lib/stdlib/src/ets.erl b/lib/stdlib/src/ets.erl
index d7b5dbc636..b0a197d784 100644
--- a/lib/stdlib/src/ets.erl
+++ b/lib/stdlib/src/ets.erl
@@ -42,6 +42,8 @@
 
 -export([i/0, i/1, i/2, i/3]).
 
+-export_type([tab/0]).
+
 %%------------------------------------------------------------------------------
 
 -type tab()        :: atom() | tid().
diff --git a/lib/stdlib/src/io.erl b/lib/stdlib/src/io.erl
index 1f8076e864..1d0f9374bc 100644
--- a/lib/stdlib/src/io.erl
+++ b/lib/stdlib/src/io.erl
@@ -1,19 +1,19 @@
 %%
 %% %CopyrightBegin%
-%% 
-%% Copyright Ericsson AB 1996-2009. All Rights Reserved.
-%% 
+%%
+%% Copyright Ericsson AB 1996-2010. All Rights Reserved.
+%%
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
 %% compliance with the License. You should have received a copy of the
 %% Erlang Public License along with this software. If not, it can be
 %% retrieved online at http://www.erlang.org/.
-%% 
+%%
 %% Software distributed under the License is distributed on an "AS IS"
 %% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 %% the License for the specific language governing rights and limitations
 %% under the License.
-%% 
+%%
 %% %CopyrightEnd%
 %%
 -module(io).
@@ -32,6 +32,7 @@
 	 parse_erl_form/1,parse_erl_form/2,parse_erl_form/3]).
 -export([request/1,request/2,requests/1,requests/2]).
 
+-export_type([device/0, format/0]).
 
 %%-------------------------------------------------------------------------
 
diff --git a/lib/stdlib/src/io_lib.erl b/lib/stdlib/src/io_lib.erl
index 26f6ec8931..4ca9d079b7 100644
--- a/lib/stdlib/src/io_lib.erl
+++ b/lib/stdlib/src/io_lib.erl
@@ -75,6 +75,8 @@
 	 collect_line/2, collect_line/3, collect_line/4,
 	 get_until/3, get_until/4]).
 
+-export_type([chars/0]).
+
 %%----------------------------------------------------------------------
 
  %% XXX: overapproximates a deep list of (unicode) characters
diff --git a/lib/stdlib/src/io_lib_fread.erl b/lib/stdlib/src/io_lib_fread.erl
index 74316dc730..33553692bc 100644
--- a/lib/stdlib/src/io_lib_fread.erl
+++ b/lib/stdlib/src/io_lib_fread.erl
@@ -1,19 +1,19 @@
 %%
 %% %CopyrightBegin%
-%% 
-%% Copyright Ericsson AB 1996-2009. All Rights Reserved.
-%% 
+%%
+%% Copyright Ericsson AB 1996-2010. All Rights Reserved.
+%%
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
 %% compliance with the License. You should have received a copy of the
 %% Erlang Public License along with this software. If not, it can be
 %% retrieved online at http://www.erlang.org/.
-%% 
+%%
 %% Software distributed under the License is distributed on an "AS IS"
 %% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 %% the License for the specific language governing rights and limitations
 %% under the License.
-%% 
+%%
 %% %CopyrightEnd%
 %%
 -module(io_lib_fread).
@@ -22,6 +22,8 @@
 
 -export([fread/2,fread/3]).
 
+-export_type([continuation/0, fread_2_ret/0, fread_3_ret/0]).
+
 -import(lists, [reverse/1,reverse/2]).
 
 %%-----------------------------------------------------------------------
diff --git a/lib/stdlib/src/proc_lib.erl b/lib/stdlib/src/proc_lib.erl
index 9aa5e0a71e..4fb64a3353 100644
--- a/lib/stdlib/src/proc_lib.erl
+++ b/lib/stdlib/src/proc_lib.erl
@@ -1,19 +1,19 @@
 %%
 %% %CopyrightBegin%
-%% 
-%% Copyright Ericsson AB 1996-2009. All Rights Reserved.
-%% 
+%%
+%% Copyright Ericsson AB 1996-2010. All Rights Reserved.
+%%
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
 %% compliance with the License. You should have received a copy of the
 %% Erlang Public License along with this software. If not, it can be
 %% retrieved online at http://www.erlang.org/.
-%% 
+%%
 %% Software distributed under the License is distributed on an "AS IS"
 %% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 %% the License for the specific language governing rights and limitations
 %% under the License.
-%% 
+%%
 %% %CopyrightEnd%
 %%
 -module(proc_lib).
@@ -34,6 +34,8 @@
 %% Internal exports.
 -export([wake_up/3]).
 
+-export_type([spawn_option/0]).
+
 %%-----------------------------------------------------------------------------
 
 -type priority_level() :: 'high' | 'low' | 'max' | 'normal'.
diff --git a/lib/stdlib/src/proplists.erl b/lib/stdlib/src/proplists.erl
index 35d14891f1..6a45e0f868 100644
--- a/lib/stdlib/src/proplists.erl
+++ b/lib/stdlib/src/proplists.erl
@@ -1,19 +1,19 @@
 %%
 %% %CopyrightBegin%
-%% 
-%% Copyright Ericsson AB 2001-2009. All Rights Reserved.
-%% 
+%%
+%% Copyright Ericsson AB 2001-2010. All Rights Reserved.
+%%
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
 %% compliance with the License. You should have received a copy of the
 %% Erlang Public License along with this software. If not, it can be
 %% retrieved online at http://www.erlang.org/.
-%% 
+%%
 %% Software distributed under the License is distributed on an "AS IS"
 %% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 %% the License for the specific language governing rights and limitations
 %% under the License.
-%% 
+%%
 %% %CopyrightEnd%
 %%
 %% =====================================================================
@@ -49,6 +49,8 @@
 
 %% ---------------------------------------------------------------------
 
+-export_type([property/0]).
+
 -type property()   :: atom() | tuple().
 
 -type aliases()    :: [{any(), any()}].
diff --git a/lib/stdlib/src/supervisor.erl b/lib/stdlib/src/supervisor.erl
index 22269a8d1b..f5d5441184 100644
--- a/lib/stdlib/src/supervisor.erl
+++ b/lib/stdlib/src/supervisor.erl
@@ -21,7 +21,7 @@
 -behaviour(gen_server).
 
 %% External exports
--export([start_link/2,start_link/3,
+-export([start_link/2, start_link/3,
 	 start_child/2, restart_child/2,
 	 delete_child/2, terminate_child/2,
 	 which_children/1, count_children/1,
@@ -33,25 +33,47 @@
 -export([init/1, handle_call/3, handle_info/2, terminate/2, code_change/3]).
 -export([handle_cast/2]).
 
+-export_type([child_spec/0, strategy/0]).
+
+%%--------------------------------------------------------------------------
+
+-type child_id() :: pid() | 'undefined'.
+-type mfargs()   :: {module(), atom(), [term()]}.
+-type modules()  :: [module()] | 'dynamic'.
+-type restart()  :: 'permanent' | 'transient' | 'temporary'.
+-type shutdown() :: 'brutal_kill' | timeout().
+-type worker()   :: 'worker' | 'supervisor'.
+-type sup_name() :: {'local', atom()} | {'global', atom()}.
+-type sup_ref()  :: atom() | {atom(), atom()} | {'global', atom()} | pid().
+-type child_spec() :: {term(),mfargs(),restart(),shutdown(),worker(),modules()}.
+
+-type strategy() :: 'one_for_all' | 'one_for_one'
+                  | 'rest_for_one' | 'simple_one_for_one'.
+
+%%--------------------------------------------------------------------------
+
+-record(child, {% pid is undefined when child is not running
+	        pid = undefined :: child_id(),
+		name,
+		mfargs          :: mfargs(),
+		restart_type    :: restart(),
+		shutdown        :: shutdown(),
+		child_type      :: worker(),
+		modules = []    :: modules()}).
+-type child() :: #child{}.
+
 -define(DICT, dict).
 
 -record(state, {name,
-		strategy,
-		children = [],
-		dynamics = ?DICT:new(),
-		intensity,
-		period,
+		strategy               :: strategy(),
+		children = []          :: [child()],
+		dynamics = ?DICT:new() :: ?DICT(),
+		intensity              :: non_neg_integer(),
+		period                 :: pos_integer(),
 		restarts = [],
 	        module,
 	        args}).
-
--record(child, {pid = undefined,  % pid is undefined when child is not running
-		name,
-		mfa,
-		restart_type,
-		shutdown,
-		child_type,
-		modules = []}).
+-type state() :: #state{}.
 
 -define(is_simple(State), State#state.strategy =:= simple_one_for_one).
 
@@ -65,21 +87,40 @@ behaviour_info(_Other) ->
 %%% Servers/processes should/could also be built using gen_server.erl.
 %%% SupName = {local, atom()} | {global, atom()}.
 %%% ---------------------------------------------------
+
+-type startlink_err() :: {'already_started', pid()} | 'shutdown' | term().
+-type startlink_ret() :: {'ok', pid()} | 'ignore' | {'error', startlink_err()}.
+
+-spec start_link(module(), term()) -> startlink_ret().
 start_link(Mod, Args) ->
     gen_server:start_link(supervisor, {self, Mod, Args}, []).
  
+-spec start_link(sup_name(), module(), term()) -> startlink_ret().
 start_link(SupName, Mod, Args) ->
     gen_server:start_link(SupName, supervisor, {SupName, Mod, Args}, []).
  
 %%% ---------------------------------------------------
 %%% Interface functions.
 %%% ---------------------------------------------------
+
+-type info()	       :: term().
+-type startchild_err() :: 'already_present'
+			| {'already_started', child_id()} | term().
+-type startchild_ret() :: {'ok', child_id()} | {'ok', child_id(), info()}
+			| {'error', startchild_err()}.
+
+-spec start_child(sup_ref(), child_spec() | [term()]) -> startchild_ret().
 start_child(Supervisor, ChildSpec) ->
     call(Supervisor, {start_child, ChildSpec}).
 
+-type restart_err() :: 'running' | 'not_found' | 'simple_one_for_one' | term().
+-spec restart_child(sup_ref(), term()) ->
+    {'ok', child_id()} | {'ok', child_id(), info()} | {'error', restart_err()}.
 restart_child(Supervisor, Name) ->
     call(Supervisor, {restart_child, Name}).
 
+-type del_err() :: 'running' | 'not_found' | 'simple_one_for_one'.
+-spec delete_child(sup_ref(), term()) -> 'ok' | {'error', del_err()}.
 delete_child(Supervisor, Name) ->
     call(Supervisor, {delete_child, Name}).
 
@@ -89,9 +130,13 @@ delete_child(Supervisor, Name) ->
 %%          Note that the child is *always* terminated in some
 %%          way (maybe killed).
 %%-----------------------------------------------------------------
+
+-type term_err() :: 'not_found' | 'simple_one_for_one'.
+-spec terminate_child(sup_ref(), term()) -> 'ok' | {'error', term_err()}.
 terminate_child(Supervisor, Name) ->
     call(Supervisor, {terminate_child, Name}).
 
+-spec which_children(sup_ref()) -> [{term(), child_id(), worker(), modules()}].
 which_children(Supervisor) ->
     call(Supervisor, which_children).
 
@@ -101,6 +146,7 @@ count_children(Supervisor) ->
 call(Supervisor, Req) ->
     gen_server:call(Supervisor, Req, infinity).
 
+-spec check_childspecs([child_spec()]) -> 'ok' | {'error', term()}.
 check_childspecs(ChildSpecs) when is_list(ChildSpecs) ->
     case check_startspec(ChildSpecs) of
 	{ok, _} -> ok;
@@ -113,6 +159,14 @@ check_childspecs(X) -> {error, {badarg, X}}.
 %%% Initialize the supervisor.
 %%% 
 %%% ---------------------------------------------------
+
+-type stop_rsn() :: 'shutdown' | {'bad_return', {module(),'init', term()}}
+                  | {'bad_start_spec', term()} | {'start_spec', term()}
+                  | {'supervisor_data', term()}.
+
+-spec init({sup_name(), module(), [term()]}) ->
+        {'ok', state()} | 'ignore' | {'stop', stop_rsn()}.
+
 init({SupName, Mod, Args}) ->
     process_flag(trap_exit, true),
     case Mod:init(Args) of
@@ -158,12 +212,12 @@ init_dynamic(_State, StartSpec) ->
 
 %%-----------------------------------------------------------------
 %% Func: start_children/2
-%% Args: Children = [#child] in start order
-%%       SupName = {local, atom()} | {global, atom()} | {pid(),Mod}
+%% Args: Children = [child()] in start order
+%%       SupName = {local, atom()} | {global, atom()} | {pid(), Mod}
 %% Purpose: Start all children.  The new list contains #child's 
 %%          with pids.
 %% Returns: {ok, NChildren} | {error, NChildren}
-%%          NChildren = [#child] in termination order (reversed
+%%          NChildren = [child()] in termination order (reversed
 %%                        start order)
 %%-----------------------------------------------------------------
 start_children(Children, SupName) -> start_children(Children, [], SupName).
@@ -182,8 +236,8 @@ start_children([], NChildren, _SupName) ->
     {ok, NChildren}.
 
 do_start_child(SupName, Child) ->
-    #child{mfa = {M, F, A}} = Child,
-    case catch apply(M, F, A) of
+    #child{mfargs = {M, F, Args}} = Child,
+    case catch apply(M, F, Args) of
 	{ok, Pid} when is_pid(Pid) ->
 	    NChild = Child#child{pid = Pid},
 	    report_progress(NChild, SupName),
@@ -192,7 +246,7 @@ do_start_child(SupName, Child) ->
 	    NChild = Child#child{pid = Pid},
 	    report_progress(NChild, SupName),
 	    {ok, Pid, Extra};
-	ignore -> 
+	ignore ->
 	    {ok, undefined};
 	{error, What} -> {error, What};
 	What -> {error, What}
@@ -211,15 +265,17 @@ do_start_child_i(M, F, A) ->
 	What ->
 	    {error, What}
     end.
-    
 
 %%% ---------------------------------------------------
 %%% 
 %%% Callback functions.
 %%% 
 %%% ---------------------------------------------------
+-type call() :: 'which_children' | 'count_children' | {_, _}.	% XXX: refine
+-spec handle_call(call(), term(), state()) -> {'reply', term(), state()}.
+
 handle_call({start_child, EArgs}, _From, State) when ?is_simple(State) ->
-    #child{mfa = {M, F, A}} = hd(State#state.children),
+    #child{mfargs = {M, F, A}} = hd(State#state.children),
     Args = A ++ EArgs,
     case do_start_child_i(M, F, Args) of
 	{ok, Pid} ->
@@ -235,7 +291,7 @@ handle_call({start_child, EArgs}, _From, State) when ?is_simple(State) ->
     end;
 
 %%% The requests terminate_child, delete_child and restart_child are 
-%%% invalid for simple_one_for_one supervisors. 
+%%% invalid for simple_one_for_one supervisors.
 handle_call({_Req, _Data}, _From, State) when ?is_simple(State) ->
     {reply, {error, simple_one_for_one}, State};
 
@@ -297,7 +353,7 @@ handle_call(which_children, _From, State) ->
     Resp =
 	lists:map(fun(#child{pid = Pid, name = Name,
 			     child_type = ChildType, modules = Mods}) ->
-		    {Name, Pid, ChildType, Mods}
+			  {Name, Pid, ChildType, Mods}
 		  end,
 		  State#state.children),
     {reply, Resp, State};
@@ -318,7 +374,6 @@ handle_call(count_children, _From, State) when ?is_simple(State) ->
     {reply, Reply, State};
 
 handle_call(count_children, _From, State) ->
-
     %% Specs and children are together on the children list...
     {Specs, Active, Supers, Workers} =
 	lists:foldl(fun(Child, Counts) ->
@@ -347,15 +402,19 @@ count_child(#child{pid = Pid, child_type = supervisor},
 
 %%% Hopefully cause a function-clause as there is no API function
 %%% that utilizes cast.
+-spec handle_cast('null', state()) -> {'noreply', state()}.
+
 handle_cast(null, State) ->
     error_logger:error_msg("ERROR: Supervisor received cast-message 'null'~n", 
 			   []),
-
     {noreply, State}.
 
 %%
 %% Take care of terminated children.
 %%
+-spec handle_info(term(), state()) ->
+        {'noreply', state()} | {'stop', 'shutdown', state()}.
+
 handle_info({'EXIT', Pid, Reason}, State) ->
     case restart_child(Pid, Reason, State) of
 	{ok, State1} ->
@@ -368,9 +427,12 @@ handle_info(Msg, State) ->
     error_logger:error_msg("Supervisor received unexpected message: ~p~n", 
 			   [Msg]),
     {noreply, State}.
+
 %%
 %% Terminate this server.
 %%
+-spec terminate(term(), state()) -> 'ok'.
+
 terminate(_Reason, State) ->
     terminate_children(State#state.children, State#state.name),
     ok.
@@ -384,6 +446,9 @@ terminate(_Reason, State) ->
 %% NOTE: This requires that the init function of the call-back module
 %%       does not have any side effects.
 %%
+-spec code_change(term(), state(), term()) ->
+        {'ok', state()} | {'error', term()}.
+
 code_change(_, State, _) ->
     case (State#state.module):init(State#state.args) of
 	{ok, {SupFlags, StartSpec}} ->
@@ -411,7 +476,7 @@ check_flags({Strategy, MaxIntensity, Period}) ->
 check_flags(What) ->
     {bad_flags, What}.
 
-update_childspec(State, StartSpec)  when ?is_simple(State) -> 
+update_childspec(State, StartSpec) when ?is_simple(State) ->
     case check_startspec(StartSpec) of                        
         {ok, [Child]} ->                                      
             {ok, State#state{children = [Child]}};            
@@ -437,7 +502,7 @@ update_childspec1([Child|OldC], Children, KeepOld) ->
 	    update_childspec1(OldC, Children, [Child|KeepOld])
     end;
 update_childspec1([], Children, KeepOld) ->
-    % Return them in (keeped) reverse start order.
+    %% Return them in (kept) reverse start order.
     lists:reverse(Children ++ KeepOld).  
 
 update_chsp(OldCh, Children) ->
@@ -482,7 +547,7 @@ handle_start_child(Child, State) ->
 
 %%% ---------------------------------------------------
 %%% Restart. A process has terminated.
-%%% Returns: {ok, #state} | {shutdown, #state}
+%%% Returns: {ok, state()} | {shutdown, state()}
 %%% ---------------------------------------------------
 
 restart_child(Pid, Reason, State) when ?is_simple(State) ->
@@ -490,19 +555,19 @@ restart_child(Pid, Reason, State) when ?is_simple(State) ->
 	{ok, Args} ->
 	    [Child] = State#state.children,
 	    RestartType = Child#child.restart_type,
-	    {M, F, _} = Child#child.mfa,
-	    NChild = Child#child{pid = Pid, mfa = {M, F, Args}},
+	    {M, F, _} = Child#child.mfargs,
+	    NChild = Child#child{pid = Pid, mfargs = {M, F, Args}},
 	    do_restart(RestartType, Reason, NChild, State);
 	error ->
 	    {ok, State}
     end;
 restart_child(Pid, Reason, State) ->
     Children = State#state.children,
-    case lists:keysearch(Pid, #child.pid, Children) of
-	{value, Child} ->
+    case lists:keyfind(Pid, #child.pid, Children) of
+	#child{} = Child ->
 	    RestartType = Child#child.restart_type,
 	    do_restart(RestartType, Reason, Child, State);
-	_ ->
+	false ->
 	    {ok, State}
     end.
 
@@ -534,7 +599,7 @@ restart(Child, State) ->
     end.
 
 restart(simple_one_for_one, Child, State) ->
-    #child{mfa = {M, F, A}} = Child,
+    #child{mfargs = {M, F, A}} = Child,
     Dynamics = ?DICT:erase(Child#child.pid, State#state.dynamics),
     case do_start_child_i(M, F, A) of
 	{ok, Pid} ->
@@ -580,9 +645,9 @@ restart(one_for_all, Child, State) ->
 
 %%-----------------------------------------------------------------
 %% Func: terminate_children/2
-%% Args: Children = [#child] in termination order
+%% Args: Children = [child()] in termination order
 %%       SupName = {local, atom()} | {global, atom()} | {pid(),Mod}
-%% Returns: NChildren = [#child] in
+%% Returns: NChildren = [child()] in
 %%          startup order (reversed termination order)
 %%-----------------------------------------------------------------
 terminate_children(Children, SupName) ->
@@ -617,7 +682,6 @@ do_terminate(Child, _SupName) ->
 %% Returns: ok | {error, OtherReason}  (this should be reported)
 %%-----------------------------------------------------------------
 shutdown(Pid, brutal_kill) ->
-  
     case monitor_child(Pid) of
 	ok ->
 	    exit(Pid, kill),
@@ -630,9 +694,7 @@ shutdown(Pid, brutal_kill) ->
 	{error, Reason} ->      
 	    {error, Reason}
     end;
-
 shutdown(Pid, Time) ->
-    
     case monitor_child(Pid) of
 	ok ->
 	    exit(Pid, shutdown), %% Try to shutdown gracefully
@@ -738,9 +800,9 @@ remove_child(Child, State) ->
 %%         MaxIntensity = integer()
 %%         Period = integer()
 %%       Mod :== atom()
-%%       Arsg :== term()
+%%       Args :== term()
 %% Purpose: Check that Type is of correct type (!)
-%% Returns: {ok, #state} | Error
+%% Returns: {ok, state()} | Error
 %%-----------------------------------------------------------------
 init_state(SupName, Type, Mod, Args) ->
     case catch init_state1(SupName, Type, Mod, Args) of
@@ -755,11 +817,11 @@ init_state1(SupName, {Strategy, MaxIntensity, Period}, Mod, Args) ->
     validIntensity(MaxIntensity),
     validPeriod(Period),
     {ok, #state{name = supname(SupName,Mod),
-	       strategy = Strategy,
-	       intensity = MaxIntensity,
-	       period = Period,
-	       module = Mod,
-	       args = Args}};
+		strategy = Strategy,
+		intensity = MaxIntensity,
+		period = Period,
+		module = Mod,
+		args = Args}};
 init_state1(_SupName, Type, _, _) ->
     {invalid_type, Type}.
 
@@ -771,26 +833,26 @@ validStrategy(What)               -> throw({invalid_strategy, What}).
 
 validIntensity(Max) when is_integer(Max),
                          Max >=  0 -> true;
-validIntensity(What)              -> throw({invalid_intensity, What}).
+validIntensity(What)               -> throw({invalid_intensity, What}).
 
 validPeriod(Period) when is_integer(Period),
                          Period > 0 -> true;
 validPeriod(What)                   -> throw({invalid_period, What}).
 
-supname(self,Mod) -> {self(),Mod};
-supname(N,_)      -> N.
+supname(self, Mod) -> {self(), Mod};
+supname(N, _)      -> N.
 
 %%% ------------------------------------------------------
 %%% Check that the children start specification is valid.
 %%% Shall be a six (6) tuple
 %%%    {Name, Func, RestartType, Shutdown, ChildType, Modules}
 %%% where Name is an atom
-%%%       Func is {Mod, Fun, Args} == {atom, atom, list}
+%%%       Func is {Mod, Fun, Args} == {atom(), atom(), list()}
 %%%       RestartType is permanent | temporary | transient
 %%%       Shutdown = integer() | infinity | brutal_kill
 %%%       ChildType = supervisor | worker
 %%%       Modules = [atom()] | dynamic
-%%% Returns: {ok, [#child]} | Error
+%%% Returns: {ok, [child()]} | Error
 %%% ------------------------------------------------------
 
 check_startspec(Children) -> check_startspec(Children, []).
@@ -818,14 +880,14 @@ check_childspec(Name, Func, RestartType, Shutdown, ChildType, Mods) ->
     validChildType(ChildType),
     validShutdown(Shutdown, ChildType),
     validMods(Mods),
-    {ok, #child{name = Name, mfa = Func, restart_type = RestartType,
+    {ok, #child{name = Name, mfargs = Func, restart_type = RestartType,
 		shutdown = Shutdown, child_type = ChildType, modules = Mods}}.
 
 validChildType(supervisor) -> true;
 validChildType(worker) -> true;
 validChildType(What) -> throw({invalid_child_type, What}).
 
-validName(_Name) -> true. 
+validName(_Name) -> true.
 
 validFunc({M, F, A}) when is_atom(M), 
                           is_atom(F), 
@@ -923,7 +985,7 @@ report_error(Error, Reason, Child, SupName) ->
 extract_child(Child) ->
     [{pid, Child#child.pid},
      {name, Child#child.name},
-     {mfa, Child#child.mfa},
+     {mfargs, Child#child.mfargs},
      {restart_type, Child#child.restart_type},
      {shutdown, Child#child.shutdown},
      {child_type, Child#child.child_type}].