[Telepathy-commits] [telepathy-spec/master] ChannelRequest, ChannelDispatcher: move the rationale for ChannelRequest being a separate object into StartRequest, and improve it

[Simon McVittie]

---
 spec/Channel_Dispatcher.xml |   20 ++++++++++++++++++--
 spec/Channel_Request.xml    |   12 ++----------
 2 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index 4ca7996..df36e77 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -81,8 +81,24 @@
     </property>
 
     <method name="StartRequest">
-      <tp:docstring>
-        Start a channel request.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Start a channel request. This just creates a
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">ChannelRequest.DRAFT</tp:dbus-ref>
+          object, which can be used to perform the actual request and track its
+          success or failure.</p>
+
+        <tp:rationale>
+          <p>The request can take a long time - in the worst case, the
+            channel dispatcher has to ask the account manager to put the
+            account online, the account manager has to ask the operating
+            system to obtain an Internet connection, and the operating
+            system has to ask the user whether to activate an Internet
+            connection using an on-demand mechanism like dialup.</p>
+
+          <p>This means that using a single D-Bus method call and response
+            to represent the whole request will tend to lead to that call
+            timing out, which is not the behaviour we want.</p>
+        </tp:rationale>
       </tp:docstring>
 
       <arg direction="out" name="Request" type="o">
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index 2258902..6bc48f1 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -37,16 +37,8 @@
         <p>Actually request the channels.</p>
 
         <p>This method SHOULD return immediately; on success, the request
-          might still fail, but this will be indicated asynchronously.</p>
-
-        <tp:rationale>
-          <p>The request can take a long time - in the worst case, the
-            channel dispatcher has to ask the account manager to put the
-            account online, the account manager has to ask the operating
-            system to obtain an Internet connection, and the operating
-            system has to ask the user whether to activate an Internet
-            connection using an on-demand mechanism like dialup.</p>
-          </tp:rationale>
+          might still fail, but this will be indicated asynchronously
+          by the <tp:member-ref>Failed</tp:member-ref> signal.</p>
       </tp:docstring>
 
       <arg direction="in" name="Connection" type="o">
-- 
1.5.6.5