From fbf9bb9e644a54fca7b001bd287d32405c2e0a9f Mon Sep 17 00:00:00 2001
From: Yasuyuki Tanaka <yasuyuki.tanaka@inf.ethz.ch>
Date: Wed, 11 Jan 2017 21:42:39 +0100
Subject: [PATCH] ringbufindex: explain return values by the APIs

---
 core/lib/ringbufindex.h | 69 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 58 insertions(+), 11 deletions(-)

diff --git a/core/lib/ringbufindex.h b/core/lib/ringbufindex.h
index 722676b49..6fa07b966 100644
--- a/core/lib/ringbufindex.h
+++ b/core/lib/ringbufindex.h
@@ -48,25 +48,72 @@ struct ringbufindex {
   uint8_t put_ptr, get_ptr;
 };
 
-/* Initialize a ring buffer. The size must be a power of two */
+/**
+ * \brief Initialize a ring buffer. The size must be a power of two
+ * \param r Pointer to ringbufindex
+ * \param size Size of ring buffer
+ */
 void ringbufindex_init(struct ringbufindex *r, uint8_t size);
-/* Put one element to the ring buffer */
+
+/**
+ * \brief Put one element to the ring buffer
+ * \param r Pointer to ringbufindex
+ * \retval 0 Failure; the ring buffer is full
+ * \retval 1 Success; an element is added
+ */
 int ringbufindex_put(struct ringbufindex *r);
-/* Check if there is space to put an element.
- * Return the index where the next element is to be added */
+
+/**
+ * \brief Check if there is space to put an element.
+ * \param r Pinter to ringbufindex
+ * \retval >= 0 The index where the next element is to be added.
+ * \retval -1 Failure; the ring buffer is full
+ */
 int ringbufindex_peek_put(const struct ringbufindex *r);
-/* Remove the first element and return its index */
+
+/**
+ * \brief Remove the first element and return its index
+ * \param r Pinter to ringbufindex
+ * \retval >= 0 The index of the first element
+ * \retval -1 No element in the ring buffer
+ */
 int ringbufindex_get(struct ringbufindex *r);
-/* Return the index of the first element
- * (which will be removed if calling ringbufindex_get) */
+
+/**
+ * \brief Return the index of the first element which will be removed if calling
+ *        ringbufindex_get.
+ * \param r Pinter to ringbufindex
+ * \retval >= 0 The index of the first element
+ * \retval -1 No element in the ring buffer
+ */
 int ringbufindex_peek_get(const struct ringbufindex *r);
-/* Return the ring buffer size */
+
+/**
+ * \brief Return the ring buffer size
+ * \param r Pinter to ringbufindex
+ * \return The size of the ring buffer
+ */
 int ringbufindex_size(const struct ringbufindex *r);
-/* Return the number of elements currently in the ring buffer */
+
+/**
+ * \brief Return the number of elements currently in the ring buffer.
+ * \param r Pinter to ringbufindex
+ * \return The number of elements in the ring buffer
+ */
 int ringbufindex_elements(const struct ringbufindex *r);
-/* Is the ring buffer full? */
+
+/**
+ * \brief Is the ring buffer full?
+ * \retval 0 Not full
+ * \retval 1 Full
+ */
 int ringbufindex_full(const struct ringbufindex *r);
-/* Is the ring buffer empty? */
+
+/**
+ * \brief Is the ring buffer empty?
+ * \retval 0 Not empty
+ * \retval 1 Empty
+ */
 int ringbufindex_empty(const struct ringbufindex *r);
 
 #endif /* __RINGBUFINDEX_H__ */