Update and add missing supervisor types and specs

Updates some types to match OTP, and adds some others, including exports types for
`startchild_ret/0` and `startlink_ret/0`.

Adds specs to all public functions, and marks callbacks as hidden functions so they are not
included in published user API docs.

Signed-off-by: Winford <[email protected]>

Author: UncleGrumpy

libs/estdlib/src/supervisor.erl

@@ -43,6 +43,8 @@
 
 -export_type([
     child_spec/0,
+    startchild_ret/0,
+    startlink_ret/0,
     strategy/0,
     sup_flags/0
 ]).
@@ -53,7 +55,9 @@
     | temporary
     | {terminating, permanent | transient | temporary, gen_server:from()}.
 -type shutdown() :: brutal_kill | timeout().
--type child_type() :: worker | supervisor.
+-type worker() :: worker | supervisor.
+-type child_id() :: term().
+-type child() :: undefined | pid().
 
 -type strategy() :: one_for_all | one_for_one.
 -type sup_flags() ::
@@ -70,25 +74,38 @@
         start := {module(), atom(), [any()]},
         restart => restart(),
         shutdown => shutdown(),
-        type => child_type(),
+        type => worker(),
         modules => [module()] | dynamic
     }
     | {
         Id :: any(),
         StartFunc :: {module(), atom(), [any()]},
         Restart :: restart(),
         Shutdown :: shutdown(),
-        Type :: child_type(),
+        Type :: worker(),
         Modules :: [module()] | dynamic
     }.
 
+-type startlink_ret() :: {ok, pid()} | ignore | {error, startlink_err()}.
+-type startlink_err() :: {already_started, pid()} | {shutdown, term()} | term().
+-type startchild_ret() ::
+    {ok, Child :: child()} | {ok, Child :: child(), Info :: term()} | {error, startchild_err()}.
+-type startchild_err() :: already_present | {already_started, Child :: child()} | term().
+-type sup_name() :: {local, Name :: atom()}.
+-type sup_ref() ::
+    (Name :: atom())
+    | {Name :: atom(), Node :: node()}
+    | {global, Name :: term()}
+    | {via, Module :: module(), Name :: any()}
+    | pid().
+
 -record(child, {
     pid = undefined :: pid() | undefined | {restarting, pid()} | {restarting, undefined},
     id :: any(),
     start :: {module(), atom(), [any()] | undefined},
     restart :: restart(),
     shutdown :: shutdown(),
-    type :: child_type(),
+    type :: worker(),
     modules = [] :: [module()] | dynamic
 }).
 %% note: the list of children should always be kept in order, with first to start at the head.
@@ -108,30 +125,59 @@
 %% could be used to set a sane default for the platform (OTP uses 1000).
 -define(STALE_RESTART_LIMIT, 100).
 
+-spec start_link(Module :: module(), Args :: [any()]) -> startlink_ret().
 start_link(Module, Args) ->
     gen_server:start_link(?MODULE, {Module, Args}, []).
 
+-spec start_link(SupName :: sup_name(), Module :: module(), Args :: [any()]) -> startlink_ret().
 start_link(SupName, Module, Args) ->
     gen_server:start_link(SupName, ?MODULE, {Module, Args}, []).
 
+-spec start_child(Supervisor :: sup_ref(), ChildSpec :: child_spec()) -> startchild_ret().
 start_child(Supervisor, ChildSpec) ->
     gen_server:call(Supervisor, {start_child, ChildSpec}).
 
+-spec terminate_child(Supervisor :: sup_ref(), ChildId :: any()) -> ok | {error, not_found}.
 terminate_child(Supervisor, ChildId) ->
     gen_server:call(Supervisor, {terminate_child, ChildId}).
 
+-spec restart_child(Supervisor :: sup_ref(), ChildId :: any()) ->
+    {ok, Child :: child()}
+    | {ok, Child :: child(), Info :: term()}
+    | {error, Reason :: running | restarting | not_found | term()}.
 restart_child(Supervisor, ChildId) ->
     gen_server:call(Supervisor, {restart_child, ChildId}).
 
+-spec delete_child(Supervisor :: sup_ref(), ChildId :: any()) ->
+    ok | {error, Reason :: running | restarting | not_found}.
 delete_child(Supervisor, ChildId) ->
     gen_server:call(Supervisor, {delete_child, ChildId}).
 
+-spec which_children(Supervisor :: sup_ref()) ->
+    [
+        {
+            Id :: child_id() | undefined,
+            Child :: child() | restarting,
+            Type :: worker(),
+            Modules :: [module()]
+        }
+    ].
 which_children(Supervisor) ->
     gen_server:call(Supervisor, which_children).
 
+-spec count_children(Supervisor :: sup_ref()) ->
+    [
+        {specs, ChildSpecCount :: non_neg_integer()}
+        | {active, ActiveProcessCount :: non_neg_integer()}
+        | {supervisors, ChildSupervisorCount :: non_neg_integer()}
+        | {workers, ChildWorkerCount :: non_neg_integer()}
+    ].
 count_children(Supervisor) ->
     gen_server:call(Supervisor, count_children).
 
+% @hidden
+-spec init({Mod :: module(), Args :: [any()]}) ->
+    {ok, State :: #state{}} | {stop, {bad_return, {Mod :: module(), init, Reason :: term()}}}.
 init({Mod, Args}) ->
     erlang:process_flag(trap_exit, true),
     case Mod:init(Args) of
@@ -196,13 +242,17 @@ child_spec_to_record(#{id := ChildId, start := MFA} = ChildMap) ->
         modules = Modules
     }.
 
+% @hidden
+-spec init_state(ChildSpecs :: [child_spec()], State :: #state{}) -> State :: #state{}.
 init_state([ChildSpec | T], State) ->
     Child = child_spec_to_record(ChildSpec),
     NewChildren = [Child | State#state.children],
     init_state(T, State#state{children = NewChildren});
 init_state([], State) ->
     State#state{children = lists:reverse(State#state.children)}.
 
+-spec start_children(ChildSpecs :: [child_spec()], State :: #state{}) ->
+    ChildSpecs :: [child_spec()].
 start_children([Child | T], StartedC) ->
     case try_start(Child) of
         {ok, Pid, _Result} ->
@@ -212,6 +262,7 @@ start_children([], StartedC) ->
     %% We should always keep the start list in order for later one_for_all restarts.
     lists:reverse(StartedC).
 
+% @hidden
 handle_call({start_child, ChildSpec}, _From, #state{children = Children} = State) ->
     Child = child_spec_to_record(ChildSpec),
     #child{id = ID} = Child,
@@ -280,9 +331,11 @@ handle_call(count_children, _From, #state{children = Children} = State) ->
     Reply = [{specs, Specs}, {active, Active}, {supervisors, Supers}, {workers, Workers}],
     {reply, Reply, State}.
 
+% @hidden
 handle_cast(_Msg, State) ->
     {noreply, State}.
 
+% @hidden
 handle_info({'EXIT', Pid, Reason}, State) ->
     case handle_child_exit(Pid, Reason, State) of
         {ok, State1} ->