sasl: Add specs to all public functions

nyczol · Jan 23, 2024 · 196e7cd · 196e7cd
1 parent b4ca300
commit 196e7cd
Show file tree

Hide file tree

Showing 4 changed files with 224 additions and 3 deletions.
diff --git a/lib/sasl/src/alarm_handler.erl b/lib/sasl/src/alarm_handler.erl
@@ -32,6 +32,9 @@
 	 handle_event/2, handle_call/2, handle_info/2,
 	 terminate/2]).
 
+-type alarm_id() :: term().
+-type alarm() :: {alarm_id(), AlarmDescription :: term()}.
+
 start_link() ->
     case gen_event:start_link({local, alarm_handler}) of
 	{ok, Pid} ->
@@ -45,20 +48,24 @@ start_link() ->
 %% Args: Alarm ::= {AlarmId, term()}
 %%       where AlarmId ::= term()
 %%-----------------------------------------------------------------
+-spec set_alarm(alarm()) -> term().
+
 set_alarm(Alarm) ->
     gen_event:notify(alarm_handler, {set_alarm, Alarm}).
 
 %%-----------------------------------------------------------------
 %% Func: clear_alarm/1
 %% Args: AlarmId ::= term()
 %%-----------------------------------------------------------------
+-spec clear_alarm(alarm_id()) -> term().
 clear_alarm(AlarmId) ->
     gen_event:notify(alarm_handler, {clear_alarm, AlarmId}).
 
 %%-----------------------------------------------------------------
 %% Func: get_alarms/0
 %% Returns: [{AlarmId, AlarmDesc}]
 %%-----------------------------------------------------------------
+-spec get_alarms() -> [alarm()].
 get_alarms() ->
     gen_event:call(alarm_handler, alarm_handler, get_alarms).
 

diff --git a/lib/sasl/src/rb.erl b/lib/sasl/src/rb.erl
@@ -33,6 +33,15 @@
 -export([init/1, terminate/2, handle_call/3,
 	 handle_cast/2, handle_info/2, code_change/3]).
 
+-type type() :: error | error_report | info_msg | info_report |
+                warning_msg | warning_report | crash_report |
+                supervisor_report | progress | all.
+-type option() :: {start_log, FileName :: string() | atom() | pid()} |
+                  {max, MaxNoOfReports :: integer() | all} |
+                  {report_dir, DirString :: string()} |
+                  {type, ReportType :: type() | [type()] | all } |
+                  {abort_on_error, boolean()}.
+
 %%%-----------------------------------------------------------------
 %%% Report Browser Tool.
 %%% Formats Error reports written by log_mf_h
@@ -44,7 +53,10 @@
 %% Interface functions.
 %% For available options; see print_options().
 %%-----------------------------------------------------------------
+-spec start() -> term().
 start() -> start([]).
+-spec start(Options) -> term() when
+      Options :: [option()].
 start(Options) ->
     supervisor:start_child(sasl_sup, 
 			   {rb_server, {rb, start_link, [Options]},
@@ -53,40 +65,69 @@ start(Options) ->
 start_link(Options) ->
     gen_server:start_link({local, rb_server}, rb, Options, []).
 
+-spec stop() -> term().
 stop() -> 
     supervisor:terminate_child(sasl_sup, rb_server).
 
+-spec rescan() -> term().
 rescan() -> rescan([]).
+-spec rescan(Options) -> term() when Options :: [option()].
 rescan(Options) ->
     call({rescan, Options}).
 
+-spec list() -> term().
 list() -> list(all).
+-spec list(Type :: type()) -> term().
 list(Type) -> call({list, Type}).
 
+-spec log_list() -> term().
 log_list() -> log_list(all).
+-spec log_list(Type :: type()) -> term().
 log_list(Type) -> call({log_list, Type}).
 
-show() -> 
+-spec show() -> term().
+show() ->
     call(show).
 
-show(Number) when is_integer(Number) -> 
+-spec show(Report) -> term() when Report :: integer() | type().
+show(Number) when is_integer(Number) ->
     call({show_number, Number});
 show(Type) when is_atom(Type) ->
     call({show_type, Type}).
 
+-type regexp() :: string() | {string(), Options :: [re:options()]} |
+                  re:mp() | {re:mp(), Options :: [re:compile_options()]}.
+
+-spec grep(RegExp :: regexp()) -> term().
 grep(RegExp) -> call({grep, RegExp}).
 
+-type filter() :: {Key :: term(), Value :: term()} |
+                  {Key :: term(), Value :: term(), no} |
+                  {Key :: term(), RegExp :: regexp(), re} |
+                  {Key :: term(), RegExp :: regexp(), re, no}.
+
+-spec filter(Filters) -> term() when
+      Filters :: [filter()].
 filter(Filters) when is_list(Filters) ->
     call({filter, Filters}).
 
+-spec filter(Filters, Dates) -> term() when
+      Filters :: [filter()],
+      Dates :: {DateFrom, DateTo} | {DateFrom, from} | {DateTo, to},
+      DateFrom :: calendar:datetime(),
+      DateTo :: calendar:datetime().
 filter(Filters, FDates) when is_list(Filters) andalso is_tuple(FDates) ->
     call({filter, {Filters, FDates}}).
 
+-spec start_log(FileName) -> term() when FileName :: string() | atom() | pid().
 start_log(FileName) -> call({start_log, FileName}).
 
+-spec stop_log() -> term().
 stop_log() -> call(stop_log).
 
+-spec h() -> term().
 h() -> help().
+-spec help() -> term().
 help() ->
     io:format("~nReport Browser Tool - usage~n"),
     io:format("===========================~n"),

diff --git a/lib/sasl/src/release_handler.erl b/lib/sasl/src/release_handler.erl
@@ -161,6 +161,9 @@ start_link() ->
 %%                   {file_missing, FileName} |  (in the tar package)
 %%                   exit_reason()
 %%-----------------------------------------------------------------
+-spec unpack_release(Name) -> {ok, Vsn} | {error, Reason} when Name :: string(),
+   Vsn :: string(),
+   Reason :: client_node | term().
 unpack_release(ReleaseName) ->
     call({unpack_release, ReleaseName}).
 
@@ -179,9 +182,19 @@ unpack_release(ReleaseName) ->
 %%                   {no_such_from_vsn, Vsn} |
 %%                   exit_reason()
 %%-----------------------------------------------------------------
+-spec check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason} when Vsn :: string(),
+   OtherVsn :: string(),
+   Descr :: term(),
+   Reason :: term().
 check_install_release(Vsn) ->
     check_install_release(Vsn, []).
 
+-spec check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason} when Vsn :: string(),
+   OtherVsn :: string(),
+   Opts :: [Opt],
+   Opt :: purge,
+   Descr :: term(),
+   Reason :: term().
 check_install_release(Vsn, Opts) ->
     case check_check_install_options(Opts, false) of
 	{ok,Purge} ->
@@ -213,10 +226,35 @@ check_check_install_options([],Purge) ->
 %%                   {illegal_option, Opt}} |
 %%                   exit_reason()
 %%-----------------------------------------------------------------
+-spec install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason} when
+      Vsn :: string(),
+      OtherVsn :: string(),
+      Descr :: term(),
+      Reason :: {already_installed, Vsn} |
+                {change_appl_data, term()} |
+                {missing_base_app, OtherVsn, App} |
+                {could_not_create_hybrid_boot, term()} |
+                term(),
+      App :: atom().
 install_release(Vsn) ->
     call({install_release, Vsn, restart, []}).
 
 
+-spec install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason} when
+      Vsn :: string(),
+      OtherVsn :: string(),
+      Opt :: {error_action, Action} | {code_change_timeout, Timeout} | {suspend_timeout, Timeout} | {update_paths, Bool},
+      Action :: restart | reboot,
+      Timeout :: default | infinity | pos_integer(),
+      Bool :: boolean(),
+      Descr :: term(),
+      Reason :: {illegal_option, Opt} |
+                {already_installed, Vsn} |
+                {change_appl_data, term()} |
+                {missing_base_app, OtherVsn, App} |
+                {could_not_create_hybrid_boot, term()} |
+                term(),
+      App :: atom().
 install_release(Vsn, Opt) ->
     case check_install_options(Opt, restart, []) of
 	{ok, ErrorAction, InstallOpt} ->
@@ -275,12 +313,23 @@ new_emulator_upgrade(Vsn, Opts) ->
 %%                   {no_such_release, Vsn} |
 %%                   exit_reason()
 %%-----------------------------------------------------------------
+-spec make_permanent(Vsn) -> ok | {error, Reason}
+                        when
+                            Vsn :: string(),
+                            Reason ::
+                                {bad_status, Status :: term()} | term().
 make_permanent(Vsn) ->
     call({make_permanent, Vsn}).
 
 %%-----------------------------------------------------------------
 %% Purpose: Reboots the system from an old release.
 %%-----------------------------------------------------------------
+-spec reboot_old_release(Vsn) -> ok | {error, Reason}
+                            when
+                                Vsn :: string(),
+                                Reason ::
+                                    {bad_status, Status :: term()} |
+                                    term().
 reboot_old_release(Vsn) ->
     call({reboot_old_release, Vsn}).
 
@@ -291,6 +340,8 @@ reboot_old_release(Vsn) ->
 %% Returns: ok | {error, Reason}
 %%          Reason = {permanent, Vsn} |
 %%-----------------------------------------------------------------
+-spec remove_release(Vsn) -> ok | {error, Reason} when Vsn :: string(),
+   Reason :: {permanent, Vsn} | client_node | term().
 remove_release(Vsn) ->
     call({remove_release, Vsn}).
 
@@ -310,6 +361,12 @@ remove_release(Vsn) ->
 %%          them).
 %% Returns: ok | {error, Reason}
 %%-----------------------------------------------------------------
+-spec set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason} when RelFile :: string(),
+   AppDirs :: [{App, Vsn, Dir}],
+    App :: atom(),
+    Vsn :: string(),
+   Dir :: string(),
+   Reason :: term().
 set_unpacked(RelFile, LibDirs) ->
     call({set_unpacked, RelFile, LibDirs}).
 
@@ -320,6 +377,8 @@ set_unpacked(RelFile, LibDirs) ->
 %%          This function won't delete any files at all.
 %% Returns: ok | {error, Reason}
 %%-----------------------------------------------------------------
+-spec set_removed(Vsn) -> ok | {error, Reason} when Vsn :: string(),
+   Reason :: {permanent, Vsn} | term().
 set_removed(Vsn) ->
     call({set_removed, Vsn}).
 
@@ -331,20 +390,31 @@ set_removed(Vsn) ->
 %%          is called.
 %% Returns: ok | {error, {no_such_release, Vsn}}
 %%-----------------------------------------------------------------
+-spec install_file(Vsn, File) -> ok | {error, Reason} when Vsn :: string(),
+   File :: string(),
+   Reason :: term().
 install_file(Vsn, File) when is_list(File) ->
     call({install_file, File, Vsn}).
 
 %%-----------------------------------------------------------------
 %% Returns: [{Name, Vsn, [LibName], Status}]
 %%          Status = unpacked | current | permanent | old
 %%-----------------------------------------------------------------
+-spec which_releases() -> [{Name, Vsn, Apps, Status}] when Name :: string(),
+   Vsn :: string(),
+   Apps :: [AppVsn :: string()],
+   Status :: unpacked | current | permanent | old.
 which_releases() ->
     call(which_releases).
 
 %%-----------------------------------------------------------------
 %% Returns: [{Name, Vsn, [LibName], Status}]
 %%          Status = unpacked | current | permanent | old
 %%-----------------------------------------------------------------
+-spec which_releases(Status) -> [{Name, Vsn, Apps, Status}] when Name :: string(),
+   Vsn :: string(),
+   Apps :: [AppVsn :: string()],
+   Status :: unpacked | current | permanent | old.
 which_releases(Status) ->
     Releases = which_releases(),
     get_releases_with_status(Releases, Status, []).
@@ -384,8 +454,24 @@ create_RELEASES([Root, RelFile | LibDirs]) ->
 create_RELEASES(Root, RelFile) ->
     create_RELEASES(Root, filename:join(Root, "releases"), RelFile, []).
 
+-spec create_RELEASES(RelDir, RelFile, AppDirs) -> ok | {error, Reason} when
+      RelDir :: string(),
+      RelFile :: string(),
+      AppDirs :: [{App, Vsn, Dir}],
+      App :: atom(),
+      Vsn :: string(),
+      Dir :: string(),
+      Reason :: term().
 create_RELEASES(RelDir, RelFile, LibDirs) ->
     create_RELEASES("", RelDir, RelFile, LibDirs).
+-spec create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason} when Root :: string(),
+   RelDir :: string(),
+   RelFile :: string(),
+   AppDirs :: [{App, Vsn, Dir}],
+    App :: atom(),
+    Vsn :: string(),
+   Dir :: string(),
+   Reason :: term().
 create_RELEASES(Root, RelDir, RelFile, LibDirs) ->
     case catch check_rel(Root, RelFile, LibDirs, false) of
 	{error, Reason } ->
@@ -405,6 +491,11 @@ create_RELEASES(Root, RelDir, RelFile, LibDirs) ->
 %%         located under Dir/ebin
 %% Purpose: Upgrade to the version in Dir according to an appup file
 %%-----------------------------------------------------------------
+-spec upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason} when App :: atom(),
+   Dir :: string(),
+   Unpurged :: [Module],
+    Module :: atom(),
+   Reason :: term().
 upgrade_app(App, NewDir1) ->
     NewDir = root_dir_relative_path(NewDir1),
     try upgrade_script(App, NewDir) of
@@ -428,13 +519,25 @@ upgrade_app(App, NewDir1) ->
 %% Purpose: Downgrade from the version in Dir according to an appup file
 %%          located in the ebin dir of the _current_ version
 %%-----------------------------------------------------------------
+-spec downgrade_app(App, Dir) ->  {ok, Unpurged} | restart_emulator | {error, Reason} when
+      App :: atom(),
+      Dir :: string(),
+      Unpurged :: [Module],
+      Module :: atom(),
+      Reason :: term().
 downgrade_app(App, OldDir) ->
     case string:lexemes(filename:basename(OldDir), "-") of
 	[_AppS, OldVsn] ->
 	    downgrade_app(App, OldVsn, OldDir);
 	_ ->
 	    {error, {unknown_version, App}}
     end.
+-spec downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason} when App :: atom(),
+   Dir :: string(),
+   OldVsn :: string(),
+   Unpurged :: [Module],
+    Module :: atom(),
+   Reason :: term().
 downgrade_app(App, OldVsn, OldDir) ->
     try downgrade_script(App, OldVsn, OldDir) of
 	{ok, Script} ->
@@ -444,6 +547,12 @@ downgrade_app(App, OldVsn, OldDir) ->
 	    {error, Reason}
     end.
 
+-spec upgrade_script(App, Dir) -> {ok, NewVsn, Script}
+                        when
+                            App :: atom(),
+                            Dir :: string(),
+                            NewVsn :: string(),
+                            Script :: Instructions :: term().
 upgrade_script(App, NewDir1) ->
     NewDir = root_dir_relative_path(NewDir1),
     OldVsn = ensure_running(App),
@@ -459,6 +568,12 @@ upgrade_script(App, NewDir1) ->
 	    throw(Reason)
     end.
 
+-spec downgrade_script(App, OldVsn, Dir) -> {ok, Script}
+                          when
+                              App :: atom(),
+                              OldVsn :: string(),
+                              Dir :: string(),
+                              Script :: Instructions :: term().
 downgrade_script(App, OldVsn, OldDir) ->
     NewVsn = ensure_running(App),
     NewDir = code:lib_dir(App),
@@ -473,6 +588,17 @@ downgrade_script(App, OldVsn, OldDir) ->
 	    throw(Reason)
     end.
 
+-spec eval_appup_script(App, ToVsn, ToDir, Script :: term()) ->
+                           {ok, Unpurged} |
+                           restart_emulator |
+                           {error, Reason}
+                           when
+                               App :: atom(),
+                               ToVsn :: string(),
+                               ToDir :: string(),
+                               Unpurged :: [Module],
+                               Module :: atom(),
+                               Reason :: term().
 eval_appup_script(App, ToVsn, ToDir, Script) ->
     EnvBefore = application_controller:prep_config_change(),
     AppSpecL = read_appspec(App, ToDir),