Types and specifications have been modified and added

1 files changed, 67 insertions, 84 deletions

diff --git a/lib/stdlib/src/proplists.erl b/lib/stdlib/src/proplists.erl
index 6a45e0f868..68697d0da2 100644
--- a/lib/stdlib/src/proplists.erl
+++ b/lib/stdlib/src/proplists.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 2001-2010. All Rights Reserved.
+%% Copyright Ericsson AB 2001-2011. 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
@@ -37,7 +37,7 @@
 %% overriding the default settings, object properties, annotations,
 %% etc.</p>
 %%
-%% @type property() = atom() | tuple()
+%% % @type property() = atom() | tuple()
 
 -module(proplists).
 
@@ -53,14 +53,8 @@
 
 -type property()   :: atom() | tuple().
 
--type aliases()    :: [{any(), any()}].
--type negations()  :: [{any(), any()}].
--type expansions() :: [{property(), [any()]}].
-
 %% ---------------------------------------------------------------------
 
-%% @spec property(P::property()) -> property()
-%%
 %% @doc Creates a normal form (minimal) representation of a property. If
 %% <code>P</code> is <code>{Key, true}</code> where <code>Key</code> is
 %% an atom, this returns <code>Key</code>, otherwise the whole term
@@ -68,7 +62,8 @@
 %%
 %% @see property/2
 
--spec property(property()) -> property().
+-spec property(Property) -> Property when
+      Property :: property().
 
 property({Key, true}) when is_atom(Key) ->
     Key;
@@ -76,8 +71,6 @@ property(Property) ->
     Property.
 
 
-%% @spec property(Key::term(), Value::term()) -> property()
-%%
 %% @doc Creates a normal form (minimal) representation of a simple
 %% key/value property. Returns <code>Key</code> if <code>Value</code> is
 %% <code>true</code> and <code>Key</code> is an atom, otherwise a tuple
@@ -85,7 +78,10 @@ property(Property) ->
 %%
 %% @see property/1
 
--spec property(Key::term(), Value::term()) -> atom() | {term(), term()}.
+-spec property(Key, Value) -> Property when
+      Key :: term(),
+      Value :: term(),
+      Property :: atom() | {term(), term()}.
 
 property(Key, true) when is_atom(Key) ->
     Key;
@@ -95,14 +91,13 @@ property(Key, Value) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec unfold(List::[term()]) -> [term()]
-%%
 %% @doc Unfolds all occurences of atoms in <code>List</code> to tuples
 %% <code>{Atom, true}</code>.
 %%
 %% @see compact/1
 
--spec unfold(List::[term()]) -> [term()].
+-spec unfold(List) -> List when
+      List :: [term()].
 
 unfold([P | Ps]) ->
     if is_atom(P) ->
@@ -113,15 +108,14 @@ unfold([P | Ps]) ->
 unfold([]) ->
     [].
 
-%% @spec compact(List::[term()]) -> [term()]
-%%
 %% @doc Minimizes the representation of all entries in the list. This is
 %% equivalent to <code>[property(P) || P &lt;- List]</code>.
 %%
 %% @see unfold/1
 %% @see property/1
 
--spec compact(List::[property()]) -> [property()].
+-spec compact(List) -> List when
+      List :: [property()].
 
 compact(List) ->
     [property(P) || P <- List].
@@ -129,8 +123,6 @@ compact(List) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec lookup(Key::term(), List::[term()]) -> none | tuple()
-%%
 %% @doc Returns the first entry associated with <code>Key</code> in
 %% <code>List</code>, if one exists, otherwise returns
 %% <code>none</code>. For an atom <code>A</code> in the list, the tuple
@@ -140,7 +132,9 @@ compact(List) ->
 %% @see get_value/2
 %% @see get_bool/2
 
--spec lookup(Key::term(), List::[term()]) -> 'none' | tuple().
+-spec lookup(Key, List) -> 'none' | tuple() when
+      Key :: term(),
+      List :: [term()].
 
 lookup(Key, [P | Ps]) ->
     if is_atom(P), P =:= Key ->
@@ -154,15 +148,15 @@ lookup(Key, [P | Ps]) ->
 lookup(_Key, []) ->
     none.
 
-%% @spec lookup_all(Key::term(), List::[term()]) -> [tuple()]
-%%
 %% @doc Returns the list of all entries associated with <code>Key</code>
 %% in <code>List</code>. If no such entry exists, the result is the
 %% empty list.
 %%
 %% @see lookup/2
 
--spec lookup_all(Key::term(), List::[term()]) -> [tuple()].
+-spec lookup_all(Key, List) -> [tuple()] when
+      Key :: term(),
+      List :: [term()].
 
 lookup_all(Key, [P | Ps]) ->
     if is_atom(P), P =:= Key ->
@@ -178,13 +172,13 @@ lookup_all(_Key, []) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec is_defined(Key::term(), List::[term()]) -> boolean()
-%%
 %% @doc Returns <code>true</code> if <code>List</code> contains at least
 %% one entry associated with <code>Key</code>, otherwise
 %% <code>false</code> is returned.
 
--spec is_defined(Key::term(), List::[term()]) -> boolean().
+-spec is_defined(Key, List) -> boolean() when
+      Key :: term(),
+      List :: [term()].
 
 is_defined(Key, [P | Ps]) ->
     if is_atom(P), P =:= Key ->
@@ -200,17 +194,15 @@ is_defined(_Key, []) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec get_value(Key::term(), List::[term()]) -> term()
 %% @equiv get_value(Key, List, undefined)
 
--spec get_value(Key::term(), List::[term()]) -> term().
+-spec get_value(Key, List) -> term() when
+      Key :: term(),
+      List :: List::[term()].
 
 get_value(Key, List) ->
     get_value(Key, List, undefined).
 
-%% @spec get_value(Key::term(), List::[term()], Default::term()) ->
-%%         term()
-%%
 %% @doc Returns the value of a simple key/value property in
 %% <code>List</code>. If <code>lookup(Key, List)</code> would yield
 %% <code>{Key, Value}</code>, this function returns the corresponding
@@ -221,7 +213,10 @@ get_value(Key, List) ->
 %% @see get_all_values/2
 %% @see get_bool/2
 
--spec get_value(Key::term(), List::[term()], Default::term()) -> term().
+-spec get_value(Key, List, Default) -> term() when
+      Key :: term(),
+      List :: [term()],
+      Default :: term().
 
 get_value(Key, [P | Ps], Default) ->
     if is_atom(P), P =:= Key ->
@@ -240,8 +235,6 @@ get_value(Key, [P | Ps], Default) ->
 get_value(_Key, [], Default) ->
     Default.
 
-%% @spec get_all_values(Key, List) -> [term()]
-%%
 %% @doc Similar to <code>get_value/2</code>, but returns the list of
 %% values for <em>all</em> entries <code>{Key, Value}</code> in
 %% <code>List</code>. If no such entry exists, the result is the empty
@@ -249,7 +242,9 @@ get_value(_Key, [], Default) ->
 %%
 %% @see get_value/2
 
--spec get_all_values(Key::term(), List::[term()]) -> [term()].
+-spec get_all_values(Key, List) -> [term()] when
+      Key :: term(),
+      List :: [term()].
 
 get_all_values(Key, [P | Ps]) ->
     if is_atom(P), P =:= Key ->
@@ -267,8 +262,6 @@ get_all_values(Key, [P | Ps]) ->
 get_all_values(_Key, []) ->
     [].
 
-%% @spec append_values(Key::term(), List::[term()]) -> [term()]
-%%
 %% @doc Similar to <code>get_all_values/2</code>, but each value is
 %% wrapped in a list unless it is already itself a list, and the
 %% resulting list of lists is concatenated. This is often useful for
@@ -278,7 +271,9 @@ get_all_values(_Key, []) ->
 %%
 %% @see get_all_values/2
 
--spec append_values(Key::term(), List::[term()]) -> [term()].
+-spec append_values(Key, List) -> List when
+      Key :: term(),
+      List :: [term()].
 
 append_values(Key, [P | Ps]) ->
     if is_atom(P), P =:= Key ->
@@ -301,8 +296,6 @@ append_values(_Key, []) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec get_bool(Key::term(), List::[term()]) -> boolean()
-%%
 %% @doc Returns the value of a boolean key/value option. If
 %% <code>lookup(Key, List)</code> would yield <code>{Key, true}</code>,
 %% this function returns <code>true</code>; otherwise <code>false</code>
@@ -311,7 +304,9 @@ append_values(_Key, []) ->
 %% @see lookup/2
 %% @see get_value/2
 
--spec get_bool(Key::term(), List::[term()]) -> boolean().
+-spec get_bool(Key, List) -> boolean() when
+      Key :: term(),
+      List :: [term()].
 
 get_bool(Key, [P | Ps]) ->
     if is_atom(P), P =:= Key ->
@@ -333,12 +328,11 @@ get_bool(_Key, []) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec get_keys(List::[term()]) -> [term()]
-%%
 %% @doc Returns an unordered list of the keys used in <code>List</code>,
 %% not containing duplicates.
 
--spec get_keys(List::[term()]) -> [term()].
+-spec get_keys(List) -> [term()] when
+      List :: [term()].
 
 get_keys(Ps) ->
     sets:to_list(get_keys(Ps, sets:new())).
@@ -357,12 +351,12 @@ get_keys([], Keys) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec delete(Key::term(), List::[term()]) -> [term()]
-%%
 %% @doc Deletes all entries associated with <code>Key</code> from
 %% <code>List</code>.
 
--spec delete(Key::term(), List::[term()]) -> [term()].
+-spec delete(Key, List) -> List when
+      Key :: term(),
+      List::[term()].
 
 delete(Key, [P | Ps]) ->
     if is_atom(P), P =:= Key ->
@@ -378,11 +372,6 @@ delete(_, []) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec substitute_aliases(Aliases, List::[term()]) -> [term()]
-%%
-%%	    Aliases = [{Key, Key}]
-%%	    Key = term()
-%%
 %% @doc Substitutes keys of properties. For each entry in
 %% <code>List</code>, if it is associated with some key <code>K1</code>
 %% such that <code>{K1, K2}</code> occurs in <code>Aliases</code>, the
@@ -398,7 +387,10 @@ delete(_, []) ->
 %% @see substitute_negations/2
 %% @see normalize/2
 
--spec substitute_aliases(aliases(), List::[term()]) -> [term()].
+-spec substitute_aliases(Aliases, List) -> List when
+      Aliases :: [{Key, Key}],
+      Key :: term(),
+      List::[term()].
 
 substitute_aliases(As, Props) ->
     [substitute_aliases_1(As, P) || P <- Props].
@@ -417,11 +409,6 @@ substitute_aliases_1([], P) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec substitute_negations(Negations, List::[term()]) -> [term()]
-%%
-%%	    Negations = [{Key, Key}]
-%%	    Key = term()
-%%
 %% @doc Substitutes keys of boolean-valued properties and simultaneously
 %% negates their values. For each entry in <code>List</code>, if it is
 %% associated with some key <code>K1</code> such that <code>{K1,
@@ -443,7 +430,10 @@ substitute_aliases_1([], P) ->
 %% @see substitute_aliases/2
 %% @see normalize/2
 
--spec substitute_negations(negations(), List::[term()]) -> [term()].
+-spec substitute_negations(Negations, List) -> List when
+      Negations :: [{Key, Key}],
+      Key :: term(),
+      List :: [term()].
 
 substitute_negations(As, Props) ->
     [substitute_negations_1(As, P) || P <- Props].
@@ -472,10 +462,6 @@ substitute_negations_1([], P) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec expand(Expansions, List::[term()]) -> [term()]
-%%
-%%	    Expansions = [{property(), [term()]}]
-%%
 %% @doc Expands particular properties to corresponding sets of
 %% properties (or other terms). For each pair <code>{Property,
 %% Expansion}</code> in <code>Expansions</code>, if <code>E</code> is
@@ -510,7 +496,9 @@ substitute_negations_1([], P) ->
 %%
 %% @see normalize/2
 
--spec expand(Expansions::expansions(), [term()]) -> [term()].
+-spec expand(Expansions, List) -> List when
+      Expansions :: [{Property :: property(), Expansion :: [term()]}],
+      List :: [term()].
 
 expand(Es, Ps) when is_list(Ps) ->
     Es1 = [{property(P), V} || {P, V} <- Es],
@@ -589,15 +577,6 @@ flatten([]) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec normalize(List::[term()], Stages::[Operation]) -> [term()]
-%%
-%%	    Operation = {aliases, Aliases} | {negations, Negations}
-%%                    | {expand, Expansions}
-%%	    Aliases = [{Key, Key}]
-%%	    Negations = [{Key, Key}]
-%%	    Key = term()
-%%	    Expansions = [{property(), [term()]}]
-%%
 %% @doc Passes <code>List</code> through a sequence of
 %% substitution/expansion stages. For an <code>aliases</code> operation,
 %% the function <code>substitute_aliases/2</code> is applied using the
@@ -619,11 +598,15 @@ flatten([]) ->
 %% @see expand/2
 %% @see compact/1
 
--type operation() :: {'aliases', aliases()}
-                   | {'negations', negations()}
-                   | {'expand', expansions()}.
-
--spec normalize(List::[term()], Stages::[operation()]) -> [term()].
+-spec normalize(List, Stages) -> List when
+      List :: [term()],
+      Stages :: [Operation],
+      Operation :: {'aliases', Aliases}
+                 | {'negations', Negations}
+                 | {'expand', Expansions},
+      Aliases :: [{Key, Key}],
+      Negations :: [{Key, Key}],
+      Expansions :: [{Property :: property(), Expansion :: [term()]}].
 
 normalize(L, [{aliases, As} | Xs]) ->
     normalize(substitute_aliases(As, L), Xs);
@@ -636,10 +619,6 @@ normalize(L, []) ->
 
 %% ---------------------------------------------------------------------
 
-%% @spec split(List::[term()], Keys::[term()]) -> {Lists, Rest}
-%%           Lists = [[term()]]
-%%           Rest = [term()]
-%%
 %% @doc Partitions <code>List</code> into a list of sublists and a
 %% remainder. <code>Lists</code> contains one sublist for each key in
 %% <code>Keys</code>, in the corresponding order. The relative order of
@@ -654,7 +633,11 @@ normalize(L, []) ->
 %% {[[a], [{b, 5}, b],[{c, 2}, {c, 3, 4}]], [{e, 1}, d]}</pre>
 %% </p>
 
--spec split(List::[term()], Keys::[term()]) -> {[[term()]], [term()]}.
+-spec split(List, Keys) -> {Lists, Rest} when
+      List :: [term()],
+      Keys :: [term()],
+      Lists :: [[term()]],
+      Rest :: [term()].
 
 split(List, Keys) ->
     {Store, Rest} = split(List, dict:from_list([{K, []} || K <- Keys]), []),