[glib/wip/gapplication] Some documentation additions

[Matthias Clasen <matthiasc src gnome org>]

commit 87198c88b1d00b77cb3219877b63fb13d984fa6e
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Jun 3 02:39:58 2010 -0400

    Some documentation additions

 gio/gapplication.c |   57 ++++++++++++++++++++++++++++-----------------------
 gio/gapplication.h |   26 +++++++++++------------
 2 files changed, 43 insertions(+), 40 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index 10094b4..6c16ed6 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -42,6 +42,10 @@
  * software will use a higher-level application class such as
  * #GtkApplication.
  *
+ * In addition to single-instance-ness, #GApplication provides support
+ * for 'actions', which can be presented to the user in a platform-specific
+ * way (e.g. Windows jump lists).
+ *
  * 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>.
@@ -116,14 +120,14 @@ static GApplication *primary_application = NULL;
 static GHashTable *instances_for_appid = NULL;
 
 static void     _g_application_platform_init                    (GApplication  *app,
-								 const char    *appid);
+                                                                 const char    *appid);
 static gboolean _g_application_platform_acquire_single_instance (const char    *appid,
                                                                  GError       **error);
 static void     _g_application_platform_remote_invoke_action    (GApplication  *app,
                                                                  const char    *action,
                                                                  guint          timestamp);
 static void     _g_application_platform_activate                (const char    *appid,
-								 GVariant      *data) G_GNUC_NORETURN;
+                                                                 GVariant      *data) G_GNUC_NORETURN;
 static void     _g_application_platform_on_actions_changed      (GApplication  *app);
 
 #ifdef G_OS_UNIX
@@ -148,11 +152,11 @@ _g_application_validate_id (const char *id)
   for (; *id; id++)
     {
       if (g_ascii_isalnum (*id) || (*id == '-') || (*id == '_'))
-	allow_dot = TRUE;
+        allow_dot = TRUE;
       else if (allow_dot && *id == '.')
-	allow_dot = FALSE;	
+        allow_dot = FALSE;
       else
-	return FALSE;
+        return FALSE;
     }
   return TRUE;
 }
@@ -208,18 +212,18 @@ _g_application_handle_activation (const char *appid)
   if (construct_data)
     {
       for (i = 1; i < construct_data->argc; i++)
-	{
-	  int j;
-	  guint8 *argv_bytes;
-
-	  g_variant_builder_open (&builder, G_VARIANT_TYPE ("ay"));
-
-	  argv_bytes = (guint8*) construct_data->argv[i];
-	  for (j = 0; argv_bytes[j]; j++)
-	    g_variant_builder_add_value (&builder,
-					 g_variant_new_byte (argv_bytes[j]));
-	  g_variant_builder_close (&builder);
-	}
+        {
+          int j;
+          guint8 *argv_bytes;
+
+          g_variant_builder_open (&builder, G_VARIANT_TYPE ("ay"));
+
+          argv_bytes = (guint8*) construct_data->argv[i];
+          for (j = 0; argv_bytes[j]; j++)
+            g_variant_builder_add_value (&builder,
+                                         g_variant_new_byte (argv_bytes[j]));
+          g_variant_builder_close (&builder);
+        }
     }
   g_variant_builder_close (&builder);
 
@@ -289,9 +293,9 @@ g_application_action_free (gpointer data)
  * Since: 2.26
  */
 GApplication *
-g_application_new (int                argc,
-		   char             **argv,
-		   const char        *appid)
+g_application_new (int          argc,
+                   char       **argv,
+                   const char  *appid)
 {
   GApplication *app;
   GApplicationConstructionData construct_data;
@@ -317,6 +321,7 @@ g_application_new (int                argc,
  * @argc: Argument vector length
  * @argv: (allow-none): Argument vector
  * @appid: System-dependent application identifier
+ * @subtype: The type of the subclass to instantiate
  * @plugin: Structure containing callbacks for subclasses to override behavior
  *
  * This function is similar to g_application_new(), but includes a
@@ -328,11 +333,11 @@ g_application_new (int                argc,
  * Skip:
  */
 GApplication *
-g_application_new_subtype  (int                       argc,
-			    char                    **argv,
-			    const char               *appid,
-			    GType                     subtype,
-			    const GApplicationPlugin *plugin)
+g_application_new_subtype  (int                        argc,
+                            char                     **argv,
+                            const char                *appid,
+                            GType                      subtype,
+                            const GApplicationPlugin  *plugin)
 {
   GApplication *app;
   GApplicationConstructionData construct_data;
@@ -795,7 +800,7 @@ g_application_constructor  (GType                  type,
   if (!_g_application_platform_acquire_single_instance (appid, NULL))
     {
       if (default_quit)
-	_g_application_handle_activation (appid);
+        _g_application_handle_activation (appid);
       else
         is_remote = TRUE;
     }
diff --git a/gio/gapplication.h b/gio/gapplication.h
index 4a956f9..73126db 100644
--- a/gio/gapplication.h
+++ b/gio/gapplication.h
@@ -44,7 +44,6 @@ typedef struct _GApplication            GApplication;
 typedef struct _GApplicationPrivate     GApplicationPrivate;
 typedef struct _GApplicationClass       GApplicationClass;
 typedef struct _GApplicationPlugin      GApplicationPlugin;
-typedef struct _GApplicationArguments   GApplicationArguments;
 
 /**
  * GApplication:
@@ -103,21 +102,20 @@ struct _GApplicationClass
 
 /**
  * GApplicationPlugin:
- *
- * The #GApplicationPlugin structure allows subclasses of
- * #GApplication to influence low-level behavior.  This
- * should generally not be used by application authors.
- *
  * @format_activation_data: Invoked when another process for this
- * application exists.  The callback will be invoked in the context of
- * the non-primary process.  This allows environmental data such as
- * windowing system event data to be sent to the primary process.
- * Handlers for this signal should assume @builder has been opened for
- * an "a{sv}" type, and thus only append "sv" elements.
+ *     application exists.  The callback will be invoked in the context of
+ *     the non-primary process.  This allows environmental data such as
+ *     windowing system event data to be sent to the primary process.
+ *     Handlers for this signal should assume @builder has been opened for
+ *     an "a{sv}" type, and thus only append "sv" elements.
  * @receive_activation_data: Invoked when a non-primary process for
- * this application is invoked.  This callback is invoked in the
- * context of the primary process, and will be passed environmental
- * data gathered from the @format_activation_data callback.
+ *     this application is invoked.  This callback is invoked in the
+ *     context of the primary process, and will be passed environmental
+ *     data gathered from the @format_activation_data callback.
+ *
+ * The <structname>GApplicationPlugin</structname> structure allows
+ * subclasses of #GApplication to influence low-level behavior.
+ * This should generally not be used by application authors.
  *
  * Since: 2.26
  */