[glib] Tweak GApplication docs

[Matthias Clasen <matthiasc src gnome org>]

commit 8c7e284116085058fa8b2600e02502aa6acb3f9e
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Nov 2 22:39:58 2010 -0400

    Tweak GApplication docs

 gio/gapplication.c                        |    9 +++++++++
 gio/tests/gapplication-example-actions.c  |    7 -------
 gio/tests/gapplication-example-cmdline.c  |    4 ----
 gio/tests/gapplication-example-cmdline2.c |    4 ----
 gio/tests/gapplication-example-open.c     |   16 +++++++++++-----
 5 files changed, 20 insertions(+), 20 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index 6be6036..da9d54d 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -74,6 +74,15 @@
  * When invoking an action by calling g_action_group_activate_action() on
  * the application, it is always invoked in the primary instance.
  *
+ * There is a number of different entry points into a #GApplication:
+ * <itemizedlist>
+ * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
+ * <listitem>via 'Open' (i.e. opening some files)</listitem>
+ * <listitem>via activating an action</listitem>
+ * </itemizedlist>
+ * The #GApplication::startup signal lets you handle the application
+ * initialization for all of these in a single place.
+ *
  * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
  * <programlisting>
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-open.c">
diff --git a/gio/tests/gapplication-example-actions.c b/gio/tests/gapplication-example-actions.c
index 3fc55f7..5becb95 100644
--- a/gio/tests/gapplication-example-actions.c
+++ b/gio/tests/gapplication-example-actions.c
@@ -5,9 +5,7 @@
 static void
 activate (GApplication *application)
 {
-  g_application_hold (application);
   g_print ("activated\n");
-  g_application_release (application);
 }
 
 static void
@@ -17,9 +15,7 @@ activate_action (GAction  *action,
 {
   GApplication *application = data;
 
-  g_application_hold (application);
   g_print ("action %s activated\n", g_action_get_name (action));
-  g_application_release (application);
 }
 
 static void
@@ -31,7 +27,6 @@ activate_toggle_action (GAction  *action,
   GVariant *state;
   gboolean b;
 
-  g_application_hold (application);
   g_print ("action %s activated\n", g_action_get_name (action));
 
   state = g_action_get_state (action);
@@ -39,8 +34,6 @@ activate_toggle_action (GAction  *action,
   g_variant_unref (state);
   g_action_set_state (action, g_variant_new_boolean (!b));
   g_print ("state change %d -> %d\n", b, !b);
-
-  g_application_release (application);
 }
 
 static void
diff --git a/gio/tests/gapplication-example-cmdline.c b/gio/tests/gapplication-example-cmdline.c
index 7c8f379..99380cd 100644
--- a/gio/tests/gapplication-example-cmdline.c
+++ b/gio/tests/gapplication-example-cmdline.c
@@ -10,8 +10,6 @@ command_line (GApplication            *application,
   gint argc;
   gint i;
 
-  g_application_hold (application);
-
   argv = g_application_command_line_get_arguments (cmdline, &argc);
 
   g_application_command_line_print (cmdline,
@@ -23,8 +21,6 @@ command_line (GApplication            *application,
 
   g_strfreev (argv);
 
-  g_application_release (application);
-
   return 0;
 }
 
diff --git a/gio/tests/gapplication-example-cmdline2.c b/gio/tests/gapplication-example-cmdline2.c
index 12fcda1..8280873 100644
--- a/gio/tests/gapplication-example-cmdline2.c
+++ b/gio/tests/gapplication-example-cmdline2.c
@@ -10,8 +10,6 @@ command_line (GApplication            *application,
   gint argc;
   gint i;
 
-  g_application_hold (application);
-
   argv = g_application_command_line_get_arguments (cmdline, &argc);
 
   for (i = 0; i < argc; i++)
@@ -19,8 +17,6 @@ command_line (GApplication            *application,
 
   g_strfreev (argv);
 
-  g_application_release (application);
-
   return 0;
 }
 
diff --git a/gio/tests/gapplication-example-open.c b/gio/tests/gapplication-example-open.c
index b2370f7..6dcf53c 100644
--- a/gio/tests/gapplication-example-open.c
+++ b/gio/tests/gapplication-example-open.c
@@ -5,9 +5,13 @@
 static void
 activate (GApplication *application)
 {
-  g_application_hold (application);
   g_print ("activated\n");
-  g_application_release (application);
+
+  /* Note: when doing a longer-lasting action here that returns
+   * to the mainloop, you should use g_application_hold() and
+   * g_application_release() to keep the application alive until
+   * the action is completed.
+   */
 }
 
 static void
@@ -18,8 +22,6 @@ open (GApplication  *application,
 {
   gint i;
 
-  g_application_hold (application);
-
   for (i = 0; i < n_files; i++)
     {
       gchar *uri = g_file_get_uri (files[i]);
@@ -27,7 +29,11 @@ open (GApplication  *application,
       g_free (uri);
     }
 
-  g_application_release (application);
+  /* Note: when doing a longer-lasting action here that returns
+   * to the mainloop, you should use g_application_hold() and
+   * g_application_release() to keep the application alive until
+   * the action is completed.
+   */
 }
 
 int