Merge branch 'fenollp/otp-edoc-usage-fixes'

* fenollp/otp-edoc-usage-fixes:
  Fix edoc usage errors

OTP-11702

5 files changed, 63 insertions, 44 deletions

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);