Merge pull request #2961 from rabbitmq/fix-edoc-errors

Doc: Fix all errors reported by edoc

13 files changed, 97 insertions, 59 deletions

diff --git a/deps/rabbit/Makefile b/deps/rabbit/Makefile
index 39d21ec1eb..bea8ecb5c3 100644
--- a/deps/rabbit/Makefile
+++ b/deps/rabbit/Makefile
@@ -243,11 +243,14 @@ ct-slow: CT_SUITES = $(SLOW_CT_SUITES)
 # --------------------------------------------------------------------
 
 RMQ_ERLC_OPTS += -I $(DEPS_DIR)/rabbit_common/include
+EDOC_OPTS += {preprocess,true}
 
 ifdef INSTRUMENT_FOR_QC
 RMQ_ERLC_OPTS += -DINSTR_MOD=gm_qc
+EDOC_OPTS += ,{macros,[{'INSTR_MOD',gm_qc}]}
 else
 RMQ_ERLC_OPTS += -DINSTR_MOD=gm
+EDOC_OPTS += ,{macros,[{'INSTR_MOD',gm}]}
 endif
 
 ifdef CREDIT_FLOW_TRACING
diff --git a/deps/rabbit/include/gm_specs.hrl b/deps/rabbit/include/gm_specs.hrl
index 01ecdb21c0..1e7282988a 100644
--- a/deps/rabbit/include/gm_specs.hrl
+++ b/deps/rabbit/include/gm_specs.hrl
@@ -8,8 +8,3 @@
 -type callback_result() :: 'ok' | {'stop', any()} | {'become', atom(), args()}.
 -type args() :: any().
 -type members() :: [pid()].
-
--spec joined(args(), members())                    -> callback_result().
--spec members_changed(args(), members(),members()) -> callback_result().
--spec handle_msg(args(), pid(), any())             -> callback_result().
--spec handle_terminate(args(), term())             -> any().
diff --git a/deps/rabbit/src/rabbit.erl b/deps/rabbit/src/rabbit.erl
index 4329cebe40..e4b2612869 100644
--- a/deps/rabbit/src/rabbit.erl
+++ b/deps/rabbit/src/rabbit.erl
@@ -522,7 +522,7 @@ start_apps(Apps) ->
                  #{app_name() => restart_type()}) -> 'ok'.
 
 %% TODO: start_apps/2 and is now specific to plugins. This function
-%% should be moved over `rabbit_plugins`, along with stop_apps/1, once
+%% should be moved over `rabbit_plugins', along with stop_apps/1, once
 %% the latter stops using app_utils as well.
 
 start_apps(Apps, RestartTypes) ->
diff --git a/deps/rabbit/src/rabbit_binding.erl b/deps/rabbit/src/rabbit_binding.erl
index 8b313e1f37..e68d185613 100644
--- a/deps/rabbit/src/rabbit_binding.erl
+++ b/deps/rabbit/src/rabbit_binding.erl
@@ -76,9 +76,6 @@ new(Src, RoutingKey, Dst, Arguments) ->
 
 %% Global table recovery
 
--spec recover([rabbit_exchange:name()], [rabbit_amqqueue:name()]) ->
-                        'ok'.
-
 recover() ->
     rabbit_misc:table_filter(
         fun (Route) ->
@@ -91,6 +88,9 @@ recover() ->
         end, rabbit_durable_route).
 
 %% Virtual host-specific recovery
+
+-spec recover([rabbit_exchange:name()], [rabbit_amqqueue:name()]) ->
+                        'ok'.
 recover(XNames, QNames) ->
     XNameSet = sets:from_list(XNames),
     QNameSet = sets:from_list(QNames),
diff --git a/deps/rabbit/src/rabbit_disk_monitor.erl b/deps/rabbit/src/rabbit_disk_monitor.erl
index 7da548e351..bb2962fae2 100644
--- a/deps/rabbit/src/rabbit_disk_monitor.erl
+++ b/deps/rabbit/src/rabbit_disk_monitor.erl
@@ -103,11 +103,12 @@ set_max_check_interval(Interval) ->
     gen_server:call(?MODULE, {set_max_check_interval, Interval}, infinity).
 
 -spec get_disk_free() -> (integer() | 'unknown').
--spec set_enabled(string()) -> 'ok'.
 
 get_disk_free() ->
     gen_server:call(?MODULE, get_disk_free, infinity).
 
+-spec set_enabled(string()) -> 'ok'.
+
 set_enabled(Enabled) ->
     gen_server:call(?MODULE, {set_enabled, Enabled}, infinity).
 
diff --git a/deps/rabbit/src/rabbit_health_check.erl b/deps/rabbit/src/rabbit_health_check.erl
index bfa8eea243..a454c252fd 100644
--- a/deps/rabbit/src/rabbit_health_check.erl
+++ b/deps/rabbit/src/rabbit_health_check.erl
@@ -16,11 +16,12 @@
 %% External functions
 %%----------------------------------------------------------------------------
 
--spec node(node(), timeout()) -> ok | {badrpc, term()} | {error_string, string()}.
-
 node(Node) ->
     %% same default as in CLI
     node(Node, 70000).
+
+-spec node(node(), timeout()) -> ok | {badrpc, term()} | {error_string, string()}.
+
 node(Node, Timeout) ->
     rabbit_misc:rpc_call(Node, rabbit_health_check, local, [], Timeout).
 
diff --git a/deps/rabbit/src/rabbit_mirror_queue_coordinator.erl b/deps/rabbit/src/rabbit_mirror_queue_coordinator.erl
index 99659f126f..00c1b62e93 100644
--- a/deps/rabbit/src/rabbit_mirror_queue_coordinator.erl
+++ b/deps/rabbit/src/rabbit_mirror_queue_coordinator.erl
@@ -418,15 +418,21 @@ handle_pre_hibernate(State = #state { gm = GM }) ->
 %% GM
 %% ---------------------------------------------------------------------------
 
+-spec joined(args(), members()) -> callback_result().
+
 joined([CPid], Members) ->
     CPid ! {joined, self(), Members},
     ok.
 
+-spec members_changed(args(), members(),members()) -> callback_result().
+
 members_changed([_CPid], _Births, []) ->
     ok;
 members_changed([CPid],  _Births, Deaths) ->
     ok = gen_server2:cast(CPid, {gm_deaths, Deaths}).
 
+-spec handle_msg(args(), pid(), any()) -> callback_result().
+
 handle_msg([CPid], _From, request_depth = Msg) ->
     ok = gen_server2:cast(CPid, Msg);
 handle_msg([CPid], _From, {ensure_monitoring, _Pids} = Msg) ->
@@ -445,6 +451,8 @@ handle_msg([_CPid], _From, {delete_and_terminate, _Reason}) ->
 handle_msg([_CPid], _From, _Msg) ->
     ok.
 
+-spec handle_terminate(args(), term()) -> any().
+
 handle_terminate([CPid], Reason) ->
     ok = gen_server2:cast(CPid, {delete_and_terminate, Reason}),
     ok.
diff --git a/deps/rabbit/src/rabbit_mirror_queue_slave.erl b/deps/rabbit/src/rabbit_mirror_queue_slave.erl
index 27f610d0b9..d0e2ceb9db 100644
--- a/deps/rabbit/src/rabbit_mirror_queue_slave.erl
+++ b/deps/rabbit/src/rabbit_mirror_queue_slave.erl
@@ -478,8 +478,12 @@ format_message_queue(Opt, MQ) -> rabbit_misc:format_message_queue(Opt, MQ).
 %% GM
 %% ---------------------------------------------------------------------------
 
+-spec joined(args(), members()) -> callback_result().
+
 joined([SPid], _Members) -> SPid ! {joined, self()}, ok.
 
+-spec members_changed(args(), members(),members()) -> callback_result().
+
 members_changed([_SPid], _Births, []) ->
     ok;
 members_changed([ SPid], _Births, Deaths) ->
@@ -492,6 +496,8 @@ members_changed([ SPid], _Births, Deaths) ->
         {promote, CPid} -> {become, rabbit_mirror_queue_coordinator, [CPid]}
     end.
 
+-spec handle_msg(args(), pid(), any()) -> callback_result().
+
 handle_msg([_SPid], _From, hibernate_heartbeat) ->
     %% See rabbit_mirror_queue_coordinator:handle_pre_hibernate/1
     ok;
@@ -518,6 +524,8 @@ handle_msg([SPid], _From, {sync_start, Ref, Syncer, SPids}) ->
 handle_msg([SPid], _From, Msg) ->
     ok = gen_server2:cast(SPid, {gm, Msg}).
 
+-spec handle_terminate(args(), term()) -> any().
+
 handle_terminate([_SPid], _Reason) ->
     ok.
 
diff --git a/deps/rabbit/src/rabbit_networking.erl b/deps/rabbit/src/rabbit_networking.erl
index 8806ed67d8..5c7900b335 100644
--- a/deps/rabbit/src/rabbit_networking.erl
+++ b/deps/rabbit/src/rabbit_networking.erl
@@ -183,16 +183,16 @@ tcp_listener_addresses_auto(Port) ->
     lists:append([tcp_listener_addresses(Listener) ||
                      Listener <- port_to_listeners(Port)]).
 
--spec tcp_listener_spec
-        (name_prefix(), address(), [gen_tcp:listen_option()], module(), module(),
-         any(), protocol(), non_neg_integer(), non_neg_integer(), label()) ->
-            supervisor:child_spec().
-
 tcp_listener_spec(NamePrefix, Address, SocketOpts, Transport, ProtoSup, ProtoOpts,
                   Protocol, NumAcceptors, Label) ->
     tcp_listener_spec(NamePrefix, Address, SocketOpts, Transport, ProtoSup, ProtoOpts,
                       Protocol, NumAcceptors, 1, Label).
 
+-spec tcp_listener_spec
+        (name_prefix(), address(), [gen_tcp:listen_option()], module(), module(),
+         any(), protocol(), non_neg_integer(), non_neg_integer(), label()) ->
+            supervisor:child_spec().
+
 tcp_listener_spec(NamePrefix, {IPAddress, Port, Family}, SocketOpts,
                   Transport, ProtoSup, ProtoOpts, Protocol, NumAcceptors,
                   ConcurrentConnsSupsCount, Label) ->
diff --git a/deps/rabbit/src/rabbit_node_monitor.erl b/deps/rabbit/src/rabbit_node_monitor.erl
index 1701dc6e2e..9c1231b80f 100644
--- a/deps/rabbit/src/rabbit_node_monitor.erl
+++ b/deps/rabbit/src/rabbit_node_monitor.erl
@@ -900,15 +900,16 @@ all_rabbit_nodes_up() ->
     Nodes = rabbit_mnesia:cluster_nodes(all),
     length(alive_rabbit_nodes(Nodes)) =:= length(Nodes).
 
+alive_nodes() -> alive_nodes(rabbit_mnesia:cluster_nodes(all)).
+
 -spec alive_nodes([node()]) -> [node()].
 
-alive_nodes() -> alive_nodes(rabbit_mnesia:cluster_nodes(all)).
 alive_nodes(Nodes) -> [N || N <- Nodes, lists:member(N, [node()|nodes()])].
 
--spec alive_rabbit_nodes([node()]) -> [node()].
-
 alive_rabbit_nodes() -> alive_rabbit_nodes(rabbit_mnesia:cluster_nodes(all)).
 
+-spec alive_rabbit_nodes([node()]) -> [node()].
+
 alive_rabbit_nodes(Nodes) ->
     [N || N <- alive_nodes(Nodes), rabbit:is_running(N)].
 
diff --git a/deps/rabbit/src/rabbit_router.erl b/deps/rabbit/src/rabbit_router.erl
index 011f280f4b..cce6093c92 100644
--- a/deps/rabbit/src/rabbit_router.erl
+++ b/deps/rabbit/src/rabbit_router.erl
@@ -18,14 +18,11 @@
 -type routing_key() :: binary().
 -type match_result() :: [rabbit_types:binding_destination()].
 
+%%----------------------------------------------------------------------------
+
 -spec match_bindings(rabbit_types:binding_source(),
                            fun ((rabbit_types:binding()) -> boolean())) ->
     match_result().
--spec match_routing_key(rabbit_types:binding_source(),
-                             [routing_key()] | ['_']) ->
-    match_result().
-
-%%----------------------------------------------------------------------------
 
 match_bindings(SrcName, Match) ->
     MatchHead = #route{binding = #binding{source      = SrcName,
@@ -34,6 +31,10 @@ match_bindings(SrcName, Match) ->
     [Dest || [#route{binding = Binding = #binding{destination = Dest}}] <-
         Routes, Match(Binding)].
 
+-spec match_routing_key(rabbit_types:binding_source(),
+                             [routing_key()] | ['_']) ->
+    match_result().
+
 match_routing_key(SrcName, [RoutingKey]) ->
     find_routes(#route{binding = #binding{source      = SrcName,
                                           destination = '$1',
diff --git a/deps/rabbit/src/rabbit_runtime_parameters.erl b/deps/rabbit/src/rabbit_runtime_parameters.erl
index 4b21b4f080..60f37b9dc7 100644
--- a/deps/rabbit/src/rabbit_runtime_parameters.erl
+++ b/deps/rabbit/src/rabbit_runtime_parameters.erl
@@ -55,35 +55,6 @@
 -type ok_or_error_string() :: 'ok' | {'error_string', string()}.
 -type ok_thunk_or_error_string() :: ok_or_error_string() | fun(() -> 'ok').
 
--spec parse_set(rabbit_types:vhost(), binary(), binary(), string(),
-                rabbit_types:user() | rabbit_types:username() | 'none')
-               -> ok_or_error_string().
--spec set(rabbit_types:vhost(), binary(), binary(), term(),
-                rabbit_types:user() | rabbit_types:username() | 'none')
-         -> ok_or_error_string().
--spec set_any(rabbit_types:vhost(), binary(), binary(), term(),
-              rabbit_types:user() | rabbit_types:username() | 'none')
-             -> ok_or_error_string().
--spec set_global(atom(), term(), rabbit_types:username()) -> 'ok'.
--spec clear(rabbit_types:vhost(), binary(), binary(), rabbit_types:username())
-           -> ok_thunk_or_error_string().
--spec clear_any(rabbit_types:vhost(), binary(), binary(), rabbit_types:username())
-                     -> ok_thunk_or_error_string().
--spec list() -> [rabbit_types:infos()].
--spec list(rabbit_types:vhost() | '_') -> [rabbit_types:infos()].
--spec list_component(binary()) -> [rabbit_types:infos()].
--spec list(rabbit_types:vhost() | '_', binary() | '_')
-                -> [rabbit_types:infos()].
--spec list_formatted(rabbit_types:vhost()) -> [rabbit_types:infos()].
--spec list_formatted(rabbit_types:vhost(), reference(), pid()) -> 'ok'.
--spec lookup(rabbit_types:vhost(), binary(), binary())
-                  -> rabbit_types:infos() | 'not_found'.
--spec value(rabbit_types:vhost(), binary(), binary()) -> term().
--spec value(rabbit_types:vhost(), binary(), binary(), term()) -> term().
--spec value_global(atom()) -> term() | 'not_found'.
--spec value_global(atom(), term()) -> term().
--spec info_keys() -> rabbit_types:info_keys().
-
 %%---------------------------------------------------------------------------
 
 -import(rabbit_misc, [pget/2]).
@@ -92,6 +63,10 @@
 
 %%---------------------------------------------------------------------------
 
+-spec parse_set(rabbit_types:vhost(), binary(), binary(), string(),
+                rabbit_types:user() | rabbit_types:username() | 'none')
+               -> ok_or_error_string().
+
 parse_set(_, <<"policy">>, _, _, _) ->
     {error_string, "policies may not be set using this method"};
 parse_set(VHost, Component, Name, String, User) ->
@@ -104,6 +79,10 @@ parse_set(VHost, Component, Name, String, User) ->
                 rabbit_misc:format("JSON decoding error. Reason: ~ts", [Reason])}
     end.
 
+-spec set(rabbit_types:vhost(), binary(), binary(), term(),
+                rabbit_types:user() | rabbit_types:username() | 'none')
+         -> ok_or_error_string().
+
 set(_, <<"policy">>, _, _, _) ->
     {error_string, "policies may not be set using this method"};
 set(VHost, Component, Name, Term, User) ->
@@ -119,6 +98,8 @@ parse_set_global(Name, String, ActingUser) ->
                 rabbit_misc:format("JSON decoding error. Reason: ~ts", [Reason])}
     end.
 
+-spec set_global(atom(), term(), rabbit_types:username()) -> 'ok'.
+
 set_global(Name, Term, ActingUser)  ->
     NameAsAtom = rabbit_data_coercion:to_atom(Name),
     rabbit_log:debug("Setting global parameter '~s' to ~p", [NameAsAtom, Term]),
@@ -131,6 +112,10 @@ set_global(Name, Term, ActingUser)  ->
 format_error(L) ->
     {error_string, rabbit_misc:format_many([{"Validation failed~n", []} | L])}.
 
+-spec set_any(rabbit_types:vhost(), binary(), binary(), term(),
+              rabbit_types:user() | rabbit_types:username() | 'none')
+             -> ok_or_error_string().
+
 set_any(VHost, Component, Name, Term, User) ->
     case set_any0(VHost, Component, Name, Term, User) of
         ok          -> ok;
@@ -196,6 +181,9 @@ mnesia_update_fun(Key, Term) ->
             Res
     end.
 
+-spec clear(rabbit_types:vhost(), binary(), binary(), rabbit_types:username())
+           -> ok_thunk_or_error_string().
+
 clear(_, <<"policy">> , _, _) ->
     {error_string, "policies may not be cleared using this method"};
 clear(VHost, Component, Name, ActingUser) ->
@@ -235,6 +223,9 @@ clear_component(Component, ActingUser) ->
             ok
     end.
 
+-spec clear_any(rabbit_types:vhost(), binary(), binary(), rabbit_types:username())
+                     -> ok_thunk_or_error_string().
+
 clear_any(VHost, Component, Name, ActingUser) ->
     Notify = fun () ->
                      case lookup_component(Component) of
@@ -269,15 +260,25 @@ event_notify(Event, VHost, Component, Props) ->
     rabbit_event:notify(Event, [{vhost,     VHost},
                                 {component, Component} | Props]).
 
+-spec list() -> [rabbit_types:infos()].
+
 list() ->
     [p(P) || #runtime_parameters{ key = {_VHost, Comp, _Name}} = P <-
              rabbit_misc:dirty_read_all(?TABLE), Comp /= <<"policy">>].
 
-list(VHost)               -> list(VHost, '_').
+-spec list(rabbit_types:vhost() | '_') -> [rabbit_types:infos()].
+
+list(VHost) -> list(VHost, '_').
+
+-spec list_component(binary()) -> [rabbit_types:infos()].
+
 list_component(Component) -> list('_',   Component).
 
 %% Not dirty_match_object since that would not be transactional when used in a
 %% tx context
+-spec list(rabbit_types:vhost() | '_', binary() | '_')
+                -> [rabbit_types:infos()].
+
 list(VHost, Component) ->
     mnesia:async_dirty(
       fun () ->
@@ -301,6 +302,8 @@ list_global() ->
                 is_atom(P#runtime_parameters.key)]
         end).
 
+-spec list_formatted(rabbit_types:vhost()) -> [rabbit_types:infos()].
+
 list_formatted(VHost) ->
     [ format_parameter(info_keys(), P) || P <- list(VHost) ].
 
@@ -316,6 +319,8 @@ format_parameter(InfoKeys, P) ->
                 end,
                 [], InfoKeys).
 
+-spec list_formatted(rabbit_types:vhost(), reference(), pid()) -> 'ok'.
+
 list_formatted(VHost, Ref, AggregatorPid) ->
     rabbit_control_misc:emitting_map(
       AggregatorPid, Ref,
@@ -329,6 +334,9 @@ list_global_formatted(Ref, AggregatorPid) ->
         AggregatorPid, Ref,
         fun(P) -> format_parameter(global_info_keys(), P) end, list_global()).
 
+-spec lookup(rabbit_types:vhost(), binary(), binary())
+                  -> rabbit_types:infos() | 'not_found'.
+
 lookup(VHost, Component, Name) ->
     case lookup0({VHost, Component, Name}, rabbit_misc:const(not_found)) of
         not_found -> not_found;
@@ -341,12 +349,21 @@ lookup_global(Name)  ->
         Params    -> p(Params)
     end.
 
-value(VHost, Comp, Name)      -> value0({VHost, Comp, Name}).
+-spec value(rabbit_types:vhost(), binary(), binary()) -> term().
+
+value(VHost, Comp, Name) -> value0({VHost, Comp, Name}).
+
+-spec value(rabbit_types:vhost(), binary(), binary(), term()) -> term().
+
 value(VHost, Comp, Name, Def) -> value0({VHost, Comp, Name}, Def).
 
+-spec value_global(atom()) -> term() | 'not_found'.
+
 value_global(Key) ->
     value0(Key).
 
+-spec value_global(atom(), term()) -> term().
+
 value_global(Key, Default) ->
     value0(Key, Default).
 
@@ -391,6 +408,8 @@ p(#runtime_parameters{key = Key, value = Value}) when is_atom(Key) ->
     [{name,      Key},
      {value,     Value}].
 
+-spec info_keys() -> rabbit_types:info_keys().
+
 info_keys() -> [component, name, value].
 
 global_info_keys() -> [name, value].
diff --git a/deps/rabbit/src/rabbit_vm.erl b/deps/rabbit/src/rabbit_vm.erl
index 0ef8609a27..01fce8b962 100644
--- a/deps/rabbit/src/rabbit_vm.erl
+++ b/deps/rabbit/src/rabbit_vm.erl
@@ -325,16 +325,17 @@ ra_type(PDict) ->
                                   info_value()).
 -type distinguisher() :: fun (([{term(), term()}]) -> atom()).
 -type distinguishers() :: [{info_key(), distinguisher()}].
+
 -spec sum_processes([process()], distinguishers(), [info_key()]) ->
                               {[{process(), [info_item()]}], [info_item()]}.
--spec sum_processes([process()], accumulate(), distinguishers(),
-                          [info_item()]) ->
-                              {[{process(), [info_item()]}], [info_item()]}.
 
 sum_processes(Names, Distinguishers, Items) ->
     sum_processes(Names, fun (_, X, Y) -> X + Y end, Distinguishers,
                   [{Item, 0} || Item <- Items]).
 
+-spec sum_processes([process()], accumulate(), distinguishers(),
+                          [info_item()]) ->
+                              {[{process(), [info_item()]}], [info_item()]}.
 %% summarize the process_info of all processes based on their
 %% '$ancestor' hierarchy, recorded in their process dictionary.
 %%