Brush up the GApplication docs

Also, fix up inclusions, mark properties for translation, etc.

gio/gapplication.c

@@ -20,6 +20,8 @@
  */
 
 /* Prologue {{{1 */
+#include "config.h"
+
 #include "gapplication.h"
 
 #include "gapplicationcommandline.h"
@@ -31,8 +33,45 @@
 #include "gioenums.h"
 #include "gfile.h"
 
+#include "glibintl.h"
+
 #include <string.h>
 
+/**
+ * SECTION: gapplication
+ * @title: GApplication
+ * @short_description: Core application class
+ *
+ * A #GApplication is the foundation of an application, unique for a
+ * given application identifier.  The GApplication class wraps some
+ * low-level platform-specific services and is intended to act as the
+ * foundation for higher-level application classes such as
+ * #GtkApplication or #MxApplication.  In general, you should not use
+ * this class outside of a higher level framework.
+ *
+ * One of the core features that GApplication provides is process
+ * uniqueness, in the context of a "session".  The session concept is
+ * platform-dependent, but corresponds roughly to a graphical desktop
+ * login.  When your application is launched again, its arguments
+ * are passed through platform communication to the already running
+ * program. The already running instance of the program is called the
+ * <firstterm>primary instance</firstterm>.
+ *
+ * Before using GApplication, you must choose an "application identifier".
+ * The expected form of an application identifier is very close to that of
+ * of a <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
+ * Examples include: "com.example.MyApp" "org.example.internal-apps.Calculator"
+ * For convenience, the restrictions on application identifiers are reproduced
+ * here:
+ * <itemizedlist>
+ *   <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.</listitem>
+ *   <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least two elements).</listitem>
+ *   <listitem>Application identifiers must not begin with a '.' (period) character.</listitem>
+ *   <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
+ *   <listitem>Application identifiers must not exceed 255 characters.</listitem>
+ * </itemizedlist>
+ */
+
 struct _GApplicationPrivate
 {
   GApplicationFlags  flags;
@@ -410,54 +449,95 @@ g_application_class_init (GApplicationClass *class)
   class->run_mainloop = g_application_real_run_mainloop;
 
   g_object_class_install_property (object_class, PROP_APPLICATION_ID,
-    g_param_spec_string ("application-id", "application identifier",
+    g_param_spec_string ("application-id",
-                         "Unique identifier for the application",
+                         P_("Application identifier"),
+                         P_("The unique identifier for the application"),
                          NULL, G_PARAM_READWRITE | G_PARAM_CONSTRUCT |
                          G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property (object_class, PROP_FLAGS,
-    g_param_spec_flags ("flags", "application flags",
+    g_param_spec_flags ("flags",
-                        "Flags specifying the behaviour of the application",
+                        P_("Application flags"),
+                        P_("Flags specifying the behaviour of the application"),
                         G_TYPE_APPLICATION_FLAGS, G_APPLICATION_FLAGS_NONE,
                         G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property (object_class, PROP_IS_REGISTERED,
-    g_param_spec_boolean ("is-registered", "is registered",
+    g_param_spec_boolean ("is-registered",
-                          "If g_application_register() has been called",
+                          P_("Is registered"),
+                          P_("If g_application_register() has been called"),
                           FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property (object_class, PROP_IS_REMOTE,
-    g_param_spec_boolean ("is-remote", "is remote",
+    g_param_spec_boolean ("is-remote",
-                          "If this application instance is remote",
+                          P_("Is remote"),
+                          P_("If this application instance is remote"),
                           FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property (object_class, PROP_INACTIVITY_TIMEOUT,
-    g_param_spec_boolean ("inactivity-timeout", "inactivity timeout",
+    g_param_spec_boolean ("inactivity-timeout",
-                          "time (ms) to stay alive after becoming idle",
+                          P_("Inactivity timeout"),
+                          P_("Iime (ms) to stay alive after becoming idle"),
                           FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property (object_class, PROP_ACTION_GROUP,
-    g_param_spec_object ("action-group", "action group",
+    g_param_spec_object ("action-group",
-                         "the group of actions that the application exports",
+                         P_("Action group"),
+                         P_("The group of actions that the application exports"),
                          G_TYPE_ACTION_GROUP, 
                          G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS));
 
+  /**
+   * GApplication::startup:
+   * @application: the application
+   *
+   * The ::startup signal is emitted on the primary instance immediately
+   * after registration. See g_activation_register().
+   */
   g_application_signals[SIGNAL_STARTUP] =
     g_signal_new ("startup", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
                   G_STRUCT_OFFSET (GApplicationClass, startup),
                   NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
 
+  /**
+   * GApplication::activate:
+   * @application: the application
+   *
+   * The ::activate signal is emitted on the primary instance when an
+   * activation occurs. See g_application_activate().
+   */
   g_application_signals[SIGNAL_ACTIVATE] =
     g_signal_new ("activate", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
                   G_STRUCT_OFFSET (GApplicationClass, activate),
                   NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
 
+
+  /**
+   * GApplication::open:
+   * @application: the application
+   * @files: an array of #GFile objects
+   * @n_files: the length of @files
+   * @hint: a hint provided by the calling instance
+   *
+   * The ::open signal is emitted on the primary instance when there are
+   * files to open. See g_application_open() for more information.
+   */
   g_application_signals[SIGNAL_OPEN] =
     g_signal_new ("open", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
                   G_STRUCT_OFFSET (GApplicationClass, open),
                   NULL, NULL, _gio_marshal_VOID__POINTER_INT_STRING,
                   G_TYPE_NONE, 3, G_TYPE_POINTER, G_TYPE_INT, G_TYPE_STRING);
 
+  /**
+   * GApplication::command-line:
+   * @application: the application
+   * @command_line: a #GApplicationCommandLine representing the
+   *     passed commandline
+   *
+   * The ::command-line signal is emitted on the primary instance when
+   * a commandline is not handled locally. See g_application_run() for
+   * more information.
+   */
   g_application_signals[SIGNAL_COMMAND_LINE] =
     g_signal_new ("command-line", G_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
                   G_STRUCT_OFFSET (GApplicationClass, command_line),
@@ -938,7 +1018,7 @@ g_application_activate (GApplication *application)
  * for this functionality, you should use "".
  *
  * The application must be registered before calling this function and
- * it must have the %G_APPLICATION_CAN_OPEN flag set.  The open()
+ * it must have the %G_APPLICATION_HANDLES_OPEN flag set.  The open()
  * virtual function should also be implemented in order for anything
  * meaningful to happen.
  *
@@ -980,11 +1060,11 @@ g_application_open (GApplication  *application,
  *
  * First, the handle_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 command_line()
+ * %FALSE then the application is registered and the #GApplication::command-line
- * virtual function is invoked in the primary instance (which may or may
+ * signal is emitted in the primary instance (which may or may not be
- * not be this instance).
+ * this instance).
  *
- * If the application has the %G_APPLICATION_REMOTE_COMMAND_LINE
+ * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
  * flag set then the default implementation of handle_command_line()
  * always returns %FALSE immediately, resulting in the commandline
  * always being handled in the primary instance.
@@ -995,7 +1075,7 @@ g_application_open (GApplication  *application,
  * to register the application.  If that works, then the command line
  * arguments are inspected.  If no commandline arguments are given, then
  * g_application_activate() is called.  If commandline arguments are
- * given and the %G_APPLICATION_CAN_OPEN flags is set then they
+ * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
  * are assumed to be filenames and g_application_open() is called.
  *
  * If you are interested in doing more complicated local handling of the
@@ -1006,6 +1086,10 @@ g_application_open (GApplication  *application,
  * non-zero then the mainloop is run until the use count falls to zero,
  * at which point 0 is returned.
  *
+ * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at
+ * use count of zero is delayed for a while (ie: the instance stays
+ * around to provide its <emphasis>service</emphasis> to others).
+ *
  * Since: 2.28
  **/
 int

gio/gapplication.h

@@ -64,6 +64,8 @@ struct _GApplication
  * @startup: invoked on the primary instance immediately after registration
  * @activate: invoked on the primary instance when an activation occurs
  * @open: invoked on the primary instance when there are files to open
+ * @command_line: invoked on the primary instance when a command-line is
+ *   not handled locally
  * @local_command_line: invoked (locally) when the process has been invoked 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.

gio/gapplicationcommandline.c

@@ -19,8 +19,12 @@
  * Authors: Ryan Lortie <desrt@desrt.ca>
  */
 
+#include "config.h"
+
 #include "gapplicationcommandline.h"
 
+#include "glibintl.h"
+
 #include <string.h>
 #include <stdio.h>
 
@@ -30,12 +34,12 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * SECTION:gapplicationcommandline
  * @title: GApplicationCommandLine
  * @short_description: A class representing a command-line invocation of
- *                     this application.
+ *                     an application
  * @see_also: #GApplication
  *
  * #GApplicationCommandLine represents a command-line invocation of
- * containing application.  It is created by #GApplication and emitted
+ * an application.  It is created by #GApplication and emitted
- * in the <varname>command-line</varname> signal and virtual function.
+ * in the #GApplication::command-line signal and virtual function.
  *
  * The class contains the list of arguments that the program was invoked
  * with.  It is also possible to query if the commandline invocation was
@@ -102,8 +106,10 @@ g_application_command_line_real_printerr_literal (GApplicationCommandLine *cmdli
 }
 
 static void
-g_application_command_line_get_property (GObject *object, guint prop_id,
+g_application_command_line_get_property (GObject    *object,
-                                         GValue *value, GParamSpec *pspec)
+                                         guint       prop_id,
+                                         GValue     *value,
+                                         GParamSpec *pspec)
 {
   GApplicationCommandLine *cmdline = G_APPLICATION_COMMAND_LINE (object);
 
@@ -190,22 +196,26 @@ g_application_command_line_class_init (GApplicationCommandLineClass *class)
   class->print_literal = g_application_command_line_real_print_literal;
 
   g_object_class_install_property (object_class, PROP_ARGUMENTS,
-    g_param_spec_variant ("arguments", "commandline arguments",
+    g_param_spec_variant ("arguments",
-                          "the commandline that caused this cmdline",
+                          P_("Commandline arguments"),
+                          P_("The commandline that caused this ::command-line signal emission"),
                           G_VARIANT_TYPE_BYTESTRING_ARRAY, NULL,
                           G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY |
                           G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property (object_class, PROP_PLATFORM_DATA,
-    g_param_spec_variant ("platform-data", "platform data",
+    g_param_spec_variant ("platform-data",
-                          "platform-specific data for the cmdline",
+                          P_("Platform data"),
+                          P_("Platform-specific data for the commandline"),
                           G_VARIANT_TYPE ("a{sv}"), NULL,
                           G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY |
                           G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property (object_class, PROP_IS_REMOTE,
-    g_param_spec_boolean ("is-remote", "is remote",
+    g_param_spec_boolean ("is-remote",
-                          "TRUE if this is a remote cmdline", FALSE,
+                          P_("Is remote"),
+                          P_("TRUE if this is a remote commandline"),
+                          FALSE,
                           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
   g_type_class_add_private (class, sizeof (GApplicationCommandLinePrivate));
@@ -365,7 +375,7 @@ g_application_command_line_printerr (GApplicationCommandLine *cmdline,
  * Sets the exit status that will be used when the invoking process
  * exits.
  *
- * The return value of the <varname>command-line</varname> signal is
+ * The return value of the #GApplication::command-line signal is
  * passed to this function when the handler returns.  This is the usual
  * way of setting the exit status.
  *

gio/gdbuserror.c

@@ -36,7 +36,7 @@
 /**
  * SECTION:gdbuserror
  * @title: GDBusError
- * @short_description: Mapping D-Bus errors to and from #GError
+ * @short_description: Mapping D-Bus errors to and from GError
  * @include: gio/gio.h
  *
  * All facilities that return errors from remote methods (such as

gio/gioenums.h

@@ -1219,7 +1219,13 @@ typedef enum
 /**
  * GApplicationFlags:
  * @G_APPLICATION_FLAGS_NONE: Default
- * @G_APPLICATION_FLAGS_HANDLE_OPEN: This application handles opening files.
+ * @G_APPLICATION_IS_SERVICE: 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_COMMAND_LINE: This application handles command lines
+ *     (in the primary instance)
  *
  * Flags used to define the behaviour of a #GApplication.
  *

gio/gsimpleaction.c

@@ -33,7 +33,7 @@ G_DEFINE_TYPE_WITH_CODE (GSimpleAction, g_simple_action, G_TYPE_OBJECT,
 /**
  * SECTION:gsimpleaction
  * @title: GSimpleAction
- * @short_description: a simple #GSimpleAction
+ * @short_description: a simple GSimpleAction
  *
  * A #GSimpleAction is the obvious simple implementation of the #GSimpleAction
  * interface.  This is the easiest way to create an action for purposes of

gio/gsimpleactiongroup.c

@@ -25,7 +25,7 @@
 /**
  * SECTION:gsimpleactiongroup
  * @title: GSimpleActionGroup
- * @short_description: a simple #GActionGroup implementation
+ * @short_description: a simple GActionGroup implementation
  *
  * #GSimpleActionGroup is a hash table filled with #GAction objects,
  * implementing the #GActionGroup interface.