[Telepathy-commits] [telepathy-spec/master] ChannelDispatcher: Improve the reinstated version of the DispatchOperations property

[Simon McVittie]

---
 spec/Channel_Dispatcher.xml |   40 ++++++++++++++++++++++++++--------------
 1 files changed, 26 insertions(+), 14 deletions(-)

diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index 844ad92..e9b16c2 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -189,31 +189,41 @@
 
     </method>
 
-    <!-- FIXME: are this property and its associated change-notification
-    signals actually needed? -->
     <property name="DispatchOperations" type="ao" access="read">
-      <tp:docstring>
-        The list of ChannelDispatchOperation objects currently being
-        processed. Change notification is via the NewDispatch and
-        DispatchFinished signals.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The list of ChannelDispatchOperation objects currently being
+          processed. Change notification is via the NewDispatch and
+          DispatchFinished signals.</p>
+
+        <p>(FIXME: include some/all properties, like the channels?)</p>
+
+        <tp:rationale>
+          <p>The existence of this property allows a newly started approver
+            to pick up existing dispatch operations.</p>
+        </tp:rationale>
       </tp:docstring>
     </property>
 
     <signal name="NewDispatchOperation">
-      <arg name="Dispatch_Operation" type="o">
-      </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when a dispatch operation is added to
+          <tp:member-ref>DispatchOperations</tp:member-ref>.</p>
 
-      <!-- FIXME: copy the Channel_Announcement_Flags from
-      Connection.Interface.Requests? -->
+        <p>(FIXME: include some/all properties, like the channels?)</p>
+      </tp:docstring>
 
-      <arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]">
+      <arg name="Dispatch_Operation" type="o">
+        <tp:docstring>
+          The dispatch operation that was created.
+        </tp:docstring>
       </arg>
     </signal>
 
     <signal name="DispatchOperationClosed">
-      <tp:docstring>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         Emitted when a dispatch operation finishes (i.e. exactly once per
-        emission of ChannelDispatchOperation.Close).
+        emission of <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT.Closed</tp:dbus-ref>).
 
         <tp:rationale>
           Strictly speaking this is redundant with
@@ -223,7 +233,9 @@
       </tp:docstring>
 
       <arg name="Dispatch_Operation" type="o">
-        The dispatch operation that was closed.
+        <tp:docstring>
+          The dispatch operation that was closed.
+        </tp:docstring>
       </arg>
     </signal>
 
-- 
1.5.6.5