added: some doxygen for the new circular cache

2 files changed, 30 insertions, 6 deletions

diff --git a/xbmc/filesystem/CacheCircular.cpp b/xbmc/filesystem/CacheCircular.cpp
index 3e446963c0..85ba15968d 100644
--- a/xbmc/filesystem/CacheCircular.cpp
+++ b/xbmc/filesystem/CacheCircular.cpp
@@ -77,6 +77,25 @@ int CCacheCircular::Close()
   return CACHE_RC_OK;
 }
 
+/**
+ * Function will write to m_buf at m_end % m_size location
+ * it will write at maximum m_size, but it will only write
+ * as much it can without wrapping around in the buffer
+ *
+ * It will always leave m_size_back of the backbuffer intact
+ * but if the back buffer is less than that, that space is
+ * usable to write.
+ *
+ * If back buffer is filled to an larger extent than
+ * m_size_back, it will allow it to be overwritten
+ * until only m_size_back data remains.
+ *
+ * The following always apply:
+ *  * m_end <= m_cur <= m_end
+ *  * m_end - m_beg <= m_size
+ *
+ * Multiple calls may be needed to fill buffer completely.
+ */
 int CCacheCircular::WriteToCache(const char *buf, size_t len)
 {
   CSingleLock lock(m_sync);
@@ -107,6 +126,11 @@ int CCacheCircular::WriteToCache(const char *buf, size_t len)
   return len;
 }
 
+/**
+ * Reads data from cache. Will only read up till
+ * the buffer wrap point. So multiple calls
+ * may be needed to empty the whole cache
+ */
 int CCacheCircular::ReadFromCache(char *buf, size_t len)
 {
   CSingleLock lock(m_sync);
diff --git a/xbmc/filesystem/CacheCircular.h b/xbmc/filesystem/CacheCircular.h
index b27db704a9..237bb9a746 100644
--- a/xbmc/filesystem/CacheCircular.h
+++ b/xbmc/filesystem/CacheCircular.h
@@ -45,12 +45,12 @@ public:
     virtual void Reset(int64_t pos) ;
 
 protected:
-    uint64_t          m_beg;
-    uint64_t          m_end;
-    uint64_t          m_cur;
-    uint8_t          *m_buf;
-    size_t            m_size;
-    size_t            m_size_back;
+    uint64_t          m_beg;       /**< index in file (not buffer) of beginning of valid data */
+    uint64_t          m_end;       /**< index in file (not buffer) of end of valid data */
+    uint64_t          m_cur;       /**< current reading index in file */
+    uint8_t          *m_buf;       /**< buffer holding data */
+    size_t            m_size;      /**< size of data buffer used (m_buf) */
+    size_t            m_size_back; /**< guaranteed size of back buffer (actual size can be smaller, or larger if front buffer doesn't need it) */
     CCriticalSection  m_sync;
     CEvent            m_written;
 #ifdef _WIN32