From fa71e0e12acbe0d27a618b3cfe3fa6f98f6f64ff Mon Sep 17 00:00:00 2001
From: Hans Baier <hansfbaier@googlemail.com>
Date: Mon, 29 Dec 2008 00:19:12 +0000
Subject: [PATCH] * added a bit of documentation in an effort to understand the
 code

git-svn-id: svn://localhost/ardour2/branches/3.0@4355 d708f5d6-7413-0410-9779-e7cbd77b26cf
---
 libs/evoral/evoral/RingBuffer.hpp | 34 +++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/libs/evoral/evoral/RingBuffer.hpp b/libs/evoral/evoral/RingBuffer.hpp
index a27e97adb2..0d92043174 100644
--- a/libs/evoral/evoral/RingBuffer.hpp
+++ b/libs/evoral/evoral/RingBuffer.hpp
@@ -56,6 +56,8 @@ public:
 		g_atomic_int_set(&_read_ptr, 0);
 	}
 
+	/** Calculate remaining space for writing
+	 */
 	size_t write_space() const {
 		const size_t w = g_atomic_int_get(&_write_ptr);
 		const size_t r = g_atomic_int_get(&_read_ptr);
@@ -69,6 +71,8 @@ public:
 		}
 	}
 	
+	/** Calculate how much still can be read
+	 */
 	size_t read_space() const {
 		const size_t w = g_atomic_int_get(&_write_ptr);
 		const size_t r = g_atomic_int_get(&_read_ptr);
@@ -80,14 +84,44 @@ public:
 		}
 	}
 
+	/** Report the buffers size
+	 */
 	size_t capacity() const { return _size; }
 
+	/** Peek at the ringbuffer (read w/o advancing read pointer).
+	 * @return how much has been peeked (read cannot exceed the end 
+	 * of the buffer):
+	 * <pre>
+	 * |-------------------------R=============================|
+	 *            read-pointer---^
+	 * </pre>
+	 */
 	size_t peek(size_t size, T* dst);
+
+	/** Peek at the ringbuffer (read w/o advancing read pointer).
+	 * @return how much has been peeked (wraps around if read exceeds
+	 * the end of the buffer):
+	 * <pre>
+	 * |===========--------------R=============================|
+	 *            read-pointer---^
+	 * </pre>
+	 */
 	bool   full_peek(size_t size, T* dst);
 
+	/** Read from the ringbuffer. (advances read pointer)
+	 * @return how much has been read (read cannot exceed the end 
+	 * of the buffer):
+	 */
 	size_t read(size_t size, T* dst);
+
+	/** Read from the ringbuffer. (advances read pointer)
+	 * @return how much has been peeked (wraps around if read exceeds
+	 * the end of the buffer):
+	 */
 	bool   full_read(size_t size, T* dst);
 
+	/** Advance read pointer by size
+	 */
 	bool   skip(size_t size);
 	
 	void   write(size_t size, const T* src);