[Telepathy-commits] [telepathy-doc/master] More on ensuring channels

[Davyd Madeley]

---
 docs/book/C/channel.xml                         |   42 +++++++++++++++++++----
 docs/examples/python_iface_messaging/example.py |    2 +
 2 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/docs/book/C/channel.xml b/docs/book/C/channel.xml
index b283d80..46edc79 100644
--- a/docs/book/C/channel.xml
+++ b/docs/book/C/channel.xml
@@ -220,13 +220,6 @@
      </tgroup>
     </informaltable>
 
-    <para>
-     Telepathy-glib provides the
-     <ulink url="&url_telepathy_glib_base;connection-requests.html#tp-cli-connection-interface-requests-call-create-channel"><function>tp_cli_connection_interface_requests_call_create_channel()</function></ulink>
-     and <ulink url="&url_telepathy_glib_base;connection-requests.html#tp-cli-connection-interface-requests-call-ensure-channel"><function>tp_cli_connection_interface_requests_call_ensure_channel()</function></ulink>
-     functions for this purpose.
-    </para>
-
    <warning>
     <title>RequestChannel</title>
     <para>
@@ -269,6 +262,41 @@
     </para>
    </warning>
 
+   <sect2 id="sec.channel.requesting.python">
+    <title>telepathy-python</title>
+
+    <para>
+      telepathy-python provides the
+      <classname>telepathy.client.Channel</classname> class as a D-Bus proxy
+      object. To construct this proxy you need to pass the connection's
+      D-Bus service name and the path to the channel object.
+    </para>
+
+    <para>
+     <classname>telepathy.client.Channel</classname> can be inherited like
+     any other Python class, so that you can pass around all of the methods
+     and state relating to that channel as one object. This is shown in
+     <xref linkend="ex.channel.requesting.python.class"/>.
+    </para>
+
+    <example id="ex.channel.requesting.python.class"
+             file="python_iface_messaging/example.py">
+     <title>Inheriting telepathy.client.Channel</title>
+    </example>
+   </sect2>
+   
+   <sect2 id="sect.channel.requesting.glib">
+    <title>telepathy-glib</title>
+    
+    <para>
+     Telepathy-glib provides the
+     <ulink url="&url_telepathy_glib_base;connection-requests.html#tp-cli-connection-interface-requests-call-create-channel"><function>tp_cli_connection_interface_requests_call_create_channel()</function></ulink>
+     and <ulink url="&url_telepathy_glib_base;connection-requests.html#tp-cli-connection-interface-requests-call-ensure-channel"><function>tp_cli_connection_interface_requests_call_ensure_channel()</function></ulink>
+     functions for this purpose.
+    </para>
+
+   </sect2>
+
   </sect1>
 
   <sect1 id="sect-channel-contactlist">
diff --git a/docs/examples/python_iface_messaging/example.py b/docs/examples/python_iface_messaging/example.py
index 8d1022d..5563964 100755
--- a/docs/examples/python_iface_messaging/example.py
+++ b/docs/examples/python_iface_messaging/example.py
@@ -21,12 +21,14 @@ from telepathy.constants import CONNECTION_STATUS_CONNECTED, \
 
 DBUS_PROPERTIES = 'org.freedesktop.DBus.Properties'
 
+# begin ex.channel.requesting.python.class
 class TextChannel (telepathy.client.Channel):
     def __init__ (self, parent, channel_path):
         self.parent = parent
         conn = parent.conn
 
         super (TextChannel, self).__init__ (conn.service_name, channel_path)
+        # end ex.channel.requesting.python.class
         channel = self
 
         channel[DBUS_PROPERTIES].Get(CHANNEL, 'Interfaces',
-- 
1.5.6.5