[glib] GApplication: Improve documentation

[Matthias Clasen <matthiasc src gnome org>]

commit f05bce027e49ba3ba4dee042ed52837d0145a7bf
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Mar 3 23:34:49 2011 -0500

    GApplication: Improve documentation
    
    This commit adds some details regarding platform data.

 gio/gapplication.c |   28 +++++++++++++++++++++++-----
 gio/gapplication.h |   20 +++++++++++++-------
 gio/gioenums.h     |   12 ++++++++----
 3 files changed, 44 insertions(+), 16 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index 48f8065..f97312e 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -94,11 +94,29 @@
  * <itemizedlist>
  * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
  * <listitem>via 'Open' (i.e. opening some files)</listitem>
+ * <listitem>by handling a command-line</listitem>
  * <listitem>via activating an action</listitem>
  * </itemizedlist>
  * The #GApplication::startup signal lets you handle the application
  * initialization for all of these in a single place.
  *
+ * Regardless of which of these entry points is used to start the application,
+ * GApplication passes some <firstterm id="platform-data">platform
+ * 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.
+ *
+ * As the name indicates, the platform data may vary depending on the
+ * operating system, but it always includes the current directory (key
+ * "cwd"), and optionally the environment (ie the set of environment
+ * variables and their values) of the calling process (key "environ").
+ * The environment is only added to the platform data if the
+ * #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.
+ *
  * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
  * <programlisting>
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-open.c">
@@ -1146,11 +1164,11 @@ g_application_open (GApplication  *application,
  * This function is intended to be run from main() and its return value
  * 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 that function 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).
+ * 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
+ * instance (which may or may not be this instance).
  *
  * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
  * flag set then the default implementation of local_command_line()
diff --git a/gio/gapplication.h b/gio/gapplication.h
index d6605f6..b178701 100644
--- a/gio/gapplication.h
+++ b/gio/gapplication.h
@@ -70,13 +70,19 @@ struct _GApplication
  *     via commandline execution.  The virtual function has the chance to
  *     inspect (and possibly replace) the list of command line arguments.
  *     See g_application_run() for more information.
- * @before_emit: invoked on the primary instance before 'activate', 'open' or any action invocation
- * @after_emit: invoked on the primary instance after 'activate', 'open' or any action invocation
- * @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when
- *   activating, opening or invoking actions
- * @quit_mainloop: invoked on the primary instance when the use count of the application drops to zero (and
- *   after any inactivity timeout, if requested)
- * @run_mainloop: invoked on the primary instance from g_application_run() if the use-count is non-zero
+ * @before_emit: invoked on the primary instance before 'activate', 'open',
+ *     'command-line' or any action invocation, gets the 'platform data' from
+ *     the calling instance
+ * @after_emit: invoked on the primary instance after 'activate', 'open',
+ *     'command-line' or any action invocation, gets the 'platform data' from
+ *     the calling instance
+ * @add_platform_data: invoked (locally) to add 'platform data' to be sent to
+ *     the primary instance when activating, opening or invoking actions
+ * @quit_mainloop: invoked on the primary instance when the use count of the
+ *     application drops to zero (and after any inactivity timeout, if
+ *     requested)
+ * @run_mainloop: invoked on the primary instance from g_application_run()
+ *     if the use-count is non-zero
  *
  * Since: 2.28
  */
diff --git a/gio/gioenums.h b/gio/gioenums.h
index 84907fe..6203aca 100644
--- a/gio/gioenums.h
+++ b/gio/gioenums.h
@@ -1248,12 +1248,16 @@ typedef enum
  *      fails if the service is already running, and the application will
  *      stay around for a while when the use count falls to zero.
  * @G_APPLICATION_IS_LAUNCHER: Don't try to become the primary instance.
- * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in the
- *     primary instance)
+ * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in
+ *     the primary instance). See g_application_run() for details.
  * @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command line
- *     arguments (in the primary instance)
+ *     arguments (in the primary instance). See g_application_run() for details.
  * @G_APPLICATION_SEND_ENVIRONMENT: Send the environment of the
- *     launching process to the primary instance
+ *     launching process to the primary instance. Set this flag if your
+ *     application is expected to behave differently depending on certain
+ *     environment variables. For instance, an editor might be expected
+ *     to use the <envvar>GIT_COMMITTER_NAME</envvar> environment variable
+ *     when editing a git commit message.
  *
  * Flags used to define the behaviour of a #GApplication.
  *