[gtkmm] Application: Added overview docs based on the C docs.

[Murray Cumming <murrayc src gnome org>]

commit 178c83229357a73a8017f6cdfd4520bc621f45d4
Author: Murray Cumming <murrayc murrayc com>
Date:   Tue Oct 8 10:32:52 2013 +0200

    Application: Added overview docs based on the C docs.

 gtk/src/application.hg |   47 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 46 insertions(+), 1 deletions(-)
---
diff --git a/gtk/src/application.hg b/gtk/src/application.hg
index aad46dd..26f4cef 100644
--- a/gtk/src/application.hg
+++ b/gtk/src/application.hg
@@ -40,8 +40,53 @@ _WRAP_ENUM(ApplicationInhibitFlags, GtkApplicationInhibitFlags)
 class Window;
 
 //TODO: Add overview documentation discussing the techniques show in the examples in gtkmm-docmentation.
+//TODO: Add the screenshots from the C API?
 
-/** TODO
+/** The Gtk::Application class handles many important aspects
+ * of a GTK+ application in a convenient fashion, without enforcing
+ * a one-size-fits-all application model.
+ *
+ * Currently, Gtk::Application handles GTK+ and gtkmm initialization, application
+ * uniqueness, session management, provides some basic scriptability and
+ * desktop shell integration by exporting actions and menus, and manages a
+ * list of toplevel windows whose life-cycle is automatically tied to the
+ * life-cycle of your application.
+ *
+ * While Gtk::Application works fine with plain Gtk::Window%s, it is recommended
+ * to use it together with Gtk::ApplicationWindow.
+ *
+ * When GDK threads are enabled, Gtk::Application will acquire the GDK
+ * lock when invoking actions that arrive from other processes.  The GDK
+ * lock is not touched for local action invocations.  In order to have
+ * actions invoked in a predictable context it is therefore recommended
+ * that the GDK lock be held while invoking actions locally with
+ * Gio::ActionGroup::activate_action().  The same applies to actions
+ * associated with Gtk::ApplicationWindow and to the Gio::Application::activate() and
+ * Gio::Application::open() methods.
+ *
+ * To set an application menu for a Gtk::Application, use
+ * set_app_menu(). The Gio::MenuModel that this method
+ * expects is usually constructed using Gtk::Builder.
+ * To specify a menubar that will be shown by
+ * Gtk::ApplicationWindow%s, use set_menubar(). Use the base
+ * Gio::ActionMap interface to add actions, to respond to the user
+ * selecting these menu items.
+ *
+ * GTK+ displays these menus as expected, depending on the platform
+ * the application is running on.
+ *
+ * Gtk::Application optionally registers with a session manager
+ * of the users session (if you set the register-session
+ * property) and offers various functionality related to the session
+ * life-cycle.
+ *
+ * An application can block various ways to end the session with
+ * the inhibit() method. Typical use cases for
+ * this kind of inhibiting are long-running, uninterruptible operations,
+ * such as burning a CD or performing a disk backup. The session
+ * manager may not honor the inhibitor, but it can be expected to
+ * inform the user about the negative consequences of ending the
+ * session while inhibitors are present.
  *
  * @newin{3,4}
  */