From 4b6eadd95637098833766fdebd41f5194ca2f362 Mon Sep 17 00:00:00 2001
From: Casey Link <unnamedrambler@gmail.com>
Date: Fri, 13 Apr 2012 15:10:19 -0500
Subject: [PATCH] Add documentation to cache

---
 src/libtomahawk/utils/tomahawkcache.h | 37 ++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/src/libtomahawk/utils/tomahawkcache.h b/src/libtomahawk/utils/tomahawkcache.h
index 6fa16d4c2..aef172860 100644
--- a/src/libtomahawk/utils/tomahawkcache.h
+++ b/src/libtomahawk/utils/tomahawkcache.h
@@ -29,6 +29,9 @@
 
 namespace TomahawkUtils {
 
+/**
+ * Internal data structure. Don't use.
+ */
 struct CacheData {
     CacheData(){}
     CacheData( qint64 maxAg, QVariant dat )
@@ -36,10 +39,19 @@ struct CacheData {
     , data( dat )
     {}
 
-    qint64 maxAge;
+    qint64 maxAge; //!< milliseconds
     QVariant data;
 };
 
+/**
+ * A simple generic cache for anyone to use.
+ *
+ * Data is segmented according to clients, which specify
+ * a client identifier.
+ *
+ * Structure is a basic key-value store with associated max lifetime in
+ * milliseconds.
+ */
 class DLLEXPORT Cache : public QObject
 {
 Q_OBJECT
@@ -48,7 +60,21 @@ public:
     static Cache* instance();
     virtual ~Cache();
 
+    /**
+     * Store data in the cache.
+     * @param identifier your unique identifier, used to segment your data.
+     * @param maxAge lifetime of data in milliseconds (e.g, 3600000 = 1 hour)
+     * @param key the key to store the data
+     * @param value the data to store
+     */
     void putData( const QString &identifier, qint64 maxAge, const QString &key, const QVariant& value );
+
+    /**
+     * Retrieve data from the cache.
+     * @param identifier your unique identifier, used to segment your data.
+     * @param key the key to store the data
+     * @return the data, if found, if not found an invalid QVariant is returned.
+     */
     QVariant getData( const QString &identifier, const QString &key );
 
 private slots:
@@ -58,7 +84,16 @@ private:
     Cache();
     static Cache* s_instance;
 
+    /**
+     * Adds a client to the manifest.
+     * Does not lock the mutex.
+     */
     void addClient( const QString &identifier );
+
+    /**
+     * Removes a client to the manifest.
+     * Does not lock the mutex.
+     */
     void removeClient( const QString &identifier );
 
     QString m_cacheBaseDir;