[empathy] Misc. gtk-doc updates, including being more explicit about refs.

[Jonny Lamb <jonnylamb src gnome org>]

commit 56beb181035248b4aff6927b3397708755ce6588
Author: Jonny Lamb <jonny lamb collabora co uk>
Date:   Thu Apr 23 10:03:06 2009 +0100

    Misc. gtk-doc updates, including being more explicit about refs.
    
    Signed-off-by: Jonny Lamb <jonny lamb collabora co uk>
---
 libempathy-gtk/empathy-account-chooser.c  |    9 ++++++---
 libempathy-gtk/empathy-contact-selector.c |    4 ++--
 libempathy-gtk/empathy-contact-widget.h   |    4 ++--
 libempathy-gtk/empathy-profile-chooser.c  |    3 ++-
 4 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/libempathy-gtk/empathy-account-chooser.c b/libempathy-gtk/empathy-account-chooser.c
index aa6cf29..5d11e8e 100644
--- a/libempathy-gtk/empathy-account-chooser.c
+++ b/libempathy-gtk/empathy-account-chooser.c
@@ -254,7 +254,7 @@ empathy_account_chooser_new (void)
  *
  * Returns the account which is currently selected in the chooser or %NULL
  * if there is no account selected. The #McAccount returned should be
- * unrefed when finished with.
+ * unrefed with g_object_unref() when finished with.
  *
  * Return value: a new ref to the #McAccount currently selected, or %NULL.
  */
@@ -284,9 +284,12 @@ empathy_account_chooser_dup_account (EmpathyAccountChooser *chooser)
  * empathy_account_chooser_get_connection:
  * @chooser: an #EmpathyAccountChooser
  *
- * Returns the #TpConnection associated with the account currently selected.
+ * Returns a borrowed reference to the #TpConnection associated with the
+ * account currently selected. The caller must reference the returned object with
+ * g_object_ref() if it will be kept
  *
- * Return value: the #TpConnection associated with the account curently selected.
+ * Return value: a borrowed reference to the #TpConnection associated with the
+ * account curently selected.
  */
 TpConnection *
 empathy_account_chooser_get_connection (EmpathyAccountChooser *chooser)
diff --git a/libempathy-gtk/empathy-contact-selector.c b/libempathy-gtk/empathy-contact-selector.c
index a51d8d3..f4a302c 100644
--- a/libempathy-gtk/empathy-contact-selector.c
+++ b/libempathy-gtk/empathy-contact-selector.c
@@ -372,8 +372,8 @@ empathy_contact_selector_new (EmpathyContactList *contact_list)
  * @selector: An #EmpathyContactSelector
  *
  * Returns a new reference to the contact which is currently selected in
- * @selector, or %NULL if there is no contact selected. The contact should
- * be unrefed with g_object_unref() when finished with.
+ * @selector, or %NULL if there is no contact selected. The returned contact
+ * should be unrefed with g_object_unref() when finished with.
  *
  * Return value: A new reference to the contact currently selected, or %NULL
  */
diff --git a/libempathy-gtk/empathy-contact-widget.h b/libempathy-gtk/empathy-contact-widget.h
index db739ad..0da5580 100644
--- a/libempathy-gtk/empathy-contact-widget.h
+++ b/libempathy-gtk/empathy-contact-widget.h
@@ -47,8 +47,8 @@ G_BEGIN_DECLS
  * @EMPATHY_CONTACT_WIDGET_FOR_TOOLTIP: Make widgets more designed for a tooltip.
  *  For example, make widgets not selectable.
  *
- * Options to instruct the #EmpathyContactWidget what features should be
- * enabled.
+ * Flags used when creating an #EmpathyContactWidget to specify which features
+ * should be available.
  */
 typedef enum
 {
diff --git a/libempathy-gtk/empathy-profile-chooser.c b/libempathy-gtk/empathy-profile-chooser.c
index 4959561..10eb379 100644
--- a/libempathy-gtk/empathy-profile-chooser.c
+++ b/libempathy-gtk/empathy-profile-chooser.c
@@ -51,7 +51,8 @@ enum {
  * empathy_profile_chooser_dup_selected:
  * @widget: an #EmpathyProfileChooser
  *
- * Returns a new reference to the selected #McProfile in @widget.
+ * Returns a new reference to the selected #McProfile in @widget. The returned
+ * #McProfile should be unrefed with g_object_unref() when finished with.
  *
  * Return value: a new reference to the selected #McProfile
  */