Refreshed documentation to reflect the change of default implementation.

Started to improve code documentation by using -spec directive, and
some small refactorings to avoid ugly code.

1 files changed, 14 insertions, 31 deletions

diff --git a/lib/ssl/src/ssl_session_cache.erl b/lib/ssl/src/ssl_session_cache.erl
index 1f2d1fc7d3..823bf7acfa 100644
--- a/lib/ssl/src/ssl_session_cache.erl
+++ b/lib/ssl/src/ssl_session_cache.erl
@@ -22,13 +22,16 @@
 
 -behaviour(ssl_session_cache_api).
 
+-include("ssl_handshake.hrl").
+-include("ssl_internal.hrl").
+
 -export([init/1, terminate/1, lookup/2, update/3, delete/2, foldl/3, 
 	 select_session/2]). 
 
+-type key() :: {{host(), port_num()}, session_id()} |  {port_num(), session_id()}.
+
 %%--------------------------------------------------------------------
-%% Function: init() -> Cache  
-%%
-%%	Cache - Reference to the cash (opaque)    
+-spec init(list()) -> cache_ref(). %% Returns reference to the cache (opaque)    
 %%
 %% Description: Return table reference. Called by ssl_manager process. 
 %%--------------------------------------------------------------------
@@ -36,9 +39,7 @@ init(_) ->
     ets:new(cache_name(), [set, protected]).
 
 %%--------------------------------------------------------------------
-%% Function: terminate(Cache) -> 
-%%
-%%      Cache - as returned by create/0
+-spec terminate(cache_ref()) -> any(). %%    
 %%
 %% Description: Handles cache table at termination of ssl manager. 
 %%--------------------------------------------------------------------
@@ -46,9 +47,7 @@ terminate(Cache) ->
     ets:delete(Cache).
 
 %%--------------------------------------------------------------------
-%% Function: lookup(Cache, Key) -> Session | undefined   
-%%      Cache - as returned by create/0   
-%%      Session = #session{}
+-spec lookup(cache_ref(), key()) -> #session{} | undefined.
 %%
 %% Description: Looks up a cach entry. Should be callable from any
 %% process.
@@ -62,9 +61,7 @@ lookup(Cache, Key) ->
     end.
 
 %%--------------------------------------------------------------------
-%% Function: update(Cache, Key, Session) -> _
-%%      Cache - as returned by create/0
-%%      Session = #session{}
+-spec update(cache_ref(), key(), #session{}) -> any().
 %%
 %% Description: Caches a new session or updates a already cached one.
 %% Will only be called from the ssl_manager process.
@@ -73,11 +70,7 @@ update(Cache, Key, Session) ->
     ets:insert(Cache, {Key, Session}).
 
 %%--------------------------------------------------------------------
-%% Function: delete(Cache, HostIP, Port, Id) -> _
-%%      Cache - as returned by create/0   
-%%      HostIP =  Host = string() | ipadress()
-%%      Port =  integer()
-%%      Id = 
+-spec delete(cache_ref(), key()) -> any().
 %%
 %% Description: Delets a cache entry.
 %% Will only be called from the ssl_manager process.
@@ -86,28 +79,19 @@ delete(Cache, Key) ->
     ets:delete(Cache, Key).
 
 %%--------------------------------------------------------------------
-%% Function: foldl(Fun, Acc0, Cache) -> Acc
-%%   
-%%	Fun  - fun()
-%%      Acc0  - term()
-%%      Cache  - cache_ref()
-%%
+-spec foldl(fun(), term(), cache_ref()) -> term().
 %%
 %% Description: Calls Fun(Elem, AccIn) on successive elements of the
 %% cache, starting with AccIn == Acc0. Fun/2 must return a new
 %% accumulator which is passed to the next call. The function returns
-%% the final value of the accumulator. Acc0 is returned if the cache is
-%% empty. 
-%% Should be callable from any process
+%% the final value of the accumulator. Acc0 is returned if the cache
+%% is empty.Should be callable from any process
 %%--------------------------------------------------------------------
 foldl(Fun, Acc0, Cache) ->
     ets:foldl(Fun, Acc0, Cache).
   
 %%--------------------------------------------------------------------
-%% Function: select_session(Cache, PartialKey) -> [Sessions]
-%%
-%%     Cache - as returned by create/0   
-%%     PartialKey - opaque  Key = {PartialKey, SessionId}
+-spec select_session(cache_ref(), {host(), port_num()} | port_num()) -> [#session{}].
 %%
 %% Description: Selects a session that could be reused. Should be callable
 %% from any process.
@@ -119,6 +103,5 @@ select_session(Cache, PartialKey) ->
 %%--------------------------------------------------------------------
 %%% Internal functions
 %%--------------------------------------------------------------------
-
 cache_name() ->
     ssl_otp_session_cache.