[glib] GApplication: More documentation tweaks

[Matthias Clasen <matthiasc src gnome org>]

commit 1485871ed5e8e9ce70b088cfedae4012032e5dca
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Mar 4 01:53:56 2011 -0500

    GApplication: More documentation tweaks

 gio/gapplication.c            |   22 +++++++++++++++++-----
 gio/gapplicationcommandline.c |   36 +++++++++++++++++++++---------------
 2 files changed, 38 insertions(+), 20 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index f4a47e1..6cacb1e 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -105,7 +105,11 @@
  * data</firstterm> from the launching instance to the primary instance,
  * in the form of a #GVariant dictionary mapping strings to variants.
  * To use platform data, override the @before_emit or @after_emit virtual
- * functions in your #GApplication subclass.
+ * functions in your #GApplication subclass. When dealing with
+ * #GApplicationCommandline objects, the platform data is directly
+ * available via g_application_command_line_get_cwd(),
+ * g_application_command_line_get_environ() and
+ * g_application_command_line_get_platform_data().
  *
  * As the name indicates, the platform data may vary depending on the
  * operating system, but it always includes the current directory (key
@@ -115,7 +119,12 @@
  * #G_APPLICATION_SEND_ENVIONMENT flag is set. GApplication subclasses
  * can add their own platform data by overriding the @add_platform_data
  * virtual function. For instance, #GtkApplication adds startup notification
- * information in this way.
+ * data in this way.
+ *
+ * To parse commandline arguments you may handle the
+ * #GApplication::command-line signal or override the local_command_line()
+ * vfunc, to parse them in either the primary instance or the local instance,
+ * respectively.
  *
  * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
  * <programlisting>
@@ -1168,10 +1177,13 @@ g_application_open (GApplication  *application,
  * required.
  *
  * First, the local_command_line() virtual function is invoked.
- * This function always runs on the local instance. It gets passed
- * a pointer to a copy of @argv and is expected to remove the arguments
+ * This function always runs on the local instance. It gets passed a pointer
+ * to a %NULL-terminated copy of @argv and is expected to remove the arguments
  * that it handled (shifting up remaining arguments). See
- * <xref linkend="gapplication-example-cmdline2"/> for an example.
+ * <xref linkend="gapplication-example-cmdline2"/> for an example of
+ * parsing @argv manually. Alternatively, you may use the #GOptionContext API,
+ * after setting <literal>argc = g_strv_length (argv);</literal>.
+ *
  * 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().
diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c
index 7b0175a..b3c98f5 100644
--- a/gio/gapplicationcommandline.c
+++ b/gio/gapplicationcommandline.c
@@ -49,7 +49,7 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * The GApplicationCommandLine object can provide the @argc and @argv
  * parameters for use with the #GOptionContext command-line parsing API,
  * with the g_application_command_line_get_arguments() function. See
- * <xref linkend="gapplication-example-cmdline3"> for an example.
+ * <xref linkend="gapplication-example-cmdline3"/> for an example.
  *
  * The exit status of the originally-invoked process may be set and
  * messages can be printed to stdout or stderr of that process.  The
@@ -59,7 +59,7 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  *
  * 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
+ * You can set the <envar>EDITOR</envar> 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
@@ -69,10 +69,10 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * <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.
+ * in the #GApplication::command-line handler. The launching instance exits
+ * once the signal handler in the primary instance has returned, and the
+ * return value of the signal handler becomes the exit status of the launching
+ * instance.
  * </para>
  * <programlisting>
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
@@ -85,7 +85,8 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * <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.
+ * passed to the #GApplication::command-line handler which runs in the primary
+ * instance.
  * </para>
  * <programlisting>
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
@@ -97,10 +98,11 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * <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.
+ * not completely handled before the #GApplication::command-line handler
+ * returns. 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>
  * <para>
  * This example also shows how to use #GOptionContext for parsing the
@@ -329,8 +331,8 @@ g_application_command_line_get_arguments (GApplicationCommandLine *cmdline,
  * g_application_command_line_get_cwd:
  * @cmdline: a #GApplicationCommandLine
  *
- * Gets the working directory of the command line invocation.  The
- * string may contain non-utf8 data.
+ * Gets the working directory of the command line invocation.
+ * The string may contain non-utf8 data.
  *
  * It is possible that the remote application did not send a working
  * directory, so this may be %NULL.
@@ -356,8 +358,9 @@ g_application_command_line_get_cwd (GApplicationCommandLine *cmdline)
  * @cmdline: a #GApplicationCommandLine
  *
  * Gets the contents of the 'environ' variable of the command line
- * invocation, as would be returned by g_get_environ().  The strings may
- * contain non-utf8 data.
+ * invocation, as would be returned by g_get_environ(), ie as a
+ * %NULL-terminated list of strings in the form 'NAME=VALUE'.
+ * The strings may contain non-utf8 data.
  *
  * The remote application usually does not send an environment.  Use
  * %G_APPLICATION_SEND_ENVIRONMENT to affect that.  Even with this flag
@@ -367,6 +370,9 @@ g_application_command_line_get_cwd (GApplicationCommandLine *cmdline)
  * The return value should not be modified or freed and is valid for as
  * long as @cmdline exists.
  *
+ * See g_application_command_line_getenv() if you are only interested
+ * in the value of a single environment variable.
+ *
  * Returns: (array zero-terminated=1) (transfer none): the environment
  * strings, or %NULL if they were not sent
  *