Try harder to explain GApplicationCommandline

Trying to answer some of the questions in
https://bugzilla.gnome.org/show_bug.cgi?id=643468

gio/gapplication.c

@@ -583,8 +583,11 @@ g_application_class_init (GApplicationClass *class)
    *     passed commandline
    *
    * The ::command-line signal is emitted on the primary instance when
-   * a commandline is not handled locally. See g_application_run() for
-   * more information.
+   * a commandline is not handled locally. See g_application_run() and
+   * the #GApplicationCommandline documentation for more information.
+   *
+   * Returns: An integer that is set as the exit status for the calling
+   *   process. See g_application_command_line_set_exit_status().
    */
   g_application_signals[SIGNAL_COMMAND_LINE] =
     g_signal_new ("command-line", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
@@ -937,7 +940,7 @@ g_application_get_is_remote (GApplication *application)
  * This is the point at which the application discovers if it is the
  * primary instance or merely acting as a remote for an already-existing
  * primary instance.  This is implemented by attempting to acquire the
- * application identifier as a uniue bus name on the session bus using
+ * application identifier as a unique bus name on the session bus using
  * GDBus.
  *
  * Due to the internal architecture of GDBus, method calls can be

gio/gapplicationcommandline.c

@@ -52,7 +52,23 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * of this object (ie: the process exits when the last reference is
  * dropped).
  *
+ * The main use for #GApplicationCommandline (and the
+ * #GApplication::command-line signal) is 'Emacs server' like use cases:
+ * You can set the <envvar>EDITOR</envvar> environment variable to have
+ * e.g. git use your favourite editor to edit commit messages, and if you
+ * already have an instance of the editor running, the editing will happen
+ * in the running instance, instead of opening a new one. An important
+ * aspect of this use case is that the process that gets started by git
+ * does not return until the editing is done.
+ *
  * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
+ * <para>
+ * A simple example where the commandline is completely handled
+ * in the ::command-line handler. The calling process exits once the
+ * signal handler in the main instance has returned, and the return
+ * value of the signal handler becomes the exit status of the calling
+ * process.
+ * </para>
  * <programlisting>
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
@@ -60,13 +76,33 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * </programlisting>
  * </example>
  *
- * <example id="gapplication-example-cmdline2"><title>Complicated commandline handling</title>
+ * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title>
+ * <para>
+ * An example of split commandline handling. Options that start with
+ * <literal>--local-</literal> are handled locally, all other options are
+ * passed to the ::command-line handler which runs in the main instance.
+ * </para>
  * <programlisting>
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
  *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
  * </xi:include>
  * </programlisting>
  * </example>
+ *
+ * <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
+ * <para>
+ * An example of deferred commandline handling. Here, the commandline is
+ * not completely handled in the ::command-line handler. Instead, we keep
+ * a reference to the GApplicationCommandline object and handle it later
+ * (in this example, in an idle). Note that it is necessary to hold the
+ * application until you are done with the commandline.
+ * </para>
+ * <programlisting>
+ * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c">
+ *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * </xi:include>
+ * </programlisting>
+ * </example>
  **/
 
 enum

gio/tests/Makefile.am

@@ -90,6 +90,7 @@ SAMPLE_PROGS = 				\
 	gapplication-example-open	\
 	gapplication-example-cmdline	\
 	gapplication-example-cmdline2	\
+	gapplication-example-cmdline3	\
 	gapplication-example-actions	\
 	$(NULL)
 
@@ -328,6 +329,9 @@ gapplication_example_cmdline_LDADD   = $(progs_ldadd)
 gapplication_example_cmdline2_SOURCES = gapplication-example-cmdline2.c
 gapplication_example_cmdline2_LDADD   = $(progs_ldadd)
 
+gapplication_example_cmdline3_SOURCES = gapplication-example-cmdline3.c
+gapplication_example_cmdline3_LDADD   = $(progs_ldadd)
+
 gapplication_example_actions_SOURCES = gapplication-example-actions.c
 gapplication_example_actions_LDADD   = $(progs_ldadd)
 

gio/tests/gapplication-example-cmdline3.c

@@ -0,0 +1,65 @@
+#include <gio/gio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static gboolean
+my_cmdline_handler (gpointer data)
+{
+  GApplicationCommandLine *cmdline = data;
+  gchar **argv;
+  gint argc;
+  gint i;
+
+  argv = g_application_command_line_get_arguments (cmdline, &argc);
+
+  g_application_command_line_print (cmdline,
+                                    "This text is written back\n"
+                                    "to stdout of the caller\n");
+
+  for (i = 0; i < argc; i++)
+    g_print ("argument %d: %s\n", i, argv[i]);
+
+  g_strfreev (argv);
+
+  g_application_command_line_set_exit_status (cmdline, 1);
+
+  /* we are done handling this commandline */
+  g_object_unref (cmdline);
+
+  return FALSE;
+}
+
+static int
+command_line (GApplication            *application,
+              GApplicationCommandLine *cmdline)
+{
+  /* keep the application running until we are done with this commandline */
+  g_application_hold (application);
+
+  g_object_set_data_full (G_OBJECT (cmdline),
+                          "application", application,
+                          (GDestroyNotify)g_application_release);
+
+  g_object_ref (cmdline);
+  g_idle_add (my_cmdline_handler, cmdline);
+
+  return 0;
+}
+
+int
+main (int argc, char **argv)
+{
+  GApplication *app;
+  int status;
+
+  app = g_application_new ("org.gtk.TestApplication",
+                           G_APPLICATION_HANDLES_COMMAND_LINE);
+  g_signal_connect (app, "command-line", G_CALLBACK (command_line), NULL);
+  g_application_set_inactivity_timeout (app, 10000);
+
+  status = g_application_run (app, argc, argv);
+
+  g_object_unref (app);
+
+  return status;
+}