Merge branch 'lukas/otp/fix-broken-doc-signatures' into maint

* lukas/otp/fix-broken-doc-signatures:
  tftp: Remove trailing anchors
  snmp: Remove trailing anchors
  megaco: Remove trailing anchors
  inets: Remove trailing anchors
  ftp: Remove trailing anchors
  wx: Fix broken doc signatures
  stdlib: Fix broken doc signatures
  ssh: Fix broken doc signatures
  snmp: Fix broken doc signatures
  observer: Fix broken doc signatures
  mnesia: Fix broken doc signatures
  megaco: Fix broken doc signatures
  inets: Fix broken doc signatures
  et: Fix broken doc signatures
  eldap: Fix broken doc signatures
  diameter: Fix broken doc signatures

lib/diameter/src/base/diameter_codec.erl

@@ -286,8 +286,6 @@ Diameter messages.
 %% *the* encode.
 
 -doc """
-encode(Mod, Msg) -> Pkt
-
 Encode a Diameter message.
 """.
 -doc(#{since => <<"OTP R15B03">>}).
@@ -477,8 +475,6 @@ rec2msg(Mod, Rec) ->
 %% longer *the* decode.
 
 -doc """
-decode(Mod, Bin) -> Pkt
-
 Decode a Diameter message.
 """.
 -doc(#{since => <<"OTP R15B03">>}).

lib/diameter/src/compiler/diameter_make.erl

@@ -91,13 +91,12 @@ Unrecognized options are silently ignored.
 %% two.
 
 -doc """
-codec(File :: iolist() | binary(), [Opt]) -> ok | {ok, [Out]} | {error, Reason}
+Compile a single dictionary file.
 
-Compile a single dictionary file. The input `File` can be either a path or a
-literal dictionary, the occurrence of newline (ascii NL) or carriage return
-(ascii CR) identifying the latter. `Opt` determines the format of the results
-and whether they are written to file or returned, and can have the following
-types.
+The input `File` can be either a path or a literal dictionary, the occurrence
+of newline (ascii NL) or carriage return (ascii CR) identifying the latter.
+`Opt` determines the format of the results and whether they are written to
+file or returned, and can have the following types.
 
 - **`parse | forms | erl | hrl`** - Specifies an output format. Whether the
   output is returned or written to file depends on whether or not option
@@ -183,7 +182,7 @@ codec(File) ->
 %% Turn an orddict returned by dict/1-2 back into a dictionary.
 
 -doc """
-format(Parsed) -> iolist()
+format(Parsed)
 
 Turns a parsed dictionary, as returned by `codec/2`, back into the dictionary
 format.
@@ -200,7 +199,7 @@ format([?VERSION | Dict]) ->
 %% Reconstitute a dictionary without @inherits.
 
 -doc """
-flatten(Parsed) -> term()
+flatten(Parsed)
 
 Reconstitute a parsed dictionary, as returned by `codec/2`, without using
 [`@inherits`](diameter_dict.md#inherits). That is, construct an equivalent
@@ -224,8 +223,6 @@ flatten([?VERSION = V | Dict]) ->
 %% format_error/1
 
 -doc """
-format_error(Reason) -> string()
-
 Turn an error reason returned by `codec/2` into a readable string.
 """.
 -doc(#{since => <<"OTP 17.0">>}).

lib/diameter/src/transport/diameter_sctp.erl

@@ -161,8 +161,6 @@ be specified as the value of a transport_module option to
 %% ---------------------------------------------------------------------------
 
 -doc """
-start({Type, Ref}, Svc, [Opt]) -> {ok, Pid, [LAddr]} | {error, Reason}
-
 The start function required by `m:diameter_transport`.
 
 Options `raddr` and `rport` specify the remote address and port for a connecting
@@ -226,14 +224,14 @@ connecting transport.
    -> {ok, pid(), [inet:ip_address()]}
  when Ref :: diameter:transport_ref().
 
-start(T, Svc, Opts)
-  when is_list(Opts) ->
+start(TypeRef, Svc, Options)
+  when is_list(Options) ->
     #diameter_service{capabilities = Caps,
                       pid = Pid}
         = Svc,
     diameter_sctp_sup:start(),  %% start supervisors on demand
     Addrs = Caps#diameter_caps.host_ip_address,
-    s(T, Addrs, Pid, Opts).
+    s(TypeRef, Addrs, Pid, Options).
 
 %% A listener spawns transports either as a consequence of this call
 %% when there is not yet an association to assign it, or at comm_up on

lib/eldap/src/eldap.erl

@@ -1921,9 +1921,6 @@ get_head([H|Rest],Tail,Rhead) -> get_head(Rest,Tail,[H|Rhead]).
 %%% --------------------------------------------------------------------
 
 -doc """
-paged_result_control(PageSize) -> {control, "1.2.840.113556.1.4.319", true,
-binary()}
-
 Paged results is an extension to the LDAP protocol specified by RFC2696
 
 This function creates a control with the specified page size for use in
@@ -1943,9 +1940,6 @@ paged_result_control(PageSize) when is_integer(PageSize) ->
     paged_result_control(PageSize, "").
 
 -doc """
-paged_result_control(PageSize, Cookie) -> {control, "1.2.840.113556.1.4.319",
-true, binary()}
-
 Paged results is an extension to the LDAP protocol specified by RFC2696
 
 This function creates a control with the specified page size and cookie for use
@@ -1986,7 +1980,7 @@ paged_result_control(PageSize, Cookie) when is_integer(PageSize) ->
 %%% --------------------------------------------------------------------
 
 -doc """
-paged_result_cookie(SearchResult) -> binary()
+paged_result_cookie(SearchResult)
 
 Paged results is an extension to the LDAP protocol specified by RFC2696.
 

lib/et/src/et.erl

@@ -136,8 +136,6 @@ Interface module for the Event Trace (ET) application
 %%----------------------------------------------------------------------
 
 -doc """
-trace_me(DetailLevel, FromTo, Label, Contents) -> hopefully_traced
-
 Invokes `et:trace_me/5` with both `From` and `To` set to `FromTo`.
 """.
 -doc(#{since => <<"OTP R13B04">>}).
@@ -151,8 +149,6 @@ trace_me(DetailLevel, FromTo, Label, Contents)
     ?MODULE:trace_me(DetailLevel, FromTo, FromTo, Label, Contents).
 
 -doc """
-trace_me(DetailLevel, From, To, Label, Contents) -> hopefully_traced
-
 A function that is intended to be traced.
 
 This function is intended to be invoked at strategic places in user applications
@@ -192,8 +188,6 @@ phone_home(DetailLevel, FromTo, Label, Contents) ->
     ?MODULE:trace_me(DetailLevel, FromTo, FromTo, Label, Contents).
 
 -doc """
-phone_home(DetailLevel, From, To, Label, Contents) -> hopefully_traced
-
 These functions sends a signal to the outer space and the caller hopes that
 someone is listening. In other words, they invoke `et:trace_me/4` and
 `et:trace_me/5` respectively.
@@ -219,8 +213,6 @@ report_event(DetailLevel, FromTo, Label, Contents) ->
     ?MODULE:trace_me(DetailLevel, FromTo, FromTo, Label, Contents).
 
 -doc """
-report_event(DetailLevel, From, To, Label, Contents) -> hopefully_traced
-
 Deprecated functions which for the time being are kept for backwards
 compatibility. Invokes `et:trace_me/4` and `et:trace_me/5` respectively.
 """.

lib/et/src/et_collector.erl

@@ -207,8 +207,6 @@ Interface module for the Event Trace (ET) application
 %% Reason = term()
 %%----------------------------------------------------------------------
 -doc """
-start_link(Options) -> {ok, CollectorPid} | {error, Reason}
-
 Start a collector process.
 
 The collector collects trace events and keeps them ordered by their timestamp.
@@ -352,11 +350,9 @@ start_clients(CollectorPid, []) ->
 %% CollectorPid = pid()
 %%----------------------------------------------------------------------
 -doc """
-stop(CollectorPid) -> ok
-
 Stop a collector process.
 """.
--spec stop(CollectorPid::pid()) -> ok.
+-spec stop(pid()) -> ok.
 stop(CollectorPid) ->
     call(CollectorPid, stop).
 
@@ -386,8 +382,6 @@ stop(CollectorPid) ->
 %% The options defaults to existing, write and keep.
 %%----------------------------------------------------------------------
 -doc """
-save_event_file(CollectorPid, FileName, Options) -> ok | {error, Reason}
-
 Save the events to a file.
 
 By default the currently stored events (existing) are written to a brand new
@@ -528,8 +522,8 @@ report(_, Bad) ->
     exit({bad_event, Bad}).
 
 -doc(#{equiv => report_event/6}).
--spec report_event(CollectorPid, DetailLevel, FromTo, Label, Contents) -> {ok, Continuation} when
-      CollectorPid :: pid(),
+-spec report_event(Handle, DetailLevel, FromTo, Label, Contents) -> {ok, Continuation} when
+      Handle :: CollectorPid :: pid() | table_handle(),
       DetailLevel :: level(),
       FromTo :: actor(),
       Label  :: term(),
@@ -539,18 +533,15 @@ report_event(CollectorPid, DetailLevel, FromTo, Label, Contents) ->
     report_event(CollectorPid, DetailLevel, FromTo, FromTo, Label, Contents).
 
 -doc """
-report_event(Handle, DetailLevel, From, To, Label, Contents) -> {ok,
-Continuation} | exit(Reason)
-
 Report an event to the collector.
 
 All events are filtered thru the collector filter, which optionally may
 transform or discard the event. The first call should use the pid of the
 collector process as report handle, while subsequent calls should use the table
 handle.
 """.
--spec report_event(CollectorPid, DetailLevel, From, To, Label, Contents) -> {ok, Continuation} when
-      CollectorPid :: pid(),
+-spec report_event(Handle, DetailLevel, From, To, Label, Contents) -> {ok, Continuation} when
+      Handle :: CollectorPid :: pid() | table_handle(),
       DetailLevel :: level(),
       From :: actor(),
       To :: actor(),
@@ -582,8 +573,6 @@ report_event(CollectorPid, DetailLevel, From, To, Label, Contents)
 %%----------------------------------------------------------------------
 
 -doc """
-make_key(Type, Stuff) -> Key
-
 Make a key out of an event record or an old key.
 """.
 -spec make_key(Handle, Stuff) -> Key when
@@ -644,8 +633,6 @@ get_table_handle(CollectorPid) when is_pid(CollectorPid) ->
 %% Reason = term()
 %%----------------------------------------------------------------------
 -doc """
-get_global_pid() -> CollectorPid | exit(Reason)
-
 Return a the identity of the globally registered collector if there is any.
 """.
 -spec get_global_pid() -> CollectorPid :: pid().
@@ -671,8 +658,6 @@ get_global_pid() ->
 %% TracePattern = {report_module(), dbg_match_spec_match_spec()}
 %%----------------------------------------------------------------------
 -doc """
-change_pattern(CollectorPid, RawPattern) -> {old_pattern, TracePattern}
-
 Change active trace pattern globally on all trace nodes.
 """.
 -spec change_pattern(CollectorPid, RawPattern) -> {old_pattern, TracePattern} when
@@ -709,11 +694,7 @@ change_pattern(CollectorPid, RawPattern) ->
 %% Val = term()
 %%----------------------------------------------------------------------
 -doc """
-dict_insert(CollectorPid, Key, Val) -> okdict_insert(CollectorPid, {subscriber,
-SubscriberPid}, Void) -> okdict_insert(CollectorPid, {filter, collector},
-FilterFun) -> ok
-
-Insert a dictionary entry and send a \{et, \{dict_insert, Key, Val\}\} tuple to
+Insert a dictionary entry and send a `{et, {dict_insert, Key, Val}}` tuple to
 all registered subscribers.
 
 If the entry is a new subscriber, it will imply that the new subscriber process
@@ -754,8 +735,6 @@ dict_insert(CollectorPid, Key, Val) ->
 %% Val = term()
 %%----------------------------------------------------------------------
 -doc """
-dict_lookup(CollectorPid, Key) -> [Val]
-
 Lookup a dictionary entry and return zero or one value.
 """.
 -spec dict_lookup(CollectorPid::pid(), Key::term()) -> [Val::term()].
@@ -781,8 +760,6 @@ dict_lookup(CollectorPid, Key) ->
 %% Key = term()
 %%----------------------------------------------------------------------
 -doc """
-dict_delete(CollectorPid, Key) -> ok
-
 Delete a dictionary entry and send a \{et, \{dict_delete, Key\}\} tuple to all
 registered subscribers.
 
@@ -808,8 +785,6 @@ dict_delete(CollectorPid, Key) ->
 %% val() = term()
 %%----------------------------------------------------------------------
 -doc """
-dict_match(CollectorPid, Pattern) -> [Match]
-
 Match some dictionary entries
 """.
 -spec dict_match(CollectorPid::pid(), {KeyPattern, ValPattern}) -> [Match] when
@@ -828,8 +803,6 @@ dict_match(CollectorPid, Pattern)  ->
 %% Msg = term()
 %%----------------------------------------------------------------------
 -doc """
-multicast(\_CollectorPid, Msg) -> ok
-
 Sends a message to all registered subscribers.
 """.
 -spec multicast(CollectorPid :: pid(), Msg::term()) -> ok.
@@ -851,9 +824,6 @@ multicast(CollectorPid, Msg) ->
 %% Pid        = dbg_trace_client_pid()
 %%----------------------------------------------------------------------
 -doc """
-start_trace_client(CollectorPid, Type, Parameters) -> file_loaded |
-{trace_client_pid, pid()} | exit(Reason)
-
 Load raw Erlang trace from a file, port or process.
 """.
 -spec start_trace_client(CollectorPid, Type, Parameter) -> file_loaded | {trace_client_pid, pid()} when
@@ -920,11 +890,7 @@ monitor_trace_port(CollectorPid, Parameters) ->
 %% 
 %% Short for iterate/5.
 %%----------------------------------------------------------------------
--doc """
-iterate(Handle, Prev, Limit) -> NewAcc
-
-Short for iterate(Handle, Prev, Limit, undefined, Prev) -> NewAcc
-""".
+-doc #{ equiv => iterate(Handle, Prev, Limit, undefined, Prev) }.
 -spec iterate(Handle, Prev, Limit) -> NewAcc when
       Handle :: CollectorPid | table_handle(),
       CollectorPid :: pid(),
@@ -957,8 +923,6 @@ iterate(Handle, Prev, Limit) ->
 %% Acc = NewAcc = term()
 %%----------------------------------------------------------------------
 -doc """
-iterate(Handle, Prev, Limit, Fun, Acc) -> NewAcc
-
 Iterate over the currently stored events.
 
 Iterates over the currently stored events and applies a function for each event.
@@ -1115,8 +1079,6 @@ incr(Val, Incr) ->
 %% table_handle() = record(table_handle)
 %%----------------------------------------------------------------------
 -doc """
-clear_table(Handle) -> ok
-
 Clear the event table.
 """.
 -spec clear_table(Handle) -> ok when

lib/et/src/et_selector.erl

@@ -52,7 +52,7 @@
 %%   integer() - explicit detail level of tracing
 %%----------------------------------------------------------------------
 -doc """
-make_pattern(RawPattern) -> TracePattern
+make_pattern(RawPattern)
 
 Makes a trace pattern suitable to feed change_pattern/1
 
@@ -115,7 +115,7 @@ make_pattern({Mod, Pattern}) when is_atom(Mod) ->
 %% accordingly with erlang:trace_pattern/2.
 %%----------------------------------------------------------------------
 -doc """
-change_pattern(Pattern) -> ok
+change_pattern(Pattern)
 
 Activates/deactivates tracing by changing the current trace pattern.
 
@@ -219,8 +219,6 @@ error_to_exit({ok, _Res}) ->
 %%                   should be dropped
 %%----------------------------------------------------------------------
 -doc """
-parse_event(Mod, ValidTraceData) -> false | true | {true, Event}
-
 Transforms trace data and makes an event record out of it.
 
 See `erlang:trace/3` for more info about the semantics of the trace data.