[Telepathy-commits] [telepathy-doc/master] Add some examples

[Davyd Madeley]

---
 docs/book/C/channel.xml                         |   26 ++++++++++++++++++++++-
 docs/examples/python_simple_presence/example.py |    4 +++
 2 files changed, 29 insertions(+), 1 deletions(-)

diff --git a/docs/book/C/channel.xml b/docs/book/C/channel.xml
index cb98a1f..fadbfb6 100644
--- a/docs/book/C/channel.xml
+++ b/docs/book/C/channel.xml
@@ -295,7 +295,7 @@
     </para>
 
     <para>
-     Two request a contact list, 3 properties must be provided to
+     To request a contact list, 3 properties must be provided to
      <methodname>EnsureChannel</methodname>
      (see <xref linkend="sec-channel-requesting"/>): the channel type
      (org.freedesktop.Telepathy.Channel.Type.ContactList), the target handle
@@ -303,6 +303,8 @@
      <type>Handle_Type_Group</type>) and
      either a target handle retrieved by
      <methodname>RequestHandles</methodname> or the ID.
+     <xref linkend="ex.channel.contactlist.ensurechannel"/> shows a code
+     example.
     </para>
   
     <example id="example.channel.contactlist.examplemaps">
@@ -364,6 +366,11 @@
       </tgroup>
      </informaltable>
     </example>
+    
+    <example id="ex.channel.contactlist.ensurechannel"
+             file="python_simple_presence/example.py">
+     <title>Setting Up a Channel for a ContactList</title>
+    </example>
 
     <para>
      Gaining access to the contacts listed in a contact list is actually
@@ -497,6 +504,23 @@
      Telepathy this. Therefore, client applications should track this
      information if necessary.
     </para></note>
+
+    <para>
+     Information about a list of contacts can be looked up using the
+     connection's <interfacename>Contacts</interfacename> interface. This
+     is documented in <xref linkend="sect.connection.contacts"/>.
+    </para>
+
+    <para>
+     <xref linkend="ex.channel.groups.getting-members"/> shows how to
+     retrieve a list of handles for current members of a group (in this case
+     a contact list).
+    </para>
+
+    <example id="ex.channel.groups.getting-members"
+             file="python_simple_presence/example.py">
+     <title>Retrieving the Members of a Group</title>
+    </example>
   
   </sect1>
   
diff --git a/docs/examples/python_simple_presence/example.py b/docs/examples/python_simple_presence/example.py
index 7867907..2d2c117 100755
--- a/docs/examples/python_simple_presence/example.py
+++ b/docs/examples/python_simple_presence/example.py
@@ -105,6 +105,7 @@ class Example (object):
                 channel = telepathy.client.Channel(conn.service_name, path)
                 self.channel = channel
 
+                # begin ex.channel.groups.getting-members
                 # request the list of members
                 channel[DBUS_PROPERTIES].Get(CHANNEL_INTERFACE_GROUP,
                                          'Members',
@@ -123,6 +124,7 @@ class Example (object):
                     False,
                     reply_handler = self.get_contact_attributes_cb,
                     error_handler = self.parent.error_cb)
+                # end ex.channel.groups.getting-members
 
             def get_contact_attributes_cb (self, attributes):
                 print '-' * 78
@@ -140,6 +142,7 @@ class Example (object):
         # we can either use TargetID if we know a name, or TargetHandle
         # if we already have a handle
         for group in groups:
+            # begin ex.channel.contactlist.ensurechannel
             print "Ensuring channel to %s..." % group
             conn[CONNECTION_INTERFACE_REQUESTS].EnsureChannel({
                 CHANNEL + '.ChannelType'     : CHANNEL_TYPE_CONTACT_LIST,
@@ -148,6 +151,7 @@ class Example (object):
                 },
                 reply_handler = ensure_channel_cb(self, group),
                 error_handler = no_channel_available)
+            # end ex.channel.contactlist.ensurechannel
 
     def get_interfaces_cb (self, interfaces):
         conn = self.conn
-- 
1.5.6.5