[telepathy-doc/master] More on D-Bus method implementation

[Davyd Madeley]

---
 docs/book/C/services.xml                           |   19 +++++++++++++++++++
 docs/examples/glib_mc5_observer/example-observer.c |    2 ++
 2 files changed, 21 insertions(+), 0 deletions(-)

diff --git a/docs/book/C/services.xml b/docs/book/C/services.xml
index 1307a78..7b1bb1f 100644
--- a/docs/book/C/services.xml
+++ b/docs/book/C/services.xml
@@ -110,6 +110,8 @@
      <function>tp_svc_client_observer_observe_channels_impl</function>.
      This is shown in
      <xref linkend="ex.services.glib.iface.long-iface-init"/>.
+     <xref linkend="ex.services.glib.iface.method"/> shows the corresponding
+     method implementation.
     </para>
 
     <example id="ex.services.glib.iface.long-iface-init">
@@ -140,6 +142,23 @@ observer_iface_init (gpointer g_iface, gpointer iface_data)
      </example>
     </tip>
 
+    <example id="ex.services.glib.iface.method"
+             file="glib_mc5_observer/example-observer.c">
+     <title>Method Implementation for ObserveChannels</title>
+    </example>
+
+    <para>
+     Method implementations may be either synchronous or asynchronous as you
+     desire, however while your mainloop is blocked in a method call your
+     service will be unable to handle any other incoming method calls
+     (or other mainloop events, such as a client UI). When you are ready to
+     return from the method call, call the appropriate
+     <literal>return_from</literal> function, which will be of the form
+     <literal>tp_svc_interface_name_return_from_method_name</literal>, e.g.
+     <literal>tp_svc_client_observer_return_from_observe_channels</literal>
+     (<xref linkend="ex.services.glib.iface.method"/>).
+    </para>
+
    </sect2>
 
   </sect1>
diff --git a/docs/examples/glib_mc5_observer/example-observer.c b/docs/examples/glib_mc5_observer/example-observer.c
index b47ef31..7ee5524 100644
--- a/docs/examples/glib_mc5_observer/example-observer.c
+++ b/docs/examples/glib_mc5_observer/example-observer.c
@@ -36,6 +36,7 @@ enum
 // {
 // };
 
+/* begin ex.services.glib.iface.method */
 static void
 example_observer_observe_channels (TpSvcClientObserver   *self,
                                    const char            *account,
@@ -65,6 +66,7 @@ example_observer_observe_channels (TpSvcClientObserver   *self,
 
   tp_svc_client_observer_return_from_observe_channels (context);
 }
+/* end ex.services.glib.iface.method */
 
 static void
 example_observer_get_property (GObject    *self,
-- 
1.5.6.5