[telepathy-spec/master] Approver: improve text based on my "Semantics of the ChannelDispatcher" mail to the list

[Simon McVittie]

---
 spec/Client_Approver.xml |   55 ++++++++++++++++++++++++++++++++-------------
 1 files changed, 39 insertions(+), 16 deletions(-)

diff --git a/spec/Client_Approver.xml b/spec/Client_Approver.xml
index 8725c81..9cb3a4a 100644
--- a/spec/Client_Approver.xml
+++ b/spec/Client_Approver.xml
@@ -27,14 +27,23 @@
     <tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>Approvers notify the user that new channels have been created,
-        and allow the user to accept or reject those channels.</p>
-
-      <p>They can also select which channel handler will be used for the
+      <p>Approvers are clients that notify the user that new channels have
+        been created by a contact, and allow the user to accept or reject
+        those channels. The new channels are represented by a <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT</tp:dbus-ref>
+        object, which is passed to the
+        <tp:member-ref>AddDispatchOperation</tp:member-ref> method.</p>
+
+      <tp:rationale>
+        <p>For instance, Empathy's tray icon, or the answer/reject window
+          seen when a Maemo device receives a VoIP call, should be
+          Approvers.</p>
+      </tp:rationale>
+
+      <p>Approvers can also select which channel handler will be used for the
         channel, for instance by offering the user a list of possible
-        handlers rather than just an accept/reject choice.</p>
-
-      <p>However, the Channel Dispatcher must be able to prioritize
+        handlers rather than just an accept/reject choice.
+        However, the Channel Dispatcher must be able to prioritize
         possible handlers on its own using some reasonable heuristic,
         probably based on user configuration.</p>
 
@@ -49,12 +58,22 @@
         window and highlights contacts there, and one that is part
         of a full-screen media player.</p>
 
-      <p>Any approver can approve the handling of a channel with a
-        particular channel handler. Approvers can also request that the
-        channel is rejected. The first approver to reply gets its decision
-        acted on; any other approvers that reply at the same time will
-        get a D-Bus error, indicating that the channel has already been
-        dealt with.</p>
+      <p>Any approver can approve the handling of a channel dispatch operation
+        with a particular channel handler by calling the <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">HandleWith</tp:dbus-ref>
+        method. Approvers can also attempt to <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Claim</tp:dbus-ref>
+        channels; if this succeeds, the approver may handle the channels
+        itself (if it is also a Handler), or close the channels in order to
+        reject them.</p>
+
+      <p>At the D-Bus level, there is no "reject" operation: approvers wishing
+        to reject channels SHOULD call the Claim method, then (if it succeeds)
+        close the channels in any way they see fit.</p>
+
+      <p>The first approver to reply gets its decision acted on; any other
+        approvers that reply at approximately the same time will get a D-Bus
+        error, indicating that the channel has already been dealt with.</p>
 
       <p>Approvers should usually prompt the user and ask for
         confirmation, rather than dispatching the channel to a handler
@@ -92,15 +111,19 @@
           operations already exist.</p>
 
         <p>The channel dispatcher SHOULD call this method on all approvers
-          at the same time. If no approvers return from this method
+          at the same time. If an approver returns an error from this method,
+          the approver is assumed to be faulty.</p>
+
+        <p>If no approvers return from this method
           successfully (including situations where there are no matching
           approvers at all), the channel dispatcher SHOULD consider this
           to be an error, and recover by dispatching the channel to the
           most preferred handler.</p>
 
         <tp:rationale>
-          Processes that aren't approvers shouldn't be making connections
-          anyway - there should always be at least one approver running.
+          Processes that aren't approvers (or don't at least ensure that there
+          is some approver) probably shouldn't be making connections
+          anyway, so there should always be at least one approver running.
         </tp:rationale>
       </tp:docstring>
 
-- 
1.5.6.5