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.

diff --git a/gio/gapplication.c b/gio/gapplication.c
index 1172a59..5f922d1 100644 (file)
--- 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>.