diff --git a/gio/gapplication.c b/gio/gapplication.c
index f97312e7e..f10d2d86c 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