Add documentation for EmpathyContactWidget.

Signed-off-by: Jonny Lamb <jonny.lamb@collabora.co.uk>

2 files changed, 73 insertions, 0 deletions

diff --git a/libempathy-gtk/empathy-contact-widget.c b/libempathy-gtk/empathy-contact-widget.c
index fc64d15c6..c78aafeaa 100644
--- a/libempathy-gtk/empathy-contact-widget.c
+++ b/libempathy-gtk/empathy-contact-widget.c
@@ -44,6 +44,25 @@
 #define DEBUG_FLAG EMPATHY_DEBUG_CONTACT
 #include <libempathy/empathy-debug.h>
 
+/**
+ * SECTION:empathy-contact-widget
+ * @title:EmpathyContactWidget
+ * @short_description: A widget used to display and edit details about a contact
+ * @include: libempathy-empathy-contact-widget.h
+ *
+ * #EmpathyContactWidget is a widget which displays appropriate widgets
+ * with details about a contact, also allowing changing these details,
+ * if desired.
+ */
+
+/**
+ * EmpathyContactWidget:
+ * @parent: parent object
+ *
+ * Widget which displays appropriate widgets with details about a contact,
+ * also allowing changing these details, if desired.
+ */
+
 /* Delay before updating the widget when the id entry changed (seconds) */
 #define ID_CHANGED_TIMEOUT 1
 
@@ -151,6 +170,15 @@ enum
   COL_COUNT
 };
 
+/**
+ * empathy_contact_widget_new:
+ * @contact: an #EmpathyContact
+ * @flags: #EmpathyContactWidgetFlags for the new contact widget
+ *
+ * Creates a new #EmpathyContactWidget.
+ *
+ * Return value: a new #EmpathyContactWidget
+ */
 GtkWidget *
 empathy_contact_widget_new (EmpathyContact *contact,
                             EmpathyContactWidgetFlags flags)
@@ -212,6 +240,14 @@ empathy_contact_widget_new (EmpathyContact *contact,
     information->vbox_contact_widget);
 }
 
+/**
+ * empathy_contact_widget_get_contact:
+ * @widget: an #EmpathyContactWidget
+ *
+ * Get the #EmpathyContact related with the #EmpathyContactWidget @widget.
+ *
+ * Returns: the #EmpathyContact associated with @widget
+ */
 EmpathyContact *
 empathy_contact_widget_get_contact (GtkWidget *widget)
 {
@@ -226,6 +262,13 @@ empathy_contact_widget_get_contact (GtkWidget *widget)
   return information->contact;
 }
 
+/**
+ * empathy_contact_widget_set_contact:
+ * @widget: an #EmpathyContactWidget
+ * @contact: a different #EmpathyContact
+ *
+ * Change the #EmpathyContact related with the #EmpathyContactWidget @widget.
+ */
 void
 empathy_contact_widget_set_contact (GtkWidget *widget,
                                     EmpathyContact *contact)
@@ -242,6 +285,15 @@ empathy_contact_widget_set_contact (GtkWidget *widget,
   contact_widget_set_contact (information, contact);
 }
 
+/**
+ * empathy_contact_widget_set_account_filter:
+ * @widget: an #EmpathyContactWidget
+ * @filter: a #EmpathyAccountChooserFilterFunc
+ * @user_data: user data to pass to @filter, or %NULL
+ *
+ * Set a filter on the #EmpathyAccountChooser included in the
+ * #EmpathyContactWidget.
+ */
 void
 empathy_contact_widget_set_account_filter (
     GtkWidget *widget,
diff --git a/libempathy-gtk/empathy-contact-widget.h b/libempathy-gtk/empathy-contact-widget.h
index 4ba75e17f..db739ad19 100644
--- a/libempathy-gtk/empathy-contact-widget.h
+++ b/libempathy-gtk/empathy-contact-widget.h
@@ -29,6 +29,27 @@
 
 G_BEGIN_DECLS
 
+/**
+ * EmpathyContactWidgetFlags:
+ * @EMPATHY_CONTACT_WIDGET_EDIT_NONE: Don't show any widgets to edit any details
+ *  of the contact. This should be the option for widgets that merely display
+ *  information about a contact.
+ * @EMPATHY_CONTACT_WIDGET_EDIT_ALIAS: Show a #GtkEntry allowing changes to the
+ *  contact's alias.
+ * @EMPATHY_CONTACT_WIDGET_EDIT_AVATAR: Show an #EmpathyAvatarChooser allowing
+ *  changes to the contact's avatar.
+ * @EMPATHY_CONTACT_WIDGET_EDIT_ACCOUNT: Show an #EmpathyAccountChooser allowing
+ *  changes to the contact's account.
+ * @EMPATHY_CONTACT_WIDGET_EDIT_ID: Show a #GtkEntry allowing changes to the
+ *  contact's identifier.
+ * @EMPATHY_CONTACT_WIDGET_EDIT_GROUPS: Show a widget to change the groups the
+ *  contact is in.
+ * @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.
+ */
 typedef enum
 {
   EMPATHY_CONTACT_WIDGET_EDIT_NONE    = 0,