Merge branch 'hb/stdlib/spec_improvements/OTP-10658'

* hb/stdlib/spec_improvements/OTP-10658:
  [stdlib] Correct and improve specs and types of erl_scan and sys

1 files changed, 49 insertions, 46 deletions

diff --git a/lib/stdlib/src/sys.erl b/lib/stdlib/src/sys.erl
index 4dd70ad425..2d6287814e 100644
--- a/lib/stdlib/src/sys.erl
+++ b/lib/stdlib/src/sys.erl
@@ -39,7 +39,18 @@
                       | {'in', Msg :: _, From :: _}
                       | {'out', Msg :: _, To :: _}
                         | term().
--opaque dbg_opt()    :: list().
+-opaque dbg_opt()    :: {'trace', 'true'}
+                      | {'log',
+                         {N :: non_neg_integer(),
+                          [{Event :: system_event(),
+                            FuncState :: _,
+                            FormFunc :: dbg_fun()}]}}
+                      | {'statistics', {file:date_time(),
+                                        {'reductions', non_neg_integer()},
+                                        MessagesIn :: non_neg_integer(),
+                                        MessagesOut :: non_neg_integer()}}
+                      | {'log_to_file', file:io_device()}
+                      | {Func :: dbg_fun(), FuncState :: term()}.
 -type dbg_fun()      :: fun((FuncState :: _,
                              Event :: system_event(),
                              ProcState :: _) -> 'done' | (NewFuncState :: _)).
@@ -47,24 +58,22 @@
 %%-----------------------------------------------------------------
 %% System messages
 %%-----------------------------------------------------------------
--spec suspend(Name) -> Void when
-      Name :: name(),
-      Void :: term().
+-spec suspend(Name) -> 'ok' when
+      Name :: name().
 suspend(Name) -> send_system_msg(Name, suspend).
--spec suspend(Name, Timeout) -> Void when
+
+-spec suspend(Name, Timeout) -> 'ok' when
       Name :: name(),
-      Timeout :: timeout(),
-      Void :: term().
+      Timeout :: timeout().
 suspend(Name, Timeout) -> send_system_msg(Name, suspend, Timeout).
 
--spec resume(Name) -> Void when
-      Name :: name(),
-      Void :: term().
+-spec resume(Name) -> 'ok' when
+      Name :: name().
 resume(Name) -> send_system_msg(Name, resume).
--spec resume(Name, Timeout) -> Void when
+
+-spec resume(Name, Timeout) -> 'ok' when
       Name :: name(),
-      Timeout :: timeout(),
-      Void :: term().
+      Timeout :: timeout().
 resume(Name, Timeout) -> send_system_msg(Name, resume, Timeout).
 
 -spec get_status(Name) -> Status when
@@ -73,9 +82,10 @@ resume(Name, Timeout) -> send_system_msg(Name, resume, Timeout).
       SItem :: (PDict :: [{Key :: term(), Value :: term()}])
              | (SysState :: 'running' | 'suspended')
              | (Parent :: pid())
-             | (Dbg :: dbg_opt())
+             | (Dbg :: [dbg_opt()])
              | (Misc :: term()).
 get_status(Name) -> send_system_msg(Name, get_status).
+
 -spec get_status(Name, Timeout) -> Status when
       Name :: name(),
       Timeout :: timeout(),
@@ -83,7 +93,7 @@ get_status(Name) -> send_system_msg(Name, get_status).
       SItem :: (PDict :: [{Key :: term(), Value :: term()}])
              | (SysState :: 'running' | 'suspended')
              | (Parent :: pid())
-             | (Dbg :: dbg_opt())
+             | (Dbg :: [dbg_opt()])
              | (Misc :: term()).
 get_status(Name, Timeout) -> send_system_msg(Name, get_status, Timeout).
 
@@ -95,6 +105,7 @@ get_status(Name, Timeout) -> send_system_msg(Name, get_status, Timeout).
       Reason :: term().
 change_code(Name, Mod, Vsn, Extra) ->
     send_system_msg(Name, {change_code, Mod, Vsn, Extra}).
+
 -spec change_code(Name, Module, OldVsn, Extra, Timeout) ->
                          'ok' | {error, Reason} when
       Name :: name(),
@@ -191,35 +202,33 @@ no_debug(Name) -> send_system_msg(Name, {debug, no_debug}).
       Timeout :: timeout().
 no_debug(Name, Timeout) -> send_system_msg(Name, {debug, no_debug}, Timeout).
 
--spec install(Name, FuncSpec) -> Void when
+-spec install(Name, FuncSpec) -> 'ok' when
       Name :: name(),
       FuncSpec :: {Func, FuncState},
       Func :: dbg_fun(),
-      FuncState :: term(),
-      Void :: term().
+      FuncState :: term().
 install(Name, {Func, FuncState}) ->
     send_system_msg(Name, {debug, {install, {Func, FuncState}}}).
--spec install(Name, FuncSpec, Timeout) -> Void when
+
+-spec install(Name, FuncSpec, Timeout) -> 'ok' when
       Name :: name(),
       FuncSpec :: {Func, FuncState},
       Func :: dbg_fun(),
       FuncState :: term(),
-      Timeout :: timeout(),
-      Void :: term().
+      Timeout :: timeout().
 install(Name, {Func, FuncState}, Timeout) ->
     send_system_msg(Name, {debug, {install, {Func, FuncState}}}, Timeout).
 
--spec remove(Name, Func) -> Void when
+-spec remove(Name, Func) -> 'ok' when
       Name :: name(),
-      Func :: dbg_fun(),
-      Void :: term().
+      Func :: dbg_fun().
 remove(Name, Func) ->
     send_system_msg(Name, {debug, {remove, Func}}).
--spec remove(Name, Func, Timeout) -> Void when
+
+-spec remove(Name, Func, Timeout) -> 'ok' when
       Name :: name(),
       Func :: dbg_fun(),
-      Timeout :: timeout(),
-      Void :: term().
+      Timeout :: timeout().
 remove(Name, Func, Timeout) ->
     send_system_msg(Name, {debug, {remove, Func}}, Timeout).
 
@@ -245,18 +254,13 @@ mfa(Name, {change_code, Mod, Vsn, Extra}) ->
     {sys, change_code, [Name, Mod, Vsn, Extra]};
 mfa(Name, Atom) ->
     {sys, Atom, [Name]}.
+
 mfa(Name, Req, Timeout) ->
     {M, F, A} = mfa(Name, Req),
     {M, F, A ++ [Timeout]}.
 
 %%-----------------------------------------------------------------
 %% Func: handle_system_msg/6
-%% Args: Msg    ::= term()
-%%       From   ::= {pid(),Ref} but don't count on that
-%%       Parent ::= pid()
-%%       Module ::= atom()
-%%       Debug  ::= [debug_opts()]
-%%       Misc   ::= term()
 %% Purpose: Used by a process module that wishes to take care of
 %%          system messages.  The process receives a {system, From,
 %%          Msg} message, and passes the Msg to this function.
@@ -268,14 +272,14 @@ mfa(Name, Req, Timeout) ->
 %%          The Module must export system_continue/3, system_terminate/4
 %%          and format_status/2 for status information.
 %%-----------------------------------------------------------------
--spec handle_system_msg(Msg, From, Parent, Module, Debug, Misc) -> Void when
+-spec handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
+                               no_return() when
       Msg :: term(),
       From :: {pid(), Tag :: _},
       Parent :: pid(),
       Module :: module(),
       Debug :: [dbg_opt()],
-      Misc :: term(),
-      Void :: term().
+      Misc :: term().
 handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
     handle_system_msg(running, Msg, From, Parent, Module, Debug, Misc, false).
 
@@ -294,10 +298,6 @@ handle_system_msg(SysState, Msg, From, Parent, Mod, Debug, Misc, Hib) ->
 
 %%-----------------------------------------------------------------
 %% Func: handle_debug/4
-%% Args: Debug ::= [debug_opts()]
-%%       Func  ::= {M,F} | fun()  arity 3
-%%       State ::= term()
-%%       Event ::= {in, Msg} | {in, Msg, From} | {out, Msg, To} | term()
 %% Purpose: Called by a process that wishes to debug an event.
 %%          Func is a formatting function, called as Func(Device, Event).
 %% Returns: [debug_opts()]
@@ -453,6 +453,7 @@ print_event(Dev, {Event, State, FormFunc}) ->
     FormFunc(Dev, Event, State).
 
 init_stat() -> {erlang:localtime(), process_info(self(), reductions), 0, 0}.
+
 get_stat({Time, {reductions, Reds}, In, Out}) ->
     {reductions, Reds2} = process_info(self(), reductions),
     [{start_time, Time}, {current_time, erlang:localtime()},
@@ -492,9 +493,8 @@ get_debug2(Item, Debug, Default) ->
 	_ -> Default
     end.
 
--spec print_log(Debug) -> Void when
-      Debug :: [dbg_opt()],
-      Void :: term().
+-spec print_log(Debug) -> 'ok' when
+      Debug :: [dbg_opt()].
 print_log(Debug) ->
     {_N, Logs} = get_debug(log, Debug, {0, []}),
     lists:foreach(fun print_event/1,
@@ -511,8 +511,6 @@ close_log_file(Debug) ->
 
 %%-----------------------------------------------------------------
 %% Func: debug_options/1
-%% Args: [trace|log|{log,N}|statistics|{log_to_file, FileName}|
-%%        {install, {Func, FuncState}}]
 %% Purpose: Initiate a debug structure.  Called by a process that
 %%          wishes to initiate the debug structure without the
 %%          system messages.
@@ -521,7 +519,11 @@ close_log_file(Debug) ->
 
 -spec debug_options(Options) -> [dbg_opt()] when
       Options :: [Opt],
-      Opt :: 'trace' | 'log' | 'statistics' | {'log_to_file', FileName}
+      Opt :: 'trace'
+           | 'log'
+           | {'log', pos_integer()}
+           | 'statistics'
+           | {'log_to_file', FileName}
            | {'install', FuncSpec},
       FileName :: file:name(),
       FuncSpec :: {Func, FuncState},
@@ -529,6 +531,7 @@ close_log_file(Debug) ->
       FuncState :: term().
 debug_options(Options) ->
     debug_options(Options, []).
+
 debug_options([trace | T], Debug) ->
     debug_options(T, install_debug(trace, true, Debug));
 debug_options([log | T], Debug) ->