From 1a6455b7858ea16f314949ceed9a128ad46267b2 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 4 Mar 2011 00:03:13 -0500 Subject: [PATCH] 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 file changed, 16 insertions(+), 4 deletions(-) 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 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 * for an example. * * If, after the above is done, the use count of the application is zero