Fix edoc usage errors

Errors discovered using `erldocs`:
  Superfluous @hidden tag would exit edoc application;
  'Multiple @spec tag': appended a @clear tag after macro condition;
  '@spec arity does not match': added missing argument.

10 files changed, 69 insertions, 51 deletions

diff --git a/lib/common_test/src/ct_framework.erl b/lib/common_test/src/ct_framework.erl
index 54510a657a..580588fbd2 100644
--- a/lib/common_test/src/ct_framework.erl
+++ b/lib/common_test/src/ct_framework.erl
@@ -1417,7 +1417,7 @@ warn(_What) ->
     true.
 
 %%%-----------------------------------------------------------------
-%%% @spec add_data_dir(File0) -> File1
+%%% @spec add_data_dir(File0, Config) -> File1
 add_data_dir(File,Config) when is_atom(File) ->
     add_data_dir(atom_to_list(File),Config);
 
diff --git a/lib/common_test/src/ct_logs.erl b/lib/common_test/src/ct_logs.erl
index a7fb45a4e4..a4ad65c0a4 100644
--- a/lib/common_test/src/ct_logs.erl
+++ b/lib/common_test/src/ct_logs.erl
@@ -76,7 +76,7 @@
 		    tests = []}).
 
 %%%-----------------------------------------------------------------
-%%% @spec init(Mode) -> Result
+%%% @spec init(Mode, Verbosity) -> Result
 %%%   Mode = normal | interactive
 %%%   Result = {StartTime,LogDir}
 %%%   StartTime = term()
diff --git a/lib/common_test/src/ct_util.erl b/lib/common_test/src/ct_util.erl
index ac9857487d..f5eb3a72f0 100644
--- a/lib/common_test/src/ct_util.erl
+++ b/lib/common_test/src/ct_util.erl
@@ -77,6 +77,8 @@
 -record(suite_data, {key,name,value}).
 
 %%%-----------------------------------------------------------------
+start() ->
+    start(normal, ".", ?default_verbosity).
 %%% @spec start(Mode) -> Pid | exit(Error)
 %%%       Mode = normal | interactive
 %%%       Pid = pid()
@@ -91,9 +93,6 @@
 %%% <code>ct_util_server</code>.</p>
 %%%
 %%% @see ct
-start() ->
-    start(normal, ".", ?default_verbosity).
-
 start(LogDir) when is_list(LogDir) ->
     start(normal, LogDir, ?default_verbosity);
 start(Mode) ->
diff --git a/lib/compiler/src/rec_env.erl b/lib/compiler/src/rec_env.erl
index 31a1f8b0b7..a31413251a 100644
--- a/lib/compiler/src/rec_env.erl
+++ b/lib/compiler/src/rec_env.erl
@@ -72,6 +72,7 @@ test_1({custom, F} = Type, N, Env) when is_integer(N), N > 0 ->
 test_1(_,0, Env) ->
     Env.
 -endif.
+%%@clear
 
 
 %% Representation:
diff --git a/lib/dialyzer/src/dialyzer_utils.erl b/lib/dialyzer/src/dialyzer_utils.erl
index a4c4d37a0f..c077f73525 100644
--- a/lib/dialyzer/src/dialyzer_utils.erl
+++ b/lib/dialyzer/src/dialyzer_utils.erl
@@ -450,11 +450,10 @@ flat_format(Fmt, Lst) ->
 %% Created     : 5 March 2007
 %%-------------------------------------------------------------------
 
+-spec pp_hook() -> fun((cerl:cerl(), _, _) -> term()).
 pp_hook() ->
   fun pp_hook/3.
 
--spec pp_hook() -> fun((cerl:cerl(), _, _) -> term()).
-
 pp_hook(Node, Ctxt, Cont) ->
   case cerl:type(Node) of
     binary ->
diff --git a/lib/ssl/src/dtls.erl b/lib/ssl/src/dtls.erl
index 1cad9560b5..780bddeb10 100644
--- a/lib/ssl/src/dtls.erl
+++ b/lib/ssl/src/dtls.erl
@@ -31,25 +31,29 @@
 	 handshake/1, handshake/2, handshake/3]).
 
 %%--------------------------------------------------------------------
+%%
+%% Description: Connect to a DTLS server.
+%%--------------------------------------------------------------------
+
 -spec connect(host() | port(), [connect_option()]) -> {ok, #sslsocket{}} |
 					      {error, reason()}.
+
+connect(Socket, Options) when is_port(Socket) ->
+    connect(Socket, Options, infinity).
+
 -spec connect(host() | port(), [connect_option()] | inet:port_number(),
 	      timeout() | list()) ->
 		     {ok, #sslsocket{}} | {error, reason()}.
--spec connect(host() | port(), inet:port_number(), list(), timeout()) ->
-		     {ok, #sslsocket{}} | {error, reason()}.
-
-%%
-%% Description: Connect to an DTLS server.
-%%--------------------------------------------------------------------
 
-connect(Socket, Options) when is_port(Socket) ->
-    connect(Socket, Options, infinity).
 connect(Socket, SslOptions, Timeout)  when is_port(Socket) ->
     DTLSOpts = [{protocol, dtls} | SslOptions],
     ssl:connect(Socket, DTLSOpts, Timeout);
 connect(Host, Port, Options) ->
     connect(Host, Port, Options, infinity).
+
+-spec connect(host() | port(), inet:port_number(), list(), timeout()) ->
+		     {ok, #sslsocket{}} | {error, reason()}.
+
 connect(Host, Port, Options, Timeout) ->
     DTLSOpts = [{protocol, dtls} | Options],
     ssl:connect(Host, Port, DTLSOpts, Timeout).
@@ -65,38 +69,44 @@ listen(Port, Options) ->
     ssl:listen(Port, DTLSOpts).
 
 %%--------------------------------------------------------------------
--spec accept(#sslsocket{}) -> {ok, #sslsocket{}} |
-					{error, reason()}.
--spec accept(#sslsocket{}, timeout()) -> {ok, #sslsocket{}} |
-						   {error, reason()}.
 %%
 %% Description: Performs transport accept on an ssl listen socket
 %%--------------------------------------------------------------------
+-spec accept(#sslsocket{}) -> {ok, #sslsocket{}} |
+					{error, reason()}.
 accept(ListenSocket) ->
     accept(ListenSocket, infinity).
+
+-spec accept(#sslsocket{}, timeout()) -> {ok, #sslsocket{}} |
+						   {error, reason()}.
 accept(Socket, Timeout) ->
     ssl:transport_accept(Socket, Timeout).
 
 %%--------------------------------------------------------------------
--spec handshake(#sslsocket{}) -> ok | {error, reason()}.
--spec handshake(#sslsocket{} | port(), timeout()| [ssl_option()
-						    | transport_option()]) ->
-			ok | {ok, #sslsocket{}} | {error, reason()}.
--spec handshake(port(), [ssl_option()| transport_option()], timeout()) ->
-			{ok, #sslsocket{}} | {error, reason()}.
 %%
 %% Description: Performs accept on an ssl listen socket. e.i. performs
 %%              ssl handshake.
 %%--------------------------------------------------------------------
 
+-spec handshake(#sslsocket{}) -> ok | {error, reason()}.
+
 handshake(ListenSocket) ->
     handshake(ListenSocket, infinity).
 
+
+-spec handshake(#sslsocket{} | port(), timeout()| [ssl_option()
+						    | transport_option()]) ->
+			ok | {ok, #sslsocket{}} | {error, reason()}.
+
 handshake(#sslsocket{} = Socket, Timeout) ->
     ssl:ssl_accept(Socket, Timeout);
 
 handshake(ListenSocket, SslOptions)  when is_port(ListenSocket) ->
     handshake(ListenSocket, SslOptions, infinity).
 
+
+-spec handshake(port(), [ssl_option()| transport_option()], timeout()) ->
+			{ok, #sslsocket{}} | {error, reason()}.
+
 handshake(Socket, SslOptions, Timeout) when is_port(Socket) ->
     ssl:ssl_accept(Socket, SslOptions, Timeout).
diff --git a/lib/ssl/src/ssl_manager.erl b/lib/ssl/src/ssl_manager.erl
index 4d5eaeb607..fbc73e0e42 100644
--- a/lib/ssl/src/ssl_manager.erl
+++ b/lib/ssl/src/ssl_manager.erl
@@ -167,27 +167,27 @@ clean_cert_db(Ref, File) ->
     ok.
 
 %%--------------------------------------------------------------------
--spec register_session(inet:port_number(), #session{}) -> ok.
--spec register_session(host(), inet:port_number(), #session{}) -> ok.
 %%
 %% Description: Make the session available for reuse.
 %%--------------------------------------------------------------------
+-spec register_session(host(), inet:port_number(), #session{}) -> ok.
 register_session(Host, Port, Session) ->
     cast({register_session, Host, Port, Session}).
 
+-spec register_session(inet:port_number(), #session{}) -> ok.
 register_session(Port, Session) ->
     cast({register_session, Port, Session}).
 %%--------------------------------------------------------------------
--spec invalidate_session(inet:port_number(), #session{}) -> ok.
--spec invalidate_session(host(), inet:port_number(), #session{}) -> ok.
 %%
 %% Description: Make the session unavailable for reuse. After
 %% a the session has been marked "is_resumable = false" for some while
 %% it will be safe to remove the data from the session database.
 %%--------------------------------------------------------------------
+-spec invalidate_session(host(), inet:port_number(), #session{}) -> ok.
 invalidate_session(Host, Port, Session) ->
     cast({invalidate_session, Host, Port, Session}).
 
+-spec invalidate_session(inet:port_number(), #session{}) -> ok.
 invalidate_session(Port, Session) ->
     cast({invalidate_session, Port, Session}).
 
diff --git a/lib/ssl/src/ssl_pkix_db.erl b/lib/ssl/src/ssl_pkix_db.erl
index 9de50c8f26..e59aba0618 100644
--- a/lib/ssl/src/ssl_pkix_db.erl
+++ b/lib/ssl/src/ssl_pkix_db.erl
@@ -115,17 +115,17 @@ add_trusted_certs(_Pid, File, [CertsDb, RefDb, PemChache] = Db) ->
 	    new_trusted_cert_entry({MD5, File}, Db)
     end.
 %%--------------------------------------------------------------------
--spec cache_pem_file({binary(), binary()}, [db_handle()]) -> {ok, term()}.
--spec cache_pem_file(reference(), {binary(), binary()}, [db_handle()]) -> {ok, term()}.
 %%
 %% Description: Cache file as binary in DB
 %%--------------------------------------------------------------------
+-spec cache_pem_file({binary(), binary()}, [db_handle()]) -> {ok, term()}.
 cache_pem_file({MD5, File}, [_CertsDb, _RefDb, PemChache]) ->
     {ok, PemBin} = file:read_file(File),
     Content = public_key:pem_decode(PemBin),
     insert(MD5, Content, PemChache),
     {ok, Content}.
 
+-spec cache_pem_file(reference(), {binary(), binary()}, [db_handle()]) -> {ok, term()}.
 cache_pem_file(Ref, {MD5, File}, [_CertsDb, _RefDb, PemChache]) ->
     {ok, PemBin} = file:read_file(File),
     Content = public_key:pem_decode(PemBin),
diff --git a/lib/ssl/src/tls.erl b/lib/ssl/src/tls.erl
index 3e7b2db9c2..c829129250 100644
--- a/lib/ssl/src/tls.erl
+++ b/lib/ssl/src/tls.erl
@@ -30,25 +30,29 @@
 	 handshake/1, handshake/2, handshake/3]).
 
 %%--------------------------------------------------------------------
--spec connect(host() | port(), [connect_option()]) -> {ok, #sslsocket{}} |
-					      {error, reason()}.
--spec connect(host() | port(), [connect_option()] | inet:port_number(), 
-	      timeout() | list()) ->
-		     {ok, #sslsocket{}} | {error, reason()}.
--spec connect(host() | port(), inet:port_number(), list(), timeout()) ->
-		     {ok, #sslsocket{}} | {error, reason()}.
-
 %%
 %% Description: Connect to an TLS server.
 %%--------------------------------------------------------------------
 
+-spec connect(host() | port(), [connect_option()]) -> {ok, #sslsocket{}} |
+					      {error, reason()}.
+
 connect(Socket, Options) when is_port(Socket) ->
     connect(Socket, Options, infinity).
+
+-spec connect(host() | port(), [connect_option()] | inet:port_number(),
+	      timeout() | list()) ->
+		     {ok, #sslsocket{}} | {error, reason()}.
+
 connect(Socket, SslOptions, Timeout)  when is_port(Socket) ->
     TLSOpts = [{protocol, tls} | SslOptions],
     ssl:connect(Socket, TLSOpts, Timeout);
 connect(Host, Port, Options) ->
     connect(Host, Port, Options, infinity).
+
+-spec connect(host() | port(), inet:port_number(), list(), timeout()) ->
+		     {ok, #sslsocket{}} | {error, reason()}.
+
 connect(Host, Port, Options, Timeout) ->
     TLSOpts = [{protocol, tls} | Options],
     ssl:connect(Host, Port, TLSOpts, Timeout).
@@ -64,39 +68,44 @@ listen(Port, Options) ->
     ssl:listen(Port, TLSOpts).
 
 %%--------------------------------------------------------------------
--spec accept(#sslsocket{}) -> {ok, #sslsocket{}} |
-					{error, reason()}.
--spec accept(#sslsocket{}, timeout()) -> {ok, #sslsocket{}} |
-						   {error, reason()}.
 %%
 %% Description: Performs transport accept on an ssl listen socket
 %%--------------------------------------------------------------------
+-spec accept(#sslsocket{}) -> {ok, #sslsocket{}} |
+					{error, reason()}.
 accept(ListenSocket) ->
     accept(ListenSocket, infinity).
+
+-spec accept(#sslsocket{}, timeout()) -> {ok, #sslsocket{}} |
+						   {error, reason()}.
 accept(Socket, Timeout) ->
     ssl:transport_accept(Socket, Timeout).
 
 %%--------------------------------------------------------------------
--spec handshake(#sslsocket{}) -> ok | {error, reason()}.
--spec handshake(#sslsocket{} | port(), timeout()| [ssl_option()
-						    | transport_option()]) ->
-			ok | {ok, #sslsocket{}} | {error, reason()}.
--spec handshake(port(), [ssl_option()| transport_option()], timeout()) ->
-			{ok, #sslsocket{}} | {error, reason()}.
 %%
 %% Description: Performs accept on an ssl listen socket. e.i. performs
 %%              ssl handshake. 
 %%--------------------------------------------------------------------
 
+-spec handshake(#sslsocket{}) -> ok | {error, reason()}.
+
 handshake(ListenSocket) ->
     handshake(ListenSocket, infinity).
 
 
+-spec handshake(#sslsocket{} | port(), timeout()| [ssl_option()
+						    | transport_option()]) ->
+			ok | {ok, #sslsocket{}} | {error, reason()}.
+
 handshake(#sslsocket{} = Socket, Timeout) ->
     ssl:ssl_accept(Socket, Timeout);
     
 handshake(ListenSocket, SslOptions)  when is_port(ListenSocket) ->
     handshake(ListenSocket, SslOptions, infinity).
 
+
+-spec handshake(port(), [ssl_option()| transport_option()], timeout()) ->
+			{ok, #sslsocket{}} | {error, reason()}.
+
 handshake(Socket, SslOptions, Timeout) when is_port(Socket) ->
     ssl:ssl_accept(Socket, SslOptions, Timeout).
diff --git a/lib/ssl/src/tls_record.erl b/lib/ssl/src/tls_record.erl
index 88107557a0..8c0c4f3c91 100644
--- a/lib/ssl/src/tls_record.erl
+++ b/lib/ssl/src/tls_record.erl
@@ -262,18 +262,18 @@ supported_protocol_versions([_|_] = Vsns) ->
     Vsns.
 
 %%--------------------------------------------------------------------
--spec is_acceptable_version(tls_version()) -> boolean().
--spec is_acceptable_version(tls_version(), Supported :: [tls_version()]) -> boolean().
 %%     
 %% Description: ssl version 2 is not acceptable security risks are too big.
 %% 
 %%--------------------------------------------------------------------
+-spec is_acceptable_version(tls_version()) -> boolean().
 is_acceptable_version({N,_}) 
   when N >= ?LOWEST_MAJOR_SUPPORTED_VERSION ->
     true;
 is_acceptable_version(_) ->
     false.
 
+-spec is_acceptable_version(tls_version(), Supported :: [tls_version()]) -> boolean().
 is_acceptable_version({N,_} = Version, Versions)   
   when N >= ?LOWEST_MAJOR_SUPPORTED_VERSION ->
     lists:member(Version, Versions);