Improve other diameter_app doc

1 files changed, 112 insertions, 80 deletions

diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index 98c8b8c807..9d8a6568eb 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -112,7 +112,8 @@ and, for the call-specific callbacks, any extra arguments passed to
 <item>
 <p>
 A record containing the identities of
-the local Diameter node and the remote Diameter peer having an established transport
+the local Diameter node and the remote Diameter peer having an
+established transport
 connection, as well as the capabilities as
 determined by capabilities exchange.
 Each field of the record is a 2-tuple consisting of
@@ -168,13 +169,14 @@ Fields should not be set in return values except as documented.</p>
 <tag><c>peer_ref() = term()</c></tag>
 <item>
 <p>
-A term identifying a transport connection with a Diameter peer.
-Should be treated opaquely.</p>
+A term identifying a transport connection with a Diameter peer.</p>
 </item>
 
 <marker id="peer"/>
 
-<tag><c>peer() = {<seealso marker="#peer_ref">peer_ref()</seealso>, <seealso marker="#capabilities">capabilities()</seealso>}</c></tag>
+<tag><c>peer() =
+          {<seealso marker="#peer_ref">peer_ref()</seealso>,
+           <seealso marker="#capabilities">capabilities()</seealso>}</c></tag>
 <item>
 <p>
 A tuple representing a Diameter peer connection.</p>
@@ -219,10 +221,29 @@ process.</p>
 </type>
 <desc>
 <p>
-Invoked when a transport connection has been established
-and a successful capabilities exchange has indicated that the peer
-supports the Diameter application of the application on which
-the callback module in question has been configured.</p>
+Invoked to signal the availability of a peer connection.
+In particular, capabilities exchange with the peer has indicated
+support for the application in question, the RFC 3539 watchdog state
+machine for the connection has reached state <c>OKAY</c> and Diameter
+messages can be both sent and received.</p>
+
+<note>
+<p>
+A watchdog state machine can reach state <c>OKAY</c> from state
+<c>SUSPECT</c> without a new capabilities exchange taking place.
+A new transport connection (and capabilities exchange) results in a
+new peer_ref().</p>
+</note>
+
+<note>
+<p>
+There is no requirement that a callback return before incoming
+requests are received: <seealso
+marker="#handle_request">handle_request/3</seealso> callbacks must be
+handled independently of <seealso
+marker="#peer_up">peer_up/3</seealso> and <seealso
+marker="#peer_down">peer_down/3</seealso>.</p>
+</note>
 
 <marker id="peer_down"/>
 </desc>
@@ -238,36 +259,42 @@ the callback module in question has been configured.</p>
 </type>
 <desc>
 <p>
-Invoked when a transport connection has been lost following a previous
-call to <seealso marker="#peer_up">peer_up/3</seealso>.</p>
+Invoked to signal that a peer connection is no longer available
+following a previous call to <seealso
+marker="#peer_up">peer_up/3</seealso>.
+In particular, that the RFC 3539 watchdog state machine for the
+connection has left state <c>OKAY</c> and the peer will no longer be a
+candidate in <seealso marker="#pick_peer">pick_peer()</seealso>
+callbacks.</p>
 
 <marker id="pick_peer"/>
 </desc>
 </func>
 
 <func>
-<name>Mod:pick_peer(Candidates, Reserved, SvcName, State)
-      -> {ok, Peer} | {Peer, NewState} | false</name>
+<name>Mod:pick_peer(Candidates, _Reserved, SvcName, State)
+      -> Selection | false</name>
 <fsummary>Select a target peer for an outgoing request.</fsummary>
 <type>
 <v>Candidates = [<seealso marker="#peer">peer()</seealso>]</v>
-<v>Peer = <seealso marker="#peer">peer()</seealso> | false</v>
 <v>SvcName = <seealso marker="diameter#service_name">diameter:service_name()</seealso></v>
 <v>State = NewState = <seealso marker="#state">state()</seealso></v>
+<v>Selection = {ok, Peer} | {Peer, NewState}</v>
+<v>Peer = <seealso marker="#peer">peer()</seealso> | false</v>
 </type>
 <desc>
 <p>
 Invoked as a consequence of a call to <seealso
 marker="diameter#call">diameter:call/4</seealso> to select a destination
-peer for an outgoing request, the return value indicating the selected
-peer.</p>
+peer for an outgoing request.
+The return value indicates the selected peer.</p>
 
 <p>
-The candidate peers list will only include those
-which are selected by any <c>filter</c> option specified in the call to
-<seealso marker="diameter#call">diameter:call/4</seealso>, and only
-those which have indicated support for the Diameter application in
-question.
+The candidate list contains only those peers that have advertised
+support for the Diameter application in question during capabilities
+exchange, that have not be excluded by a <c>filter</c> option in
+the call to <seealso marker="diameter#call">diameter:call/4</seealso>
+and whose watchdog state machine is in the <c>OKAY</c> state.
 The order of the elements is unspecified except that any
 peers whose Origin-Host and Origin-Realm matches that of the
 outgoing request (in the sense of a <c>{filter, {all, [host, realm]}}</c>
@@ -275,36 +302,40 @@ option to <seealso marker="diameter#call">diameter:call/4</seealso>)
 will be placed at the head of the list.</p>
 
 <p>
-The return values <c>false</c> and <c>{false, State}</c> are
-equivalent when callback state is mutable, as are
-<c>{ok, Peer}</c> and <c>{Peer, State}</c>.
-Returning a peer as <c>false</c> causes <c>{error, no_connection}</c>
-to be returned from <seealso marker="diameter#call">diameter:call/4</seealso>.
-Returning a <seealso marker="#peer">peer()</seealso> from an initial
-pick_peer/4 callback will result in a
-<seealso marker="#prepare_request">prepare_request/3</seealso> callback
-followed by either <seealso
-marker="#handle_answer">handle_answer/4</seealso>
+A callback that returns a peer() will be followed by a
+<seealso marker="#prepare_request">prepare_request/3</seealso>
+callback and, if the latter indicates that the request should be sent,
+by either <seealso marker="#handle_answer">handle_answer/4</seealso>
 or <seealso marker="#handle_error">handle_error/4</seealso> depending
 on whether or not an answer message is received from the peer.
-If transport with the peer is lost before this then a new <seealso
-marker="#pick_peer">pick_peer/4</seealso> callback takes place to
-select an alternate peer.</p>
-
-<p>
-Note that there is no guarantee that a <seealso
+If the transport becomes unavailable after <seealso
+marker="prepare_request">prepare_request/3</seealso> then a new <seealso
+marker="#pick_peer">pick_peer/4</seealso> callback may take place to
+failover to an alternate peer, after which <seealso
+marker="#prepare_retransmit">prepare_retransmit/3</seealso> takes the
+place of <seealso
+marker="prepare_request">prepare_request/3</seealso> in resending the
+request.
+There is no guarantee that a <seealso
 marker="#pick_peer">pick_peer/4</seealso> callback to select
-an alternate peer will be followed by any additional callbacks, only
-that the initial <seealso
-marker="#pick_peer">pick_peer/4</seealso> will be, since a
+an alternate peer will be followed by any additional callbacks since a
 retransmission to an alternate peer is abandoned if an answer is
 received from a previously selected peer.</p>
 
+<p>
+Returning <c>false</c> or <c>{false, NewState}</c> causes <c>{error,
+no_connection}</c> to be returned from <seealso
+marker="diameter#call">diameter:call/4</seealso>.</p>
+
+<p>
+The return values <c>false</c> and <c>{false, State}</c> (that is,
+<c>NewState = State</c>) are equivalent, as are <c>{ok, Peer}</c> and
+<c>{Peer, State}</c>.</p>
+
 <note>
 <p>
-<c>{Peer, NewState}</c> and its equivalents can only be returned if
-the Diameter application in question was
-configured with the <seealso
+The return value <c>{Peer, NewState}</c> is only allowed if
+the Diameter application in question was configured with the <seealso
 marker="diameter#application_opt">diameter:application_opt()</seealso>
 <c>{call_mutates_state, true}</c>.
 Otherwise, the <c>State</c> argument is always
@@ -360,7 +391,7 @@ ignored.</p>
 <p>
 A returned <c>PostF</c> will be evaluated on any encoded
 <c>#diameter_packet{}</c> prior to transmission, the <c>bin</c> field
-of this record containing the encoded binary.
+containing the encoded binary.
 The return value is ignored.</p>
 
 <p>
@@ -395,8 +426,9 @@ Invoked to return a request for encoding and retransmission.
 Has the same role as <seealso
 marker="#prepare_request">prepare_request/3</seealso> in the case that
 a peer connection is lost an an alternate peer selected but the
-argument <seealso marker="#packet">packet()</seealso> is as returned by the initial
-<c>prepare_request/3</c>.</p>
+argument <seealso marker="#packet">packet()</seealso> is as returned
+by the initial <seealso
+marker="#prepare_request">prepare_request/3</seealso>.</p>
 
 <p>
 Returning <c>{discard, Reason}</c> causes the request to be aborted
@@ -423,40 +455,41 @@ discarded}</c>.</p>
 <desc>
 <p>
 Invoked when an answer message is received from a peer.
-The return value is returned from the call to <seealso
-marker="diameter#call">diameter:call/4</seealso> for which the
-callback takes place unless the <c>detach</c> option was
-specified.</p>
+The return value is returned from <seealso
+marker="diameter#call">diameter:call/4</seealso> unless the
+<c>detach</c> option was specified.</p>
 
 <p>
-The decoded answer record is in the <c>msg</c> field of the argument
-<seealso marker="#packet">packet()</seealso>,
-the undecoded binary in the <c>packet</c> field.
+The decoded answer record and undecoded binary are in the <c>msg</c>
+and <c>bin</c> fields of the argument
+<seealso marker="#packet">packet()</seealso> respectively.
 <c>Request</c> is the outgoing request message as was returned from
 <seealso marker="#prepare_request">prepare_request/3</seealso> or
-<seealso marker="#prepare_retransmit">prepare_retransmit/3</seealso>
-before the request was passed to the transport.</p>
+<seealso
+    marker="#prepare_retransmit">prepare_retransmit/3</seealso>.</p>
 
 <p>
 For any given call to <seealso
 marker="diameter#call">diameter:call/4</seealso> there is at most one
-call to the handle_answer callback of the application in question: any
+<seealso marker="#handle_answer">handle_answer/4</seealso> callback: any
 duplicate answer (due to retransmission or otherwise) is discarded.
-Similarly, only one of <c>handle_answer/4</c> or <c>handle_error/4</c> is
-called for any given request.</p>
+Similarly, only one of <seealso
+marker="#handle_answer">handle_answer/4</seealso> or
+<seealso marker="#handle_error">handle_error/4</seealso> is 
+called.</p>
 
 <p>
 By default, an incoming answer message that cannot be successfully
-decoded causes the request process in question to fail, causing the
-relevant call to <seealso
-marker="diameter#call">diameter:call/4</seealso>
-to return <c>{error, failure} (unless the <c>detach</c> option was
-specified)</c>.
-In particular, there is no <c>handle_error/4</c> callback in this
+decoded causes the request process to fail, causing
+<seealso marker="diameter#call">diameter:call/4</seealso>
+to return <c>{error, failure}</c> unless the <c>detach</c> option was
+specified.
+In particular, there is no <seealso
+marker="#handle_error">handle_error/4</seealso> callback in this
 case.
-Application configuration may change this behaviour as described for
-<seealso
-marker="diameter#start_service">diameter:start_service/2</seealso>.</p>
+The <seealso
+marker="diameter#application_opt">diameter:application_opt()</seealso>
+<c>answer_errors</c> can be set to change this behaviour.</p>
 
 <marker id="handle_error"/>
 </desc>
@@ -474,21 +507,20 @@ marker="diameter#start_service">diameter:start_service/2</seealso>.</p>
 </type>
 <desc>
 <p>
-Invoked when an error occurs before an answer message is received from
-a peer in response to an outgoing request.
-The return value is returned from the call to <seealso
-marker="diameter#call">diameter:call/4</seealso> for which the
-callback takes place (unless the <c>detach</c> option was
-specified).</p>
+Invoked when an error occurs before an answer message is received
+in response to an outgoing request.
+The return value is returned from <seealso
+marker="diameter#call">diameter:call/4</seealso> unless the
+<c>detach</c> option was specified.</p>
 
 <p>
 Reason <c>timeout</c> indicates that an answer message has not been
-received within the required time.
+received within the time specified with the corresponding <seealso
+marker="diameter#call_opt">diameter:call_opt()</seealso>.
 Reason <c>failover</c> indicates
 that the transport connection to the peer to which the request has
-been sent has been lost but that not alternate node was available,
-possibly because a <seealso marker="#pick_peer">pick_peer/4</seealso>
-callback returned false.</p>
+been sent has become unavailable and that not alternate peer was
+not selected.</p>
 
 <marker id="handle_request"/>
 </desc>
@@ -504,8 +536,7 @@ callback returned false.</p>
 <v>Action  = Reply
            | {relay, [Opt]}
            | discard
-           | {eval, Action, PostF}
-           | {eval_packet, Action, PostF}</v>
+           | {eval|eval_packet, Action, PostF}</v>
 <v>Reply   = {reply, <seealso marker="#message">message()</seealso>}
            | {protocol_error, 3000..3999}</v>
 <v>Opt     = <seealso marker="diameter#call_opt">diameter:call_opt()</seealso></v>
@@ -624,7 +655,8 @@ causes the request to be answered with 3002 (DIAMETER_UNABLE_TO_DELIVER).</p>
 <tag><c>discard</c></tag>
 <item>
 <p>
-Discard the request.</p>
+Discard the request.
+No answer message is sent to the peer.</p>
 </item>
 
 <tag><c>{eval, Action, PostF}</c></tag>
@@ -640,7 +672,7 @@ The return value is ignored.</p>
 <p>
 Like <c>eval</c> but evaluate <c>PostF</c> on any encoded
 <c>#diameter_packet{}</c> prior to transmission, the <c>bin</c> field
-of this record containing the encoded binary.
+containing the encoded binary.
 The return value is ignored.</p>
 </item>