[telepathy-glib/master] Added an example of using tp_debug_sender_log_handler.

[Jonny Lamb]

Signed-off-by: Jonny Lamb <jonny.lamb at collabora.co.uk>
---
 telepathy-glib/debug-sender.c |   22 +++++++++++++++++++++-
 1 files changed, 21 insertions(+), 1 deletions(-)

diff --git a/telepathy-glib/debug-sender.c b/telepathy-glib/debug-sender.c
index 81b5f3e..5552482 100644
--- a/telepathy-glib/debug-sender.c
+++ b/telepathy-glib/debug-sender.c
@@ -416,12 +416,32 @@ tp_debug_sender_add_message (TpDebugSender *self,
  * sending every message to the #TpDebugSender. Note that every message,
  * regardless of domain, is given to g_log_default_hander().
  *
- * An example of its usage follows:
+ * Note that a ref to a #TpDebugSender must be kept at all times otherwise
+ * no messages given to the handler will be sent to the Telepathy debug
+ * interface.
+ *
+ * An example of its usage, taking in mind the notes above, follows:
  * |[
+ * // Create a main loop and debug sender
+ * GMainLoop *loop = g_main_loop_new (NULL, FALSE);
  * TpDebugSender *sender = tp_debug_sender_dup ();
+ *
+ * // Set the default handler
  * g_log_set_default_handler (tp_debug_sender_log_handler, G_LOG_DOMAIN);
+ *
+ * // Run the main loop, but keeping a ref on the TpDebugSender from
+ * // the beginning of this code sample.
+ * g_main_loop_run (loop);
+ *
+ * // g_main_loop_quit was called, so only now can we clean up the
+ * // TpDebugSender.
+ * g_object_unref (sender);
  * ]|
  *
+ * This function is merely for convenience if it meets the requirements.
+ * It can easily be re-implemented in services, and does not need to be
+ * used.
+ *
  * Since: 0.7.UNRELEASED
  */
 void
-- 
1.5.6.5