Add missing specs to different modules

esl · Jan 20, 2025 · 9495a64 · 9495a64
1 parent a9509dc
commit 9495a64
Show file tree

Hide file tree

Showing 12 changed files with 180 additions and 28 deletions.
diff --git a/src/escalus.erl b/src/escalus.erl
@@ -136,46 +136,60 @@ story(Config, ResourceCounts, Story) ->
 
 %% Assertions
 
+-spec assert(atom(), term()) -> ok | no_return().
 assert(PredSpec, Arg) ->
     escalus_new_assert:assert(PredSpec, Arg).
 
+-spec assert(atom(), [term()], term()) -> ok | no_return().
 assert(PredSpec, Params, Arg) ->
     escalus_new_assert:assert(PredSpec, Params, Arg).
 
+-spec assert_many([atom()], [exml:element()]) -> ok | no_return().
 assert_many(Predicates, Stanzas) ->
     escalus_new_assert:assert_many(Predicates, Stanzas).
 
 %% Client API
 
+-spec send(client(), exml:element()) -> ok.
 send(Client, Packet) ->
     escalus_client:send(Client, Packet).
 
+-spec send_and_wait(client(), exml:element()) -> exml:element().
 send_and_wait(Client, Packet) ->
     escalus_client:send_and_wait(Client, Packet).
 
+-spec wait_for_stanza(client()) -> exml:element().
 wait_for_stanza(Client) ->
     escalus_client:wait_for_stanza(Client).
 
+-spec wait_for_stanza(client(), timeout()) -> exml:element().
 wait_for_stanza(Client, Timeout) ->
     escalus_client:wait_for_stanza(Client, Timeout).
 
+-spec wait_for_stanzas(client(), non_neg_integer()) -> [exml:element()].
 wait_for_stanzas(Client, Count) ->
     escalus_client:wait_for_stanzas(Client, Count).
 
+-spec wait_for_stanzas(client(), non_neg_integer(), timeout()) -> [exml:element()].
 wait_for_stanzas(Client, Count, Timeout) ->
     escalus_client:wait_for_stanzas(Client, Count, Timeout).
 
+-spec peek_stanzas(client()) -> [exml:element()].
 peek_stanzas(Client) ->
     escalus_client:peek_stanzas(Client).
 
+-spec send_iq_and_wait_for_result(client(), exml:element()) -> exml:element() | no_return().
 send_iq_and_wait_for_result(Client, Iq) ->
     escalus_client:send_iq_and_wait_for_result(Client, Iq).
 
+-spec send_iq_and_wait_for_result(client(), exml:element(), timeout()) ->
+    exml:element() | no_return().
 send_iq_and_wait_for_result(Client, Iq, Timeout) ->
     escalus_client:send_iq_and_wait_for_result(Client, Iq, Timeout).
 
 %% Other functions
 
+-spec override(config(), atom(), {atom(), atom()}) -> config().
 override(Config, OverrideName, NewValue) ->
     escalus_overridables:override(Config, OverrideName, NewValue).
 
diff --git a/src/escalus_assert.erl b/src/escalus_assert.erl
@@ -15,6 +15,7 @@
 %%==============================================================================
 
 -module(escalus_assert).
+-compile(nowarn_missing_spec).
 
 -export([is_chat_message/2,
          has_no_stanzas/1,

diff --git a/src/escalus_connection.erl b/src/escalus_connection.erl
@@ -430,6 +430,7 @@ upgrade_to_tls(#client{module = Mod, rcv_pid = Pid, props = Props}) ->
     SSLOpts = proplists:get_value(ssl_opts, Props, DefSslOpts),
     Mod:upgrade_to_tls(Pid, SSLOpts).
 
+-spec wait_for_close(client()) -> boolean().
 wait_for_close(Client) ->
     wait_for_close(Client, default_timeout()).
 
@@ -476,6 +477,8 @@ maybe_forward_to_owner(_, State, Stanzas, Fun, Timestamp) ->
 stanza_msg(Stanza, Metadata) ->
     {stanza, self(), Stanza, Metadata}.
 
+-spec separate_ack_requests({boolean(), non_neg_integer(), term()}, [exml_stream:element()]) ->
+    {{boolean(), non_neg_integer(), term()}, [exml_stream:element()], [exml_stream:element()]}.
 separate_ack_requests({false, H0, A}, Stanzas) ->
     %% Don't keep track of H
     {{false, H0, A}, [], Stanzas};

diff --git a/src/escalus_ct.erl b/src/escalus_ct.erl
@@ -163,5 +163,6 @@ ct_log_timestamp({MS, S, US}) ->
                                 "~2.10.0B:~2.10.0B:~2.10.0B.~3.10.0B",
                                 [Year, Month, Day, Hour, Min, Sec, MilliSec])).
 
+-spec log_error(binary(), [any()]) -> ok.
 log_error(Format, Args) ->
     ct:pal(error, Format, Args).
diff --git a/src/escalus_ejabberd.erl b/src/escalus_ejabberd.erl
@@ -53,21 +53,26 @@
 %%% Business API
 %%%
 
+-spec rpc(atom(), atom(), [any()], timeout()) -> any().
 rpc(M, F, A, Timeout) ->
     Node = escalus_ct:get_config(ejabberd_node),
     Cookie = escalus_ct:get_config(ejabberd_cookie),
     escalus_rpc:call(Node, M, F, A, Timeout, Cookie).
 
+-spec rpc(atom(), atom(), [any()]) -> any().
 rpc(M, F, A) ->
     rpc(M, F, A, 3000).
 
+-spec remote_display(string()) -> true.
 remote_display(String) ->
     Line = [$\n, [$- || _ <- String], $\n],
     remote_format("~s~s~s", [Line, String, Line]).
 
+-spec remote_format(string()) -> true.
 remote_format(Format) ->
     remote_format(Format, []).
 
+-spec remote_format(string(), [any()]) -> true.
 remote_format(Format, Args) ->
     group_leader(rpc(erlang, whereis, [user]), self()),
     io:format(Format, Args),
@@ -106,14 +111,17 @@ with_local_option(Option, Value, Fun) ->
         end, lists:zip(Hosts, OldValues))
     end.
 
-get_c2s_status(#client{jid=Jid}) ->
+-spec get_c2s_status(escalus:client()) -> term().
+get_c2s_status(#client{jid = Jid}) ->
     {match, USR} = re:run(Jid, <<"([^@]*)@([^/]*)/(.*)">>, [{capture, all_but_first, list}]),
     Pid = rpc(ejabberd_sm, get_session_pid, USR),
     rpc(sys, get_status, [Pid]).
 
+-spec wait_for_session_count(escalus:config(), non_neg_integer()) -> ok | no_return().
 wait_for_session_count(Config, Count) ->
     wait_for_session_count(Config, Count, 0).
 
+-spec get_remote_sessions(escalus:config()) -> term().
 get_remote_sessions(Config) ->
     escalus_overridables:do(Config, get_remote_sessions, [],
                             {?MODULE, default_get_remote_sessions}).
@@ -203,8 +211,13 @@ reset_option({Option, _, Set, _}, Config) ->
 %% escalus_user_db callbacks
 %%--------------------------------------------------------------------
 
-start(_) -> ok.
-stop(_) -> ok.
+-spec start(_) -> ok.
+start(_) ->
+    ok.
+
+-spec stop(_) -> ok.
+stop(_) ->
+    ok.
 
 -spec create_users(escalus:config(), [escalus_users:named_user()]) -> escalus:config().
 create_users(Config, Users) ->
@@ -220,11 +233,17 @@ delete_users(Config, Users) ->
 %% escalus_server callbacks
 %%--------------------------------------------------------------------
 
-pre_story(Config) -> Config.
+-spec pre_story(escalus:config()) -> escalus:config().
+pre_story(Config) ->
+    Config.
 
-post_story(Config) -> Config.
+-spec post_story(escalus:config()) -> escalus:config().
+post_story(Config) ->
+    Config.
 
-name() -> ?MODULE.
+-spec name() -> atom().
+name() ->
+    ?MODULE.
 
 %%--------------------------------------------------------------------
 %% Helpers
@@ -245,16 +264,20 @@ unregister_user(Config, {_UserName, UserSpec}) ->
     [U, S, _P] = USP,
     rpc(ejabberd_admin, unregister, [U, S], 30000).
 
+-spec default_get_remote_sessions() -> any().
 default_get_remote_sessions() ->
     rpc(ejabberd_sm, get_full_session_list, []).
 
+-spec legacy_get_remote_sessions() -> any().
 legacy_get_remote_sessions() ->
     rpc(ejabberd_sm, dirty_get_sessions_list, []).
 
+-spec unify_str_arg(any()) -> any().
 unify_str_arg(Arg) ->
     StrFormat = escalus_ct:get_config(ejabberd_string_format),
     unify_str_arg(Arg, StrFormat).
 
+-spec unify_str_arg(any(), str | string()) -> any().
 unify_str_arg(Arg, str) when is_binary(Arg) ->
     binary_to_list(Arg);
 unify_str_arg(Arg, _) ->

diff --git a/src/escalus_event.erl b/src/escalus_event.erl
@@ -22,7 +22,6 @@
 
 -include_lib("exml/include/exml.hrl").
 
--type config() :: escalus_config:config().
 -type event_client() :: list({atom(), any()}).
 -type manager() :: pid().
 -type resource() :: binary().
@@ -41,40 +40,47 @@ add_handler(Mgr, Handler, Args) ->
 delete_handler(Mgr, Handler, Args) ->
     gen_event:delete_handler(Mgr, Handler, Args).
 
+-spec incoming_stanza(event_client(), exml_stream:element()) -> ok.
 incoming_stanza(Client, Stanza) ->
     notify_stanza(Client, incoming_stanza, Stanza).
 
+-spec pop_incoming_stanza(event_client(), exml_stream:element()) -> ok.
 pop_incoming_stanza(Client, Stanza) ->
     notify_stanza(Client, pop_incoming_stanza, Stanza).
 
+-spec outgoing_stanza(event_client(), exml_stream:element()) -> ok.
 outgoing_stanza(Client, Stanza) ->
     notify_stanza(Client, outgoing_stanza, Stanza).
 
+-spec story_start(escalus_config:config()) -> ok.
 story_start(Config) ->
     gen_event:notify(manager(Config), story_start).
 
+-spec story_end(escalus_config:config()) -> ok.
 story_end(Config) ->
     gen_event:notify(manager(Config), story_end).
 
 
 %% ====================================================================
 
 %% @doc Start the event manager
-%% @end
+-spec start(escalus_config:config()) -> escalus_config:config().
 start(Config) ->
     {ok, Mgr} = gen_event:start_link(),
     add_handler(Mgr, escalus_history_h, []),
     [{escalus_event_mgr, Mgr} | Config].
 
 %% @doc Stop the event manager
-%% @end
+-spec stop(escalus_config:config()) -> escalus_config:config().
 stop(Config) ->
     gen_event:stop(manager(Config)),
     Config.
 
+-spec get_history(escalus_config:config()) -> [term()].
 get_history(Config) ->
     escalus_history_h:get_history(manager(Config)).
 
+-spec print_history(escalus_config:config()) -> ok.
 print_history(Config) ->
     CaseName = proplists:get_value(tc_name, Config),
     PrivDir  = proplists:get_value(priv_dir, Config),
@@ -179,7 +185,7 @@ manager(Config) ->
 
 %% @doc Create a new event emitter.
 -spec new_client(Config, User, MaybeResource) -> undefined | EventClient when
-      Config :: config(),
+      Config :: escalus_config:config(),
       User :: escalus_users:user_name() | escalus_users:user_spec(),
       MaybeResource :: undefined | resource(),
       EventClient :: event_client().
@@ -206,7 +212,6 @@ new_client_1(Mgr, UserSpec, Resource) ->
 
 %% @doc Notify the event system of an event
 %% <p>The system accepts any term as the event.</p>
-%% @end
 notify_stanza(undefined, _, _) ->
     ok;
 notify_stanza(Client, EventName, Stanza) ->

diff --git a/src/escalus_pred.erl b/src/escalus_pred.erl
@@ -110,8 +110,11 @@
 %% Deprecation support
 %%--------------------------------------------------------------------
 
+-spec is_presence_stanza(any()) -> any().
 ?DEPRECATED1(is_presence_stanza, is_presence).
+-spec is_presence_type(any(), any()) -> any().
 ?DEPRECATED2(is_presence_type, is_presence_with_type).
+-spec is_result(any()) -> any().
 ?DEPRECATED1(is_result, is_iq_result).
 
 %%--------------------------------------------------------------------
@@ -307,6 +310,7 @@ is_iq_set(Stanza) -> is_iq(<<"set">>, Stanza).
 -spec is_iq_get(exml:element()) -> boolean().
 is_iq_get(Stanza) -> is_iq(<<"get">>, Stanza).
 
+-spec is_iq_result_or_error(exml:element(), exml:element()) -> boolean().
 is_iq_result_or_error(QueryStanza, ResultStanza) ->
     (is_iq_error(ResultStanza) orelse is_iq_result(ResultStanza))
         andalso has_same_id(QueryStanza, ResultStanza).
@@ -540,6 +544,7 @@ has_identity(Category, Type, Stanza) ->
               Idents).
 
 %% TODO: Remove as duplicates escalus_assert:has_no_stanzas/1 functionality.
+-spec stanza_timeout(tuple()) -> boolean().
 stanza_timeout(Arg) ->
     case element(1, Arg) of
         'EXIT' ->
@@ -671,8 +676,7 @@ is_bind_result(#xmlel{} = Stanza) ->
 %% Functors
 %%--------------------------------------------------------------------
 
-%% Not supported by erlang 15 :(
-%%-spec 'not'( fun((...) -> boolean()) ) ->  fun((...) -> boolean()).
+-spec 'not'(fun((any()) -> boolean())) -> fun((any()) -> boolean()).
 'not'(Pred) when is_function(Pred, 1) ->
     fun (Arg) -> not Pred(Arg) end;
 'not'(Pred) when is_function(Pred, 2) ->

diff --git a/src/escalus_server.erl b/src/escalus_server.erl
@@ -33,9 +33,11 @@ pre_story(Config) ->
 post_story(Config) ->
     call_server(get_server(Config), post_story, [Config]).
 
+-spec name(escalus:config()) -> any().
 name(Config) ->
     call_server(get_server(Config), name, []).
 
+-spec get_server(escalus:config()) -> any().
 get_server(Config) ->
     escalus_config:get_config(escalus_xmpp_server, Config, undefined).