From: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Date: Tue, 19 May 2015 16:11:50 +0000 (-0400)
Subject: Add notification documentation
X-Git-Tag: v2.0.0-pre1~880
X-Git-Url: http://git.efficios.com/?a=commitdiff_plain;h=611c29fb84107322f4ff9830e41c6069ca84a30a;p=babeltrace.git

Add notification documentation

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
---

diff --git a/include/babeltrace/plugin/notification/eot.h b/include/babeltrace/plugin/notification/eot.h
new file mode 100644
index 00000000..e69de29b
diff --git a/include/babeltrace/plugin/notification/notification.h b/include/babeltrace/plugin/notification/notification.h
index 6db3a503..a15fde6a 100644
--- a/include/babeltrace/plugin/notification/notification.h
+++ b/include/babeltrace/plugin/notification/notification.h
@@ -35,16 +35,48 @@ extern "C" {
 
 struct bt_notification;
 
+/**
+ * Notification types. Unhandled notification types should be ignored.
+ */
 enum bt_plugin_notification_type {
 	BT_PLUGIN_NOTIFICATION_TYPE_UNKNOWN = -1,
-	BT_PLUGIN_NOTIFICATION_TYPE_EVENT = 0, /* see notification/event.h */
-	BT_PLUGIN_NOTIFICATION_TYPE_EVENTS_DISCARDED = 0, /* see notification/events-discarded.h */
+
+	/** Event delivery notification, see event.h */
+	BT_PLUGIN_NOTIFICATION_TYPE_EVENT = 0,
+
+	/** New stream packet notification, see packet.h */
+	BT_PLUGIN_NOTIFICATION_TYPE_NEW_PACKET = 1,
+
+	/** End of trace notification, see eot.h */
+	BT_PLUGIN_NOTIFICATION_TYPE_EOT = 2,
 };
 
+/**
+ * Get a notification's type.
+ *
+ * @param notification	Notification instance
+ * @returns		One of #bt_plugin_notification_type
+ */
 enum bt_plugin_notification_type bt_plugin_notification_get_type(
 		struct bt_plugin_notification *notification);
 
+/**
+ * Increments the reference count of \p notifiaction.
+ *
+ * @param notification	Notification of which to increment the reference count
+ *
+ * @see bt_plugin_notification_put()
+ */
 void bt_plugin_notification_get(struct bt_plugin_notification *notification);
+
+/**
+ * Decrements the reference count of \p notification, destroying it when this
+ * count reaches 0.
+ *
+ * @param notification	Notification of which to decrement the reference count
+ *
+ * @see bt_plugin_notification_get()
+ */
 void bt_plugin_notification_put(struct bt_plugin_notification *notification);
 
 #ifdef __cplusplus
diff --git a/include/babeltrace/plugin/notification/packet.h b/include/babeltrace/plugin/notification/packet.h
new file mode 100644
index 00000000..e69de29b