From 1d7b78714b5cda26bee0ca04ba27b6416699b80c Mon Sep 17 00:00:00 2001
From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?=
 <jeremie.galarneau@efficios.com>
Date: Fri, 15 May 2015 13:44:38 -0400
Subject: [PATCH] Add notification iterator documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
---
 .../babeltrace/plugin/notification/iterator.h | 99 ++++++++++++++++++-
 1 file changed, 95 insertions(+), 4 deletions(-)

diff --git a/include/babeltrace/plugin/notification/iterator.h b/include/babeltrace/plugin/notification/iterator.h
index b40abcf1..51247d18 100644
--- a/include/babeltrace/plugin/notification/iterator.h
+++ b/include/babeltrace/plugin/notification/iterator.h
@@ -36,16 +36,107 @@ extern "C" {
 struct bt_notification;
 struct bt_notification_iterator;
 
-extern enum bt_notification_iterator_status
-bt_notification_iterator_next(struct bt_notification_iterator *iterator);
+/**
+ * Status code. Errors are always negative.
+ */
+enum bt_notification_iterator_status {
+	/** Invalid arguments. */
+	/* -22 for compatibility with -EINVAL */
+	BT_NOTIFICATION_ITERATOR_STATUS_EINVAL = -22,
+
+	/** End of trace. */
+	BT_NOTIFICATION_ITERATOR_STATUS_EOT = -3,
+
+	/** General error. */
+	BT_NOTIFICATION_ITERATOR_STATUS_ERROR = -2,
+
+	/** Unsupported iterator feature. */
+	BT_NOTIFICATION_ITERATOR_STATUS_UNSUPPORTED = -1,
+
+	/** No error, okay. */
+	BT_NOTIFICATION_ITERATOR_STATUS_OK = 0,
+};
+
+enum bt_notification_iterator_seek_type {
+	/** Seek at a time relative to the beginning of the trace. */
+	BT_NOTIFICATION_ITERATOR_SEEK_TYPE_BEGIN = 0,
+
+	/** Seek at a time relative to the current position */
+	BT_NOTIFICATION_ITERATOR_SEEK_TYPE_CURRENT = 1,
 
+	/** Seek at a absolute time */
+	BT_NOTIFICATION_ITERATOR_SEEK_TYPE_SET = 2,
+};
+
+/**
+ * Get current notification at iterator's position.
+ *
+ * This functions will <b>not</b> advance the cursor's position.
+ * The returned notification's reference count is already incremented.
+ *
+ * @param Iterator	Iterator instance
+ * @returns		Returns a bt_notification instance
+ *
+ * @see bt_notification_put()
+ */
 extern struct bt_notification *bt_notification_iterator_get_notification(
 		struct bt_notification_iterator *iterator);
 
-extern void bt_notification_iterator_get(struct bt_notification_iterator *iterator);
-extern void bt_notification_iterator_put(struct bt_notification_iterator *iterator);
+/**
+ * Advance the iterator's position forward.
+ *
+ * This function can be called repeatedly to iterate through the iterator's
+ * associated trace.
+ *
+ * @param iterator	Iterator instance
+ * @returns		Returns a bt_notification instance
+ *
+ * @see bt_notification_iterator_get_notification()
+ */
+extern enum bt_notification_iterator_status
+bt_notification_iterator_next(struct bt_notification_iterator *iterator);
+
+/**
+ * Seek iterator to position.
+ *
+ * Sets the iterator's position for the trace associated with the iterator.
+ * The new position is computed by adding \p time to the position specified
+ * by \p whence.
+ *
+ * @param iterator	Iterator instance
+ * @param whence	One of #bt_notification_iterator_seek_type values.
+ * @returns		One of #bt_notification_iterator_status values;
+ *			if \iterator does not support seeking,
+ *			#BT_NOTIFICATION_ITERATOR_STATUS_UNSUPPORTED is
+ *			returned.
+ *
+ * @see bt_notification_iterator_get_notification()
+ */
+extern enum bt_notification_iterator_status *bt_notification_iterator_seek(
+		struct bt_notification_iterator *iterator,
+		int whence,
+		int64_t time);
 
+/**
+ * Increments the reference count of \p iterator.
+ *
+ * @param iterator	Iterator of which to increment the reference count
+ *
+ * @see bt_notification_iterator_put()
+ */
+extern void bt_notification_iterator_get(
+		struct bt_notification_iterator *iterator);
 
+/**
+ * Decrements the reference count of \p iterator, destroying it when this
+ * count reaches 0.
+ *
+ * @param iterator	Iterator of which to decrement the reference count
+ *
+ * @see bt_notification_iterator_get()
+ */
+extern void bt_notification_iterator_put(
+		struct bt_notification_iterator *iterator);
 
 #ifdef __cplusplus
 }
-- 
2.34.1