[Telepathy-commits] [telepathy-spec/master] ChannelRequest: explain why Proceed can't fail, unless the world has gone mad

[Simon McVittie]

---
 spec/Channel_Request.xml |   16 +++++++++++++++-
 1 files changed, 15 insertions(+), 1 deletions(-)

diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index 480f418..f1a5290 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -74,11 +74,25 @@
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Proceed with the channel request.</p>
 
+        <tp:rationale>
+          <p>The client that created this object calls this method
+            when it has connected signal handlers for
+            <tp:member-ref>Succeeded</tp:member-ref> and
+            <tp:member-ref>Failed</tp:member-ref>.</p>
+        </tp:rationale>
+
+        <p>Clients other than the client which created the ChannelRequest
+          MUST NOT call this method.</p>
+
         <p>This method SHOULD return immediately; on success, the request
           might still fail, but this will be indicated asynchronously
           by the <tp:member-ref>Failed</tp:member-ref> signal.</p>
 
-        <p>(FIXME: or do we define some errors here too?)</p>
+        <p>Proceed cannot fail, unless clients have got the life-cycle
+          of a ChannelRequest seriously wrong (e.g. a client calls this
+          method twice, or a client that did not create the ChannelRequest
+          calls this method). If it fails, clients SHOULD assume that the
+          whole ChannelRequest has become useless.</p>
       </tp:docstring>
 
       <tp:possible-errors>
-- 
1.5.6.5