From 5a5b1d91c8cc913c6d049e113ceedc4746d2ba8e Mon Sep 17 00:00:00 2001
From: Anders Svensson <anders@erlang.org>
Date: Wed, 11 Jul 2012 02:29:45 +0200
Subject: Clarify documentation on application state

---
 lib/diameter/doc/src/diameter_app.xml | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml
index a9ae0ebbec..a786443fa1 100644
--- a/lib/diameter/doc/src/diameter_app.xml
+++ b/lib/diameter/doc/src/diameter_app.xml
@@ -257,12 +257,8 @@ call to <seealso marker="#peer_up">peer_up/3</seealso>.</p>
 <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.
-A new application state can also be returned but only if the Diameter
-application in question was
-configured with the option <c>call_mutates_state</c> set to
-<c>true</c>, as documented for <seealso
-marker="diameter#start_service">diameter:start_service/2</seealso>.</p>
+peer for an outgoing request, the return value indicating the selected
+peer.</p>
 
 <p>
 The candidate peers list will only include those
@@ -301,6 +297,19 @@ marker="#pick_peer">pick_peer/4</seealso> will be, since a
 retransmission to an alternate peer is abandoned if an answer is
 received from a previously selected peer.</p>
 
+<note>
+<p>
+<c>{Peer, NewState}</c> and its equivalents can only be returned if
+the Diameter application in question was
+configured with the option <c>{call_mutates_state, true}</c>,
+as documented for <seealso
+marker="diameter#start_service">diameter:start_service/2</seealso>.
+Otherwise, the <c>State</c> argument is always
+the intial value as configured on the application, not any subsequent
+value returned by a <seealso marker="#peer_up">peer_up/3</seealso>
+or <seealso marker="#peer_down">peer_down/3</seealso> callback.</p>
+</note>
+
 <marker id="prepare_request"/>
 </desc>
 
-- 
cgit v1.2.3