[glib/wip/gapplication] application: Fix documentation and header style

[Emmanuele Bassi <ebassi src gnome org>]

commit bc9e15f82ba436851d10fb1fca6b3f859e657226
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Tue May 18 11:51:14 2010 +0100

    application: Fix documentation and header style

 gio/gapplication.c |  195 ++++++++++++++++++++++++++++++++++++++--------------
 gio/gapplication.h |   22 +++---
 2 files changed, 154 insertions(+), 63 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index 5973287..cfd66e5 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -25,6 +25,7 @@
 
 #include "gapplication.h"
 #include "gio-marshal.h"
+#include "glibintl.h"
 
 #include "gioalias.h"
 
@@ -190,7 +191,8 @@ g_application_new (const char        *appid,
  * g_application_try_new:
  * @flags: Application flags
  * @type: Actual GObject class type to instantiate
- * @on_other_process_exists: (scope call) (allow-none): Called if this application is already running
+ * @on_other_process_exists: (scope call) (allow-none): Called if this
+ *   application is already running
  * @user_data: (closure): User data
  * @n_parameters: Number of object construction parameters
  * @args: (array length=8): Object construction parameters
@@ -235,75 +237,142 @@ g_application_try_new (GApplicationFlags   flags,
   return G_APPLICATION (g_object_newv (class_type, n_parameters, parameters));
 }
 
+/**
+ * g_application_add_action:
+ * @application: a #GApplication
+ * @name: the action name
+ * @description: the action description; can be a translatable
+ *   string
+ *
+ * Adds an action @name to the list of exported actions of @application.
+ *
+ * You can invoke an action using g_application_invoke_action().
+ *
+ * The newly added action is enabled by default; you can call
+ * g_application_set_action_enabled() to disable it.
+ *
+ * Since: 2.26
+ */
 void
-g_application_add_action (GApplication *app,
+g_application_add_action (GApplication *application,
                           const gchar  *name,
                           const gchar  *description)
 {
+  GApplicationPrivate *priv;
   GApplicationAction *action;
 
-  g_return_if_fail (G_IS_APPLICATION (app));
-  g_return_if_fail (g_hash_table_lookup (app->priv->actions, "name") == NULL);
+  g_return_if_fail (G_IS_APPLICATION (application));
+
+  priv = application->priv;
+
+  g_return_if_fail (g_hash_table_lookup (priv->actions, name) == NULL);
   
   action = g_slice_new (GApplicationAction);
   action->name = g_strdup (name);
   action->description = g_strdup (description);
   action->enabled = TRUE;
   
-  g_hash_table_insert (app->priv->actions, action->name, action);
-  queue_actions_change_notification (app);
+  g_hash_table_insert (priv->actions, action->name, action);
+  queue_actions_change_notification (application);
 }
 
-void 
-g_application_invoke_action (GApplication *app,
+/**
+ * g_application_invoke_action:
+ * @application: a #GApplication
+ * @name: the name of the action to invoke
+ * @timestamp: the timestamp that is going to be passed to
+ *   the #GApplication::action signal
+ *
+ * Invokes the action @name of the passed #GApplication.
+ *
+ * If the action exists and is enabled, the #GApplication::action
+ * signal will be emitted.
+ *
+ * Since: 2.26
+ */
+void
+g_application_invoke_action (GApplication *application,
                              const char   *name,
                              guint         timestamp)
 {
+  GApplicationPrivate *priv;
   GApplicationAction *action;
 
-  g_return_if_fail (G_IS_APPLICATION (app));
+  g_return_if_fail (G_IS_APPLICATION (application));
   g_return_if_fail (name != NULL);
-  
-  action = g_hash_table_lookup (app->priv->actions, name);
+
+  priv = application->priv;
+
+  action = g_hash_table_lookup (priv->actions, name);
   g_return_if_fail (action != NULL);
   if (!action->enabled)
     return;
   
-  g_signal_emit (app, application_signals[ACTION], g_quark_from_string (name), name, timestamp);
+  g_signal_emit (application, application_signals[ACTION],
+                 g_quark_from_string (name),
+                 name,
+                 timestamp);
 }
 
+/**
+ * g_application_set_action_enabled:
+ * @application: a #GApplication
+ * @name: the name of the application
+ * @enabled: whether to enable or disable the action @name
+ *
+ * Sets whether the action @name inside @application should be enabled
+ * or disabled.
+ *
+ * Invoking disabled actions will not result in the #GApplication::changed
+ * signal being emitted
+ *
+ * Since: 2.26
+ */
 void
-g_application_set_action_enabled (GApplication *app,
+g_application_set_action_enabled (GApplication *application,
                                   const char   *name,
                                   gboolean      enabled)
 {
   GApplicationAction *action;
 
-  g_return_if_fail (G_IS_APPLICATION (app));
+  g_return_if_fail (G_IS_APPLICATION (application));
   g_return_if_fail (name != NULL);
 
   enabled = !!enabled;
 
-  action = g_hash_table_lookup (app->priv->actions, name);
+  action = g_hash_table_lookup (application->priv->actions, name);
   g_return_if_fail (action != NULL);
   if (action->enabled == enabled)
     return;
 
   action->enabled = enabled;
 
-  queue_actions_change_notification (app);
+  queue_actions_change_notification (application);
 }
 
+/**
+ * g_application_get_action_enabled:
+ * @application: a #GApplication
+ * @name: the name of the action
+ *
+ * Retrieves whether the action @name is enabled or not.
+ *
+ * See g_application_set_action_enabled().
+ *
+ * Return value: %TRUE if the action was enabled, and %FALSE otherwise
+ *
+ * Since: 2.26
+ */
 gboolean
-g_application_get_action_enabled (GApplication *app,
+g_application_get_action_enabled (GApplication *application,
                                   const char   *name)
 {
   GApplicationAction *action;
 
-  g_return_val_if_fail (G_IS_APPLICATION (app), FALSE);
+  g_return_val_if_fail (G_IS_APPLICATION (application), FALSE);
   g_return_val_if_fail (name != NULL, FALSE);
 
-  action = g_hash_table_lookup (app->priv->actions, name);
+  action = g_hash_table_lookup (application->priv->actions, name);
   g_return_val_if_fail (action != NULL, FALSE);
 
   return action->enabled;
@@ -311,17 +380,21 @@ g_application_get_action_enabled (GApplication *app,
 
 /**
  * g_application_run:
- * @app: a #GApplication
+ * @application: a #GApplication
+ *
+ * Starts the application.
+ *
+ * The default implementation of this virtual function will simply run
+ * a main loop.
  *
- * Start the application.  The default implementation of this
- * virtual function will simply run a main loop.
+ * Since: 2.26
  */
 void
-g_application_run (GApplication  *app)
+g_application_run (GApplication *application)
 {
-  g_return_if_fail (G_IS_APPLICATION (app));
+  g_return_if_fail (G_IS_APPLICATION (application));
   
-  G_APPLICATION_GET_CLASS (app)->run (app);
+  G_APPLICATION_GET_CLASS (application)->run (application);
 }
 
 /**
@@ -329,25 +402,35 @@ g_application_run (GApplication  *app)
  * @app: a #GApplication
  * @timestamp: Platform-specific event timestamp, may be 0 for default
  *
- * Request the application exit.  By default, this
- * method will exit the main loop.
+ * Request the application exit.
+ *
+ * The default implementation will exit the main loop created by
+ * g_application_run()
  *
  * Returns: %TRUE if the application accepted the request, %FALSE otherwise
+ *
+ * Since: 2.26
  */
 gboolean
-g_application_quit (GApplication *app, guint timestamp)
+g_application_quit (GApplication *application,
+                    guint         timestamp)
 {
-  gboolean retval;
+  gboolean retval = FALSE;
+
+  g_return_val_if_fail (G_IS_APPLICATION (application), FALSE);
 
-  g_signal_emit (app, application_signals[QUIT], 0, timestamp, &retval);
+  g_signal_emit (application, application_signals[QUIT], 0, timestamp, &retval);
 
   return retval;
 }
 
 /**
  * g_application_get_instance:
+ *
+ * Retrieves the singleton instance of #GApplication
  * 
- * Returns: (transfer none): The singleton instance of #GApplication, or %NULL if none
+ * Returns: (transfer none): The singleton instance of #GApplication,
+ *   or %NULL if none is set
  */
 GApplication *
 g_application_get_instance (void)
@@ -367,30 +450,32 @@ g_application_get_instance (void)
  * Since: 2.26
  */
 G_CONST_RETURN char *  
-g_application_get_id (GApplication *app)
+g_application_get_id (GApplication *application)
 {
-  g_return_val_if_fail (G_IS_APPLICATION (app), NULL);
+  g_return_val_if_fail (G_IS_APPLICATION (application), NULL);
 
-  return app->priv->appid;
+  return application->priv->appid;
 }
 
 /**
  * g_application_get_mainloop:
- * @app: a #GApplication
+ * @application: a #GApplication
  *
  * Retrieves the #GMainLoop associated with the #GApplication
  *
  * Return value: (transfer none): The #GMainLoop associated with
  *   this application
+ *
+ * Since: 2.26
  */
 GMainLoop *
-g_application_get_mainloop (GApplication *app)
+g_application_get_mainloop (GApplication *application)
 {
   GApplicationPrivate *priv;
 
-  g_return_val_if_fail (G_IS_APPLICATION (app), NULL);
+  g_return_val_if_fail (G_IS_APPLICATION (application), NULL);
 
-  priv = app->priv;
+  priv = application->priv;
 
   if (priv->mainloop == NULL)
     priv->mainloop = g_main_loop_new (NULL, TRUE);
@@ -404,7 +489,9 @@ g_application_init (GApplication *app)
   app->priv = G_TYPE_INSTANCE_GET_PRIVATE (app,
                                            G_TYPE_APPLICATION,
                                            GApplicationPrivate);
-  app->priv->actions = g_hash_table_new_full (g_str_hash, g_str_equal, NULL,
+
+  app->priv->actions = g_hash_table_new_full (g_str_hash, g_str_equal,
+                                              NULL,
                                               g_application_action_free);
   _g_application_platform_init (app);
 }
@@ -419,11 +506,12 @@ g_application_get_property (GObject    *object,
 
   switch (prop_id)
     {
-      case PROP_APPID:
-        g_value_set_string (value, g_application_get_id (app));
-        break;
-      default:
-        G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
+    case PROP_APPID:
+      g_value_set_string (value, g_application_get_id (app));
+      break;
+
+    default:
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
     }
 }
 
@@ -437,11 +525,12 @@ g_application_set_property (GObject      *object,
 
   switch (prop_id)
     {
-      case PROP_APPID:
-        app->priv->appid = g_value_dup_string (value);
-        break;
-      default:
-        G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
+    case PROP_APPID:
+      app->priv->appid = g_value_dup_string (value);
+      break;
+
+    default:
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
     }
 }
 
@@ -510,10 +599,12 @@ g_application_class_init (GApplicationClass *klass)
   g_object_class_install_property (gobject_class,
                                    PROP_APPID,
                                    g_param_spec_string ("appid",
-                                                        "Application ID",
-                                                        "Platform-specific identifer for this application",
+                                                        P_("Application ID"),
+                                                        P_("Platform-specific identifer for this application"),
                                                         NULL,
-                                                        G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
+                                                        G_PARAM_READWRITE |
+                                                        G_PARAM_CONSTRUCT_ONLY |
+                                                        G_PARAM_STATIC_STRINGS));
 }
 
 #define __G_APPLICATION_C__
diff --git a/gio/gapplication.h b/gio/gapplication.h
index 3722476..aecaa7f 100644
--- a/gio/gapplication.h
+++ b/gio/gapplication.h
@@ -53,7 +53,7 @@ typedef struct _GApplicationClass       GApplicationClass;
  *
  * Since: 2.26
  */
-typedef void (*GApplicationExistsCallback) (gpointer user_data);
+typedef void (* GApplicationExistsCallback) (gpointer user_data);
 
 /**
  * GApplicationFlags:
@@ -64,8 +64,7 @@ typedef void (*GApplicationExistsCallback) (gpointer user_data);
  *
  * Since: 2.26
  */
-typedef enum
-{
+typedef enum { /*< prefix=G_APPLICATION >*/
   G_APPLICATION_FLAGS_NONE = 0,
 
   G_APPLICATION_DISABLE_SINGLE_INSTANCE = 1 << 0
@@ -136,23 +135,24 @@ GApplication *          g_application_try_new                   (GApplicationFla
                                                                  GParameter         *parameters);
 
 GApplication *          g_application_get_instance              (void);
-G_CONST_RETURN gchar *  g_application_get_id                    (GApplication      *app);
+G_CONST_RETURN gchar *  g_application_get_id                    (GApplication      *application);
 
-void                    g_application_add_action                (GApplication      *app,
+void                    g_application_add_action                (GApplication      *application,
                                                                  const char        *name,
                                                                  const char        *description);
-void                    g_application_set_action_enabled        (GApplication      *app,
+void                    g_application_set_action_enabled        (GApplication      *application,
                                                                  const char        *name,
                                                                  gboolean           enabled);
-gboolean                g_application_get_action_enabled        (GApplication      *app,
+gboolean                g_application_get_action_enabled        (GApplication      *application,
                                                                  const char        *name);
-void                    g_application_invoke_action             (GApplication      *app,
+void                    g_application_invoke_action             (GApplication      *application,
                                                                  const char        *name,
                                                                  guint              timestamp);
 
-GMainLoop *             g_application_get_mainloop              (GApplication      *app);
-void                    g_application_run                       (GApplication      *app);             
-gboolean                g_application_quit                      (GApplication      *app, guint timestamp);
+GMainLoop *             g_application_get_mainloop              (GApplication      *application);
+void                    g_application_run                       (GApplication      *application);
+gboolean                g_application_quit                      (GApplication      *app,
+                                                                 guint              timestamp);
 
 G_END_DECLS