From: Ryan Lortie <desrt@desrt.ca>
Date: Mon, 21 Oct 2013 18:29:44 +0000 (-0400)
Subject: GNotification: finish documentation
X-Git-Tag: 2.39.0~28
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6957004007fb2a5faf0013e6ec44926d841404b5;p=platform%2Fupstream%2Fglib.git

GNotification: finish documentation

Add the missing documentation and add the section to the GIO reference
docs.  Fix up a few small documentation issues.

https://bugzilla.gnome.org/show_bug.cgi?id=688492
---

diff --git a/docs/reference/gio/Makefile.am b/docs/reference/gio/Makefile.am
index f2bbf42..cc97095 100644
--- a/docs/reference/gio/Makefile.am
+++ b/docs/reference/gio/Makefile.am
@@ -59,6 +59,8 @@ IGNORE_HFILES = \
 	gnetworkingprivate.h		\
 	gnetworkmonitorbase.h		\
 	gnetworkmonitornetlink.h	\
+	gnotificationbackend.h		\
+	gnotification-private.h		\
 	gpollfilemonitor.h		\
 	gregistrysettingsbackend.h	\
 	gsettingsbackendinternal.h	\
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index 3183c86..1d65a11 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -223,6 +223,7 @@
         <xi:include href="xml/gmenu.xml"/>
         <xi:include href="xml/gmenuexporter.xml"/>
         <xi:include href="xml/gdbusmenumodel.xml"/>
+        <xi:include href="xml/gnotification.xml"/>
     </chapter>
     <chapter id="extending">
         <title>Extending GIO</title>
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index d03520b..f584326 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -2980,6 +2980,9 @@ g_application_quit
 g_application_activate
 g_application_open
 <SUBSECTION>
+g_application_send_notification
+g_application_withdraw_notification
+<SUBSECTION>
 g_application_run
 g_application_set_default
 g_application_get_default
@@ -4150,3 +4153,29 @@ G_SUBPROCESS_LAUNCHER
 G_TYPE_SUBPROCESS_LAUNCHER
 g_subprocess_launcher_get_type
 </SECTION>
+
+<SECTION>
+<FILE>gnotification</FILE>
+<TITLE>GNotification</TITLE>
+GNotification
+g_notification_new
+<SUBSECTION>
+g_notification_set_title
+g_notification_set_body
+g_notification_set_icon
+g_notification_set_urgent
+<SUBSECTION>
+g_notification_set_default_action
+g_notification_set_default_action_and_target
+g_notification_set_default_action_and_target_value
+<SUBSECTION>
+g_notification_add_button
+g_notification_add_button_with_target
+g_notification_add_button_with_target_value
+<SUBSECTION Standard>
+G_IS_NOTIFICATION
+G_NOTIFICATION
+G_TYPE_NOTIFICATION
+G_TYPE_NOTIFICATION_BACKEND
+g_notification_get_type
+</SECTION>
diff --git a/gio/giotypes.h b/gio/giotypes.h
index ffee9d2..61f78a0 100644
--- a/gio/giotypes.h
+++ b/gio/giotypes.h
@@ -62,7 +62,6 @@ typedef struct _GSettings                     GSettings;
 typedef struct _GPermission                   GPermission;
 
 typedef struct _GMenuModel                    GMenuModel;
-typedef struct _GNotificationBackend          GNotificationBackend;
 typedef struct _GNotification                 GNotification;
 
 /**
diff --git a/gio/gnotification.c b/gio/gnotification.c
index ec6e061..4add232 100644
--- a/gio/gnotification.c
+++ b/gio/gnotification.c
@@ -26,6 +26,44 @@
 #include "gicon.h"
 #include "gaction.h"
 
+/**
+ * SECTION:gnotification
+ * @short_description: User Notifications (pop up messages)
+ *
+ * #GNotification is a mechanism for creating a notification to be shown
+ * to the user -- typically as a pop-up notification presented by the
+ * desktop environment shell.
+ *
+ * The key difference between #GNotification and other similar APIs is
+ * that, if supported by the desktop environment, notifications sent
+ * with #GNotification will persist after the application has exited,
+ * and even across system reboots.
+ *
+ * Since the user may click on a notification while the application is
+ * not running, applications using #GNotification should be able to be
+ * started as a D-Bus service, using #GApplication.
+ *
+ * User interaction with a notification (either the default action, or
+ * buttons) must be associated with actions on the application (ie:
+ * "app." actions).  It is not possible to route user interaction
+ * through the notification itself, because the object will not exist if
+ * the application is autostarted as a result of a notification being
+ * clicked.
+ *
+ * A notification can be sent with g_application_send_notification().
+ *
+ * Since: 2.40
+ **/
+
+/**
+ * GNotification:
+ *
+ * This structure type is private and should only be accessed using the
+ * public APIs.
+ *
+ * Since: 2.40
+ **/
+
 typedef GObjectClass GNotificationClass;
 
 struct _GNotification
@@ -131,7 +169,7 @@ g_notification_new (const gchar *title)
   return notification;
 }
 
-/**
+/*< private >
  * g_notification_get_title:
  * @notification: a #GNotification
  *
@@ -152,7 +190,7 @@ g_notification_get_title (GNotification *notification)
 /**
  * g_notification_set_title:
  * @notification: a #GNotification
- * title: the new title for @notification
+ * @title: the new title for @notification
  *
  * Sets the title of @notification to @title.
  *
@@ -170,7 +208,7 @@ g_notification_set_title (GNotification *notification,
   notification->title = g_strdup (title);
 }
 
-/**
+/*< private >
  * g_notification_get_body:
  * @notification: a #GNotification
  *
@@ -209,7 +247,7 @@ g_notification_set_body (GNotification *notification,
   notification->body = g_strdup (body);
 }
 
-/**
+/*< private >
  * g_notification_get_icon:
  * @notification: a #GNotification
  *
@@ -248,7 +286,7 @@ g_notification_set_icon (GNotification *notification,
   notification->icon = g_object_ref (icon);
 }
 
-/**
+/*< private >
  * g_notification_get_urgent:
  * @notification: a #GNotification
  *