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 f2bbf42de4b338303924b4e5188f87ddaab3caf9..cc970954d22929e923127ea9693e229fc7f47968 100644 (file)
--- 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 3183c86ef9498f8ab46dab65c894f2248500fae6..1d65a1176b04b001b05983cdd59c3230eb98fa6d 100644 (file)
--- 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 d03520bc1689d1f8f57d1c197a0b9124878c6f2b..f584326e20a8aaf65c8729d79e4348c4b11ccc9b 100644 (file)
--- 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 ffee9d2c61c447a1ab43e7b832dd88ad66855d20..61f78a0bdcd4becb607ed50765a9e78d11b98342 100644 (file)
--- 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 ec6e06106cd307057147526137fa4b6c9a1c62ce..4add2325dab0b5275fdbd90fc186729c30c8dbbc 100644 (file)
--- 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
  *