[gtk+/open-with-dialog: 60/65] app-chooser: update docs

[Cosimo Cecchi <cosimoc src gnome org>]

commit d8ef15c592c680d1b0060238e44be717c93dcad0
Author: Cosimo Cecchi <cosimoc gnome org>
Date:   Tue Nov 30 15:03:33 2010 +0100

    app-chooser: update docs

 gtk/gtkappchooser.c       |   20 ++++++++++++++++++--
 gtk/gtkappchooserbutton.c |    9 +++++++++
 gtk/gtkappchooserdialog.c |    9 ++++++++-
 gtk/gtkappchooserwidget.c |   28 ++++++++++++++++++++++++++++
 4 files changed, 63 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtkappchooser.c b/gtk/gtkappchooser.c
index 1e8843a..cb630c3 100644
--- a/gtk/gtkappchooser.c
+++ b/gtk/gtkappchooser.c
@@ -38,6 +38,11 @@ gtk_app_chooser_default_init (GtkAppChooserIface *iface)
 {
   GParamSpec *pspec;
 
+  /**
+   * GtkAppChooser:content-type:
+   *
+   * The content type of the #GtkAppChooser object.
+   */
   pspec = g_param_spec_string ("content-type",
                                P_("Content type"),
                                P_("The content type used by the open with object"),
@@ -47,6 +52,17 @@ gtk_app_chooser_default_init (GtkAppChooserIface *iface)
   g_object_interface_install_property (iface, pspec);
 }
 
+
+/**
+ * gtk_app_chooser_get_content_type:
+ * @self: a #GtkAppChooser
+ *
+ * Returns the current value of the #GtkAppChooser:content-type property.
+ *
+ * Returns: the content type of @self. Free with g_free()
+ *
+ * Since: 3.0
+ */
 gchar *
 gtk_app_chooser_get_content_type (GtkAppChooser *self)
 {
@@ -68,7 +84,7 @@ gtk_app_chooser_get_content_type (GtkAppChooser *self)
  * Returns the currently selected application.
  *
  * Returns: (transfer full): a #GAppInfo for the currently selected
- *     application, or %NULL if none is selected. Free with g_object_unref().
+ *     application, or %NULL if none is selected. Free with g_object_unref()
  *
  * Since: 3.0
  */
@@ -82,7 +98,7 @@ gtk_app_chooser_get_app_info (GtkAppChooser *self)
  * gtk_app_chooser_refresh:
  * @self: a #GtkAppChooser
  *
- * Reload the list of applications.
+ * Reloads the list of applications.
  *
  * Since: 3.0
  */
diff --git a/gtk/gtkappchooserbutton.c b/gtk/gtkappchooserbutton.c
index cccd760..d95d435 100644
--- a/gtk/gtkappchooserbutton.c
+++ b/gtk/gtkappchooserbutton.c
@@ -523,6 +523,15 @@ gtk_app_chooser_button_class_init (GtkAppChooserButtonClass *klass)
                           G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS);
   g_object_class_install_property (oclass, PROP_SHOW_DIALOG_ITEM, pspec);
 
+  /**
+   * GtkAppChooserButton::custom-item-activated:
+   * @self: the object which received the signal
+   * @item_name: the name of the activated item
+   *
+   * Emitted when a custom item, previously added with
+   * gtk_app_chooser_button_append_custom_item(), is activated from the
+   * dropdown menu.
+   */
   signals[SIGNAL_CUSTOM_ITEM_ACTIVATED] =
     g_signal_new ("custom-item-activated",
                   GTK_TYPE_APP_CHOOSER_BUTTON,
diff --git a/gtk/gtkappchooserdialog.c b/gtk/gtkappchooserdialog.c
index 73dc7a2..1c453ab 100644
--- a/gtk/gtkappchooserdialog.c
+++ b/gtk/gtkappchooserdialog.c
@@ -660,9 +660,16 @@ gtk_app_chooser_dialog_class_init (GtkAppChooserDialogClass *klass)
 
   g_object_class_override_property (gobject_class, PROP_CONTENT_TYPE, "content-type");
 
+  /**
+   * GtkAppChooserDialog:gfile:
+   *
+   * The GFile used by the #GtkAppChooserDialog.
+   * The dialog's #GtkAppChooserWidget content type will be guessed from the
+   * file, if present.
+   */
   pspec = g_param_spec_object ("gfile",
                                P_("GFile"),
-                               P_("The GFile used by the open with dialog"),
+                               P_("The GFile used by the app chooser dialog"),
                                G_TYPE_FILE,
                                G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE |
                                G_PARAM_STATIC_STRINGS);
diff --git a/gtk/gtkappchooserwidget.c b/gtk/gtkappchooserwidget.c
index d8c15f7..b73638c 100644
--- a/gtk/gtkappchooserwidget.c
+++ b/gtk/gtkappchooserwidget.c
@@ -1069,6 +1069,13 @@ gtk_app_chooser_widget_class_init (GtkAppChooserWidgetClass *klass)
                                G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
   g_object_class_install_property (gobject_class, PROP_DEFAULT_TEXT, pspec);
 
+  /**
+   * GtkAppChooserWidget::application-selected:
+   * @self: the object which received the signal
+   * @application: the selected #GAppInfo
+   *
+   * Emitted when an application item is selected from the widget's list.
+   */
   signals[SIGNAL_APPLICATION_SELECTED] =
     g_signal_new ("application-selected",
                   GTK_TYPE_APP_CHOOSER_WIDGET,
@@ -1079,6 +1086,16 @@ gtk_app_chooser_widget_class_init (GtkAppChooserWidgetClass *klass)
                   G_TYPE_NONE,
                   1, G_TYPE_APP_INFO);
 
+  /**
+   * GtkAppChooserWidget::application-activated:
+   * @self: the object which received the signal
+   * @application: the activated #GAppInfo
+   *
+   * Emitted when an application item is activated from the widget's list.
+   * This usually happens when the user double clicks an item, or an item
+   * is selected and the user presses one of the keys Space, Shift+Space,
+   * Return or Enter.
+   */
   signals[SIGNAL_APPLICATION_ACTIVATED] =
     g_signal_new ("application-activated",
                   GTK_TYPE_APP_CHOOSER_WIDGET,
@@ -1089,6 +1106,17 @@ gtk_app_chooser_widget_class_init (GtkAppChooserWidgetClass *klass)
                   G_TYPE_NONE,
                   1, G_TYPE_APP_INFO);
 
+  /**
+   * GtkAppChooserWidget::populate-popup:
+   * @self: the object which received the signal
+   * @menu: the #GtkMenu to populate
+   * @application: the current #GAppInfo
+   *
+   * Emitted when a context menu is about to popup over an application item.
+   * Clients can insert menu items into the provided #GtkMenu object in the
+   * callback of this signal; the context menu will be shown over the item if
+   * at least one item has been added to the menu.
+   */
   signals[SIGNAL_POPULATE_POPUP] =
     g_signal_new ("populate-popup",
                   GTK_TYPE_APP_CHOOSER_WIDGET,