While trying to review a patch that adds a --version flag (bug 760796) to a program, I realized that the documentation around this is confusing due to various issues.

(a) https://wiki.gnome.org/HowDoI/GtkApplication needs an update. It still recommends using local_command_line to implement --version. Since version 2.40 (bug 721977) it should be handle_local_options, which is what https://wiki.gnome.org/HowDoI/GtkApplication/CommandLine and the gtk-doc documentation talks about.

(b) The gtk-doc has this text about local_command_line:
    "invoked (locally) when the process has been invoked via commandline execution (as opposed to, say, D-Bus activation - which is not currently supported by GApplication). The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information."

    What is the "when the process has been invoked via commandline execution as opposed to, say, D-Bus activation" part trying to say? Reading the implementation of g_application_run tells me that local_command_line is always called.

    I have no idea what "which is not currently supported by GApplication" means. What is unsupported? Does this mean that the default implementation doesn't allow command line arguments with G_APPLICATION_IS_SERVICE?

(c) Since commit 0e671286fc59b we lost the explanation about the behaviour of the default local_command_line implementation. While it is good to avoid documenting internal details, it is no longer clear what is expected from someone who is using their own implementation. The documentation says:
    "If you are interested in doing more complicated local handling of the commandline then ... 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."

    It might be nicer to mention something about the consequences of returning TRUE versus FALSE, and that default implementation does things like g_application_register, g_application_startup, g_application_open, etc.. Note that gapplication-example-cmdline2.c is not a complete example.