[gtkmm] Gtk::AppChooser*: Improve documentation

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 334deb63a9983b234a052c3c11aa9bbe4b1c5022
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Wed Nov 13 18:23:41 2013 +0100

    Gtk::AppChooser*: Improve documentation
    
    * gtk/src/appchooser.hg:
    * gtk/src/appchooserbutton.hg:
    * gtk/src/appchooserdialog.hg:
    * gtk/src/appchooserwidget.hg: Copy class documentation from gtk+ that was
    added to gtk+ after the classes were created in gtkmm. Add links to
    giommContentType in glibmm. See gtk+ bug #650012. These links will be broken
    until a new version of glibmm (after 2.38.0) is released.

 gtk/src/appchooser.hg       |   21 ++++++++++++++++++---
 gtk/src/appchooserbutton.hg |   24 +++++++++++++++++++++---
 gtk/src/appchooserdialog.hg |    9 +++++----
 gtk/src/appchooserwidget.hg |   17 +++++++++++------
 4 files changed, 55 insertions(+), 16 deletions(-)
---
diff --git a/gtk/src/appchooser.hg b/gtk/src/appchooser.hg
index 1b6ad7f..1d4d15d 100644
--- a/gtk/src/appchooser.hg
+++ b/gtk/src/appchooser.hg
@@ -31,13 +31,28 @@ typedef struct _GtkAppChooserIface GtkAppChooserIface;
 namespace Gtk
 {
 
-//TODO: The AppChooser content-type is not documented properly: 
https://bugzilla.gnome.org/show_bug.cgi?id=650012
-
-/** This interface can be implemented by widgets which allow the user to choose
+/** Interface implemented by widgets for choosing an application.
+ *
+ * This interface can be implemented by widgets which allow the user to choose
  * an application (typically for the purpose of opening a file). The main
  * objects that implement this interface are AppChooserWidget, AppChooserDialog
  * and AppChooserButton.
  *
+ * Applications are represented by Gio::AppInfo objects here.
+ * GIO has a concept of recommended and fallback applications for a
+ * given content type. Recommended applications are those that claim
+ * to handle the content type itself, while fallback also includes
+ * applications that handle a more generic content type. GIO also
+ * knows the default and last-used application for a given content
+ * type. The AppChooserWidget provides detailed control over
+ * whether the shown list of applications should include default,
+ * recommended or fallback applications.
+ *
+ * To obtain the application that has been selected in an AppChooser,
+ * use get_app_info().
+ *
+ * See @ref giommContentType in glibmm for more information about content types.
+ *
  * @newin{3,0}
  */
 class AppChooser : public Glib::Interface
diff --git a/gtk/src/appchooserbutton.hg b/gtk/src/appchooserbutton.hg
index 8b888f7..d6a5085 100644
--- a/gtk/src/appchooserbutton.hg
+++ b/gtk/src/appchooserbutton.hg
@@ -24,11 +24,27 @@ _PINCLUDE(gtkmm/private/combobox_p.h)
 namespace Gtk
 {
 
-//TODO: The AppChooser content-type is not documented properly: 
https://bugzilla.gnome.org/show_bug.cgi?id=650012
-
 /** A button to launch an application chooser dialog.
  *
- * This widget lets the user select an application. See the GtkAppChooser base class API.
+ * This widget lets the user select an application. See the AppChooser base class API.
+ *
+ * Initially, an AppChooserButton selects the first application
+ * in its list, which will either be the most-recently used application
+ * or, if property_show_default_item() is <tt>true</tt>, the
+ * default application.
+ *
+ * The list of applications shown in an AppChooserButton includes
+ * the recommended applications for the given content type. When
+ * property_show_default_item() is set, the default application
+ * is also included. To let the user choose other applications,
+ * you can set property_show_dialog_item(),
+ * which allows to open a full AppChooserDialog.
+ *
+ * It is possible to add custom items to the list, using append_custom_item().
+ * These items cause signal_custom_item_activated() to be
+ * emitted when they are selected.
+ *
+ * To track changes in the selected application, use ComboBox::signal_changed().
  *
  * The AppChooserButton widget looks like this:
  * @image html appchooserbutton1.png
@@ -47,6 +63,8 @@ public:
 
   /** Creates a new app-chooser button for applications that can handle content of the given type.
    *
+   * See @ref giommContentType in glibmm for more information about content types.
+   *
    * @param content_type The content type to show applications for
    */
   _WRAP_CTOR(AppChooserButton(const Glib::ustring& content_type), gtk_app_chooser_button_new)
diff --git a/gtk/src/appchooserdialog.hg b/gtk/src/appchooserdialog.hg
index 667b325..0452e24 100644
--- a/gtk/src/appchooserdialog.hg
+++ b/gtk/src/appchooserdialog.hg
@@ -26,8 +26,6 @@ _PINCLUDE(gtkmm/private/dialog_p.h)
 namespace Gtk
 {
 
-//TODO: The AppChooser content-type is not documented properly: 
https://bugzilla.gnome.org/show_bug.cgi?id=650012
-
 /** An application chooser dialog.
  *
  * This dialog shows an AppChooserWidget inside a Dialog.
@@ -36,8 +34,12 @@ namespace Gtk
  * Instead, you should get the embedded AppChooserWidget using get_widget() and
  * call its methods if the generic AppChooser base class API is not sufficient for your needs.
  *
+ * To set the heading that is shown above the AppChooserWidget, use set_heading().
+ *
+ * See @ref giommContentType in glibmm for more information about content types.
+ *
  * The AppChooserDialog dialog looks like this:
- * @image html appchooserbutton1.png
+ * @image html appchooserdialog1.png
  *
  * @ingroup Dialogs
  *
@@ -71,5 +73,4 @@ public:
   _WRAP_PROPERTY("heading", Glib::ustring)
 };
 
-
 } // namespace Gtk
diff --git a/gtk/src/appchooserwidget.hg b/gtk/src/appchooserwidget.hg
index 946c44c..c8a2edc 100644
--- a/gtk/src/appchooserwidget.hg
+++ b/gtk/src/appchooserwidget.hg
@@ -25,15 +25,18 @@ _PINCLUDE(gtkmm/private/box_p.h)
 namespace Gtk
 {
 
-//TODO: The AppChooser content-type is not documented properly: 
https://bugzilla.gnome.org/show_bug.cgi?id=650012
-
-/** An application chooser widget that can be embedded in other widgets
+/** An application chooser widget that can be embedded in other widgets.
  *
  * This widget is for selecting applications. It is the main building block for AppChooserDialog.
- * Most applications only need to use the latter, but you can use this widget as part of a larger widget if 
you have special needs.
+ * Most applications only need to use the latter, but you can use this widget as part of
+ * a larger widget if you have special needs.
+ *
+ * AppChooserWidget offers detailed control over what applications are shown, using
+ * property_show_default() and its other properties.
+ * See the AppChooser documentation for more information about the groups of applications.
  *
- * The AppChooserWidget widget looks like this:
- * @image html appchooserwidget1.png
+ * To keep track of the selected application, use signal_application_selected() and
+ * signal_application_activated().
  *
  * @ingroup Widgets
  *
@@ -49,6 +52,8 @@ public:
 
   /** Creates a new app-chooser widget for applications that can handle content of the given type.
    *
+   * See @ref giommContentType in glibmm for more information about content types.
+   *
    * @param content_type The content type to show applications for
    */
   _WRAP_CTOR(AppChooserWidget(const Glib::ustring& content_type), gtk_app_chooser_widget_new)