[Telepathy-commits] [telepathy-spec/master] ChannelDispatcher: explain observer/approver/dispatcher

[Simon McVittie]

20080603111807-53eee-5efd0f160b437ad677e3063ce74d8e229513bda3.gz
---
 spec/Channel_Dispatcher.xml |   30 +++++++++++++++++++++++++++++-
 1 files changed, 29 insertions(+), 1 deletions(-)

diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index 98a7396..a654f26 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -22,7 +22,35 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
   <interface name="org.freedesktop.Telepathy.ChannelDispatcher.DRAFT"
     tp:causes-havoc="experimental">
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>...</p>
+      <p>The channel dispatcher is responsible for responding to new
+        channels and launching client processes to handle them.</p>
+
+      <p>There are three categories of client process defined by this
+        specification:</p>
+
+      <dl>
+        <dt>Observer</dt>
+        <dd><p>Observers monitor the creation of new channels. This
+            functionality can be used for things like message logging.
+            All observers are notified simultaneously, and they are not
+            given an opportunity to delay channel handling; they should not
+            alter the state of the channel.</p></dd>
+
+        <dt>Approver</dt>
+        <dd>
+          <p>Approvers notify the user that new channels have been created,
+            and also select which channel handler will be used for the channel,
+            either by asking the user or by choosing the most appropriate
+            channel handler.</p>
+        </dd>
+
+        <dt>Channel handler</dt>
+        <dd>
+          <p>Channel handlers are the eventual handler for a channel or a
+            channel bundle; a typical channel handler is a user interface
+            process handling channels of a particular type.</p>
+        </dd>
+      </dl>
     </tp:docstring>
 
     <property name="Interfaces" type="as" access="read"
-- 
1.5.6.5