erpc doc changes for always_spawn

lib/kernel/src/erpc.erl

@@ -83,7 +83,10 @@ is available on the involved nodes.
          reqids_add/3,
          reqids_to_list/1]).
 
--export_type([request_id/0, request_id_collection/0, timeout_time/0]).
+-export_type([call_options/0,
+	      request_id/0,
+	      request_id_collection/0,
+	      timeout_time/0]).
 
 %% Internal exports (also used by the 'rpc' module)
 
@@ -121,13 +124,25 @@ The value can be:
   a time further into the future than `4294967295` milliseconds. Identifying the
   timeout using an absolute timeout value is especially handy when you have a
   deadline for responses corresponding to a complete collection of requests
-  (`t:request_id_collection/0`) , since you do not have to recalculate the
+  (`t:request_id_collection/0`), since you do not have to recalculate the
   relative time until the deadline over and over again.
 """.
 -type timeout_time() :: 0..?MAX_INT_TIMEOUT | 'infinity' | {abs, integer()}.
 
--type call_options() :: #{'timeout' => timeout_time(),
-			  'always_spawn' => boolean()}.
+-doc """
+Options to be used in [`call/3,5`](`call/5`) and
+[`multicall/3,5`](`multicall/5`) functions.
+
+- **`timeout`** - Upper time limit for call operations to complete, see
+  `t:timeout_time/0`. Default: `infinity`.
+
+- **`always_spawn`** - If `true`, the `apply()` will _always_ be performed
+  in a freshly spawned process. If `false`, the calling process _may_ be
+  used instead, if possible. Default: `false`.
+""".
+-doc(#{since => <<"OTP 28.0">>}).
+-type call_options() :: #{'timeout' => Timeout :: timeout_time(),
+			  'always_spawn' => AlwaysSpawn :: boolean()}.
 
 %%------------------------------------------------------------------------
 %% Exported API
@@ -178,8 +193,10 @@ call(N, M, F, A) ->
 
 -doc """
 Evaluates [`apply(Module, Function, Args)`](`apply/3`) on node `Node` and
-returns the corresponding value `Result`. `Timeout` sets an upper time limit for
-the `call` operation to complete.
+returns the corresponding value `Result`.
+
+`TimeoutOrOptions` can be either a [`timeout time`](`t:timeout_time/0`) or a
+[`call options`](`t:call_options/0`) map (since OTP 28.0).
 
 The `call()` function only returns if the applied function successfully returned
 without raising any uncaught exceptions, the operation did not time out, and no
@@ -242,9 +259,9 @@ communication may, of course, reach the calling process.
 
 > #### Note {: .info }
 >
-> You cannot make _any_ assumptions about the process that will perform the
-> `apply()`. It may be the calling process itself, a server, or a freshly
-> spawned process.
+> If the `always_spawn` option is `false` (which is the default), you cannot make
+> _any_ assumptions about the process that will perform the `apply()`. It may be
+> the calling process itself, or a freshly spawned process.
 """.
 -doc(#{since => <<"OTP 23.0">>}).
 -spec call(Node, Module, Function, Args, TimeoutOrOptions) -> Result when
@@ -322,11 +339,6 @@ Fails with an `{erpc, badarg}` `error` exception if:
 
 - `Node` is not an atom.
 - `Fun` is not a fun of zero arity.
-
-> #### Note {: .info }
->
-> You cannot make _any_ assumptions about the process that will perform the
-> `apply()`. It may be a server, or a freshly spawned process.
 """.
 -doc(#{since => <<"OTP 23.0">>}).
 -spec send_request(Node, Fun) -> RequestId when
@@ -377,11 +389,6 @@ Fails with an `{erpc, badarg}` `error` exception if:
 - `Args` is not a list. Note that the list is not verified to be a proper list
   at the client side.
 
-> #### Note {: .info }
->
-> You cannot make _any_ assumptions about the process that will perform the
-> `apply()`. It may be a server, or a freshly spawned process.
-
 Equivalent to
 [`erpc:send_request(Node, erlang, apply, [Fun,[]]), Label, RequestIdCollection)`](`send_request/6`).
 
@@ -390,11 +397,6 @@ Fails with an `{erpc, badarg}` `error` exception if:
 - `Node` is not an atom.
 - `Fun` is not a fun of zero arity.
 - `RequestIdCollection` is detected not to be request identifier collection.
-
-> #### Note {: .info }
->
-> You cannot make _any_ assumptions about the process that will perform the
-> `apply()`. It may be a server, or a freshly spawned process.
 """.
 -doc(#{since => <<"OTP 23.0">>}).
 -spec send_request(Node, Module, Function, Args) -> RequestId when
@@ -446,11 +448,6 @@ Fails with an `{erpc, badarg}` `error` exception if:
 - `Args` is not a list. Note that the list is not verified to be a proper list
   at the client side.
 - `RequestIdCollection` is detected not to be request identifier collection.
-
-> #### Note {: .info }
->
-> You cannot make _any_ assumptions about the process that will perform the
-> `apply()`. It may be a server, or a freshly spawned process.
 """.
 -doc(#{since => <<"OTP 25.0">>}).
 -spec send_request(Node, Module, Function, Args,
@@ -1050,8 +1047,12 @@ multicall(Ns, M, F, A) ->
 Performs multiple `call` operations in parallel on multiple nodes.
 
 That is, evaluates [`apply(Module, Function, Args)`](`apply/3`) on the nodes `Nodes` in
-parallel. `Timeout` sets an upper time limit for all `call` operations to
-complete. The result is returned as a list where the result from each node is
+parallel.
+
+`TimeoutOrOptions` can be either a [`timeout time`](`t:timeout_time/0`) or a
+[`call options`](`t:call_options/0`) map (since OTP 28.0).
+
+The result is returned as a list where the result from each node is
 placed at the same position as the node name is placed in `Nodes`. Each item in
 the resulting list is formatted as either:
 
@@ -1107,9 +1108,9 @@ calling process, such communication may, of course, reach the calling process.
 
 > #### Note {: .info }
 >
-> You cannot make _any_ assumptions about the process that will perform the
-> `apply()`. It may be the calling process itself, a server, or a freshly
-> spawned process.
+> If the `always_spawn` option is `false` (which is the default), you cannot make
+> _any_ assumptions about the processes that will perform the `apply()`s. It may be
+> the calling process itself, or freshly spawned processes, or a mix of both.
 """.
 -doc(#{since => <<"OTP 23.0">>}).
 -spec multicall(Nodes, Module, Function, Args, TimeoutOrOptions) -> Result when
@@ -1174,11 +1175,6 @@ if:
 - `Function` is not an atom.
 - `Args` is not a list. Note that the list is not verified to be a proper list
   at the client side.
-
-> #### Note {: .info }
->
-> You cannot make _any_ assumptions about the process that will perform the
-> `apply()`. It may be a server, or a freshly spawned process.
 """.
 -doc(#{since => <<"OTP 23.0">>}).
 -spec multicast(Nodes, Module, Function, Args) -> 'ok' when
@@ -1234,11 +1230,6 @@ ignored.
 - `Function` is not an atom.
 - `Args` is not a list. Note that the list is not verified to be a proper list
   at the client side.
-
-> #### Note {: .info }
->
-> You cannot make _any_ assumptions about the process that will perform the
-> `apply()`. It may be a server, or a freshly spawned process.
 """.
 -doc(#{since => <<"OTP 23.0">>}).
 -spec cast(Node, Module, Function, Args) -> 'ok' when