Update extensions/Channel_Interface_Tube.xml

1 files changed, 19 insertions, 11 deletions

diff --git a/extensions/Channel_Interface_Tube.xml b/extensions/Channel_Interface_Tube.xml
index d3c4e661..bea58d44 100644
--- a/extensions/Channel_Interface_Tube.xml
+++ b/extensions/Channel_Interface_Tube.xml
@@ -21,16 +21,23 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       tp:causes-havoc="experimental">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>A "tube" is a mechanism for arbitrary data transfer. A tube channel
-        can contain only one tube. This interface contains the properties,
-        signals and methods common to all types of tubes. One cannot create a
-        tube channel of type org.freedesktop.Telepathy.Channel.Interface.Tube
-        but only channels of a specific type tube channel. Only stream and
-        D-Bus tubes exist currently. They have their own interface and their
-        interface can be used to create a tube channel.</p>
+      <p>A <i>tube</i> is a mechanism for arbitrary data transfer between
+      two or more IM users, used to allow applications on the users'
+      systems to communicate without having to establish network
+      connections themselves. Currently, two types of tube exist:
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+      >Channel.Type.DBusTube</tp:dbus-ref> and
+      <tp:dbus-ref namespace="org.freedesktop.Telepathy"
+      >Channel.Type.StreamTube</tp:dbus-ref>. This interface contains
+      the properties, signals and methods common to both types of tube;
+      you can only create channels of a specific tube type, not of this
+      type. A tube channel contains exactly one tube; if you need several
+      tubes, you have to create several tube channels.</p>
 
-      <p>The Tubes channel type may be requested for handles of type
-        HANDLE_TYPE_CONTACT and HANDLE_TYPE_ROOM.</p>
+      <p>Tube channels can be requested for handles of type
+      HANDLE_TYPE_CONTACT (for 1-1 communication) or of type
+      HANDLE_TYPE_ROOM (to communicate with others in the room
+      simultaneously).</p>
     </tp:docstring>
 
     <property name="Initiator" type="u" tp:type="Contact_Handle" access="read"
@@ -52,8 +59,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           must support the value being a string (D-Bus type 's'), array of bytes
           (D-Bus type 'ay'), unsigned integer (D-Bus type 'u'), integer (D-Bus
           type 'i') and boolean (D-Bus type 'b').</p>
-        <p>When the tube is offered, the parameters are transmitted to the
-          other end.</p>
+        <p>When the tube is offered, the parameters are transmitted with the
+          offer and appear as a property of the incoming tube for other
+          participants.</p>
         <p>Example of valid parameters:
           <code>{'game name': 'go', 'board size': 19}</code></p>
         <p>When requesting a channel with