docs: Move documentation to inline comments: notification

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

2 files changed, 52 insertions, 2 deletions

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);