[glib/glib-2-28] GApplication: Beef up the local_command_line() docs

[Matthias Clasen <matthiasc src gnome org>]

commit 15236daefd2f00d5b4e89d83e4e05c13586f1a07
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Mar 4 00:03:13 2011 -0500

    GApplication: Beef up the local_command_line() docs
    
    This adds some details, such as the meaning of @argc, @argv and @status,
    even though gtk-doc does not make it easy to document vfunc arguments.
    Requested in
    https://bugzilla.gnome.org/show_bug.cgi?id=643478

 gio/gapplication.c |   20 ++++++++++++++++----
 1 files changed, 16 insertions(+), 4 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index f97312e..f10d2d8 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -1165,9 +1165,19 @@ g_application_open (GApplication  *application,
  * is intended to be returned by main().
  *
  * First, the local_command_line() virtual function is invoked.
- * This function always runs on the local instance.  If it returns
- * %FALSE then the application is registered and the
- * #GApplication::command-line signal is emitted in the primary
+ * This function always runs on the local instance. It gets passed
+ * pointers to @argc and @argv and is expected to remove the arguments
+ * that it handled from @argv (shifting up remaining arguments, and
+ * reducing @argc accordingly). See <xref linkend="gapplication-example-cmdline2"/> for an example. The last argument to local_command_line() is a
+ * pointer to the @status variable which can used to set the exit
+ * status that is returned from g_application_run().
+ *
+ * If local_command_line() returns %TRUE, the command line is expected
+ * to be completely handled, including possibly registering as the primary
+ * instance, calling g_application_activate() or g_application_open(), etc.
+ *
+ * If local_command_line() returns %FALSE then the application is registered
+ * and the #GApplication::command-line signal is emitted in the primary
  * instance (which may or may not be this instance).
  *
  * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
@@ -1186,7 +1196,9 @@ g_application_open (GApplication  *application,
  *
  * If you are interested in doing more complicated local handling of the
  * commandline then you should implement your own #GApplication subclass
- * and override local_command_line(). See
+ * and override local_command_line(). In this case, you most likely want
+ * to return %TRUE from your local_command_line() implementation to
+ * suppress the default handling. See
  * <xref linkend="gapplication-example-cmdline2"/> for an example.
  *
  * If, after the above is done, the use count of the application is zero