[glib] GApplication: document differences from libunique

[Ryan Lortie <ryanl src gnome org>]

commit ce3dddb62200fdcc97cc0aa4ec47400e94d99d36
Author: Ryan Lortie <desrt desrt ca>
Date:   Tue Sep 18 10:14:35 2012 -0400

    GApplication: document differences from libunique
    
    People implementing GApplication often waste a lot of time by trying to
    use it as if it were libunique.  Add a note to the docs about the
    difference.

 gio/gapplication.c |   13 +++++++++++++
 1 files changed, 13 insertions(+), 0 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index 1172a59..5f922d1 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -72,6 +72,19 @@
  * applications this is the always the current instance.
  * On Linux, the D-Bus session bus is used for communication.
  *
+ * The use of #GApplication differs from some other commonly-used
+ * uniqueness libraries (such as libunique) in important ways.  The
+ * application is not expected to manually register itself and check if
+ * it is the primary instance.  Instead, the <code>main()</code>
+ * function of a #GApplication should do very little more than
+ * instantiating the application instance, possibly connecting signal
+ * handlers, then calling g_application_run().  All checks for
+ * uniqueness are done internally.  If the application is the primary
+ * instance then the startup signal is emitted and the mainloop runs.
+ * If the application is not the primary instance then a signal is sent
+ * to the primary instance and g_application_run() promptly returns.
+ * See the code examples below.
+ *
  * If used, the expected form of an application identifier is very close
  * to that of of a
  * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface";>DBus bus name</ulink>.