docs: Move documentation to inline comments: notification

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

4 files changed, 53 insertions, 287 deletions

diff --git a/docs/reference/tmpl/.gitignore b/docs/reference/tmpl/.gitignore
new file mode 100644
index 0000000..e073b3b
--- /dev/null
+++ b/docs/reference/tmpl/.gitignore
@@ -0,0 +1 @@
+notification.sgml
diff --git a/docs/reference/tmpl/notification.sgml b/docs/reference/tmpl/notification.sgml
deleted file mode 100644
index c2093fd..0000000
--- a/docs/reference/tmpl/notification.sgml
+++ /dev/null
@@ -1,285 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-NotifyNotification
-
-<!-- ##### SECTION Short_Description ##### -->
-A passive pop-up notification.
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-#NotifyNotification represents a passive pop-up notification. It can
-contain summary text, body text, and an icon, as well as hints specifying
-how the notification should be presented. The notification is rendered
-by a notification daemon, and may present the notification in any number
-of ways. As such, there is a clear separation of content and presentation,
-and this API enforces that.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### MACRO NOTIFY_EXPIRES_DEFAULT ##### -->
-<para>
-The default expiration time on a notification.
-</para>
-
-
-
-<!-- ##### MACRO NOTIFY_EXPIRES_NEVER ##### -->
-<para>
-The notification never expires. It stays open until closed by the calling API
-or the user.
-</para>
-
-
-
-<!-- ##### STRUCT NotifyNotification ##### -->
-<para>
-This is an opaque structure representing a notification. This should
-not be used directly. Use the accessor functions below.
-</para>
-
-
-<!-- ##### SIGNAL NotifyNotification::closed ##### -->
-<para>
-
-</para>
-
-@notifynotification: the object which received the signal.
-
-<!-- ##### ARG NotifyNotification:body ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG NotifyNotification:closed-reason ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG NotifyNotification:icon-name ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG NotifyNotification:id ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG NotifyNotification:summary ##### -->
-<para>
-
-</para>
-
-<!-- ##### ENUM NotifyUrgency ##### -->
-<para>
-The urgency level of the notification.
-</para>
-
-@NOTIFY_URGENCY_LOW: 
-	Low urgency. Used for unimportant notifications.
-@NOTIFY_URGENCY_NORMAL: 
-	Normal urgency. Used for most standard notifications.
-@NOTIFY_URGENCY_CRITICAL: 
-	Critical urgency. Used for very important notifications.
-
-<!-- ##### USER_FUNCTION NotifyActionCallback ##### -->
-<para>
-An action callback function.
-</para>
-
-@notification: 
-@action: 
-@user_data: 
-<!-- # Unused Parameters # -->
-@Param1: The notification.
-@Param2: The action ID.
-@Param3: User data.
-
-
-<!-- ##### MACRO NOTIFY_ACTION_CALLBACK ##### -->
-<para>
-A convenience macro for casting a function to a #NotifyActionCallback. This
-is much like G_CALLBACK().
-</para>
-
-@func: The function to cast.
-
-
-<!-- ##### FUNCTION notify_notification_new ##### -->
-<para>
-
-</para>
-
-@summary: 
-@body: 
-@icon: 
-@Returns: 
-
-
-<!-- ##### FUNCTION notify_notification_update ##### -->
-<para>
-
-</para>
-
-@notification: 
-@summary: 
-@body: 
-@icon: 
-@Returns: 
-
-
-<!-- ##### FUNCTION notify_notification_show ##### -->
-<para>
-
-</para>
-
-@notification: 
-@error: 
-@Returns: 
-
-
-<!-- ##### FUNCTION notify_notification_set_timeout ##### -->
-<para>
-
-</para>
-
-@notification: 
-@timeout: 
-
-
-<!-- ##### FUNCTION notify_notification_set_category ##### -->
-<para>
-
-</para>
-
-@notification: 
-@category: 
-
-
-<!-- ##### FUNCTION notify_notification_set_urgency ##### -->
-<para>
-
-</para>
-
-@notification: 
-@urgency: 
-
-
-<!-- ##### FUNCTION notify_notification_set_icon_from_pixbuf ##### -->
-<para>
-
-</para>
-
-@notification: 
-@icon: 
-
-
-<!-- ##### FUNCTION notify_notification_set_hint ##### -->
-<para>
-
-</para>
-
-@notification: 
-@key: 
-@value: 
-
-
-<!-- ##### FUNCTION notify_notification_set_hint_int32 ##### -->
-<para>
-
-</para>
-
-@notification: 
-@key: 
-@value: 
-
-
-<!-- ##### FUNCTION notify_notification_set_hint_double ##### -->
-<para>
-
-</para>
-
-@notification: 
-@key: 
-@value: 
-
-
-<!-- ##### FUNCTION notify_notification_set_hint_string ##### -->
-<para>
-
-</para>
-
-@notification: 
-@key: 
-@value: 
-
-
-<!-- ##### FUNCTION notify_notification_set_hint_byte ##### -->
-<para>
-
-</para>
-
-@notification: 
-@key: 
-@value: 
-
-
-<!-- ##### FUNCTION notify_notification_set_hint_byte_array ##### -->
-<para>
-
-</para>
-
-@notification: 
-@key: 
-@value: 
-@len: 
-
-
-<!-- ##### FUNCTION notify_notification_clear_hints ##### -->
-<para>
-
-</para>
-
-@notification: 
-
-
-<!-- ##### FUNCTION notify_notification_add_action ##### -->
-<para>
-
-</para>
-
-@notification: 
-@action: 
-@label: 
-@callback: 
-@user_data: 
-@free_func: 
-
-
-<!-- ##### FUNCTION notify_notification_clear_actions ##### -->
-<para>
-
-</para>
-
-@notification: 
-
-
-<!-- ##### FUNCTION notify_notification_close ##### -->
-<para>
-
-</para>
-
-@notification: 
-@error: 
-@Returns: 
-
-
diff --git a/libnotify/notification.c b/libnotify/notification.c
index 571eff6..2a2cb42 100644
--- a/libnotify/notification.c
+++ b/libnotify/notification.c
@@ -28,6 +28,21 @@
 #include "notify.h"
 #include "internal.h"
 
+
+/**
+ * SECTION:notification
+ * @Short_description: A passive pop-up notification.
+ * @Title: NotifyNotification
+ *
+ * #NotifyNotification represents a passive pop-up notification. It can
+ * contain summary text, body text, and an icon, as well as hints specifying
+ * how the notification should be presented. The notification is rendered
+ * by a notification daemon, and may present the notification in any number
+ * of ways. As such, there is a clear separation of content and presentation,
+ * and this API enforces that.
+ */
+
+
 #if !defined(G_PARAM_STATIC_NAME) && !defined(G_PARAM_STATIC_NICK) && \
     !defined(G_PARAM_STATIC_BLURB)
 # define G_PARAM_STATIC_NAME 0
diff --git a/libnotify/notification.h b/libnotify/notification.h
index b949365..453f176 100644
--- a/libnotify/notification.h
+++ b/libnotify/notification.h
@@ -29,7 +29,19 @@
 
 G_BEGIN_DECLS
 
+/**
+ * NOTIFY_EXPIRES_DEFAULT:
+ *
+ * The default expiration time on a notification.
+ */
 #define NOTIFY_EXPIRES_DEFAULT -1
+
+/**
+ * NOTIFY_EXPIRES_NEVER:
+ *
+ * The notification never expires. It stays open until closed by the calling API
+ * or the user.
+ */
 #define NOTIFY_EXPIRES_NEVER    0
 
 #define NOTIFY_TYPE_NOTIFICATION         (notify_notification_get_type ())
@@ -45,7 +57,9 @@ typedef struct _NotifyNotificationPrivate NotifyNotificationPrivate;
 
 struct _NotifyNotification
 {
+        /*< private >*/
         GObject                    parent_object;
+
         NotifyNotificationPrivate *priv;
 };
 
@@ -57,8 +71,14 @@ struct _NotifyNotificationClass
         void            (*closed) (NotifyNotification *notification);
 };
 
-/*
- * Notification urgency levels.
+
+/**
+ * NotifyUrgency:
+ * @NOTIFY_URGENCY_LOW: Low urgency. Used for unimportant notifications.
+ * @NOTIFY_URGENCY_NORMAL: Normal urgency. Used for most standard notifications.
+ * @NOTIFY_URGENCY_CRITICAL: Critical urgency. Used for very important notifications.
+ *
+ * The urgency level of the notification.
  */
 typedef enum
 {
@@ -68,10 +88,25 @@ typedef enum
 
 } NotifyUrgency;
 
+/**
+ * NotifyActionCallback:
+ * @notification:
+ * @action:
+ * @user_data:
+ *
+ * An action callback function.
+ */
 typedef void    (*NotifyActionCallback) (NotifyNotification *notification,
                                          char               *action,
                                          gpointer            user_data);
 
+/**
+ * NOTIFY_ACTION_CALLBACK:
+ * @func: The function to cast.
+ *
+ * A convenience macro for casting a function to a #NotifyActionCallback. This
+ * is much like G_CALLBACK().
+ */
 #define NOTIFY_ACTION_CALLBACK(func) ((NotifyActionCallback)(func))
 
 GType               notify_notification_get_type             (void);