Index: Add more detailed documentation

This lets me remove this section of the DESIGN file.

Signed-off-by: Anna Schumaker <Anna@OcarinaProject.net>

DESIGN

@@ -66,72 +66,6 @@ Callbacks:
 
 
 
-Index:
-	An index is a special database used to map a std::string key to
-	multiple integer values.
-
-- IndexEntry:
-	class IndexEntry : public DatabaseEntry {
-	public:
-		const std::string key;
-		set<unsigned int> values;
-
-		IndexEntry(const std::string &);
-		const std::string primary_key() const;
-		void insert(unsigned int);
-		void remove(unsigned int);
-
-		void write(File &);
-		void read(File &);
-	};
-
-	File << key << endl;
-	File << values.size() << values[0] << .. << values[N] << endl;
-
-- IndexEntry API:
-	IndexEntry :: IndexEntry();
-		Creat an empty IndexEntry.
-
-	std::string IndexEntry :: primary_key() const;
-		return key;
-
-	void IndexEntry :: insert(unsigned int value);
-		Add value to the values set.
-
-	void IndexEntry :: remove(unsigned int value);
-		Remove value from the values set.
-
-	void IndexEntry :: write(File &f);
-		Write the values set to a file.
-
-	void IndexEntry :: read(File &f);
-		Read values from a file.
-
-- Index:
-	class Index : public Database<IndexEntry> {
-	public:
-		Index(const std::string &, bool);
-
-		void insert(const std::string &, unsigned int);
-		void remove(const std::string &, unsigned int);
-	};
-
-- Index API:
-	Index :: Index(const std::string &filepath, bool autosave);
-		Pass values on to the Database constructor.
-
-	void Index :: insert(const std::string &key, unsigned int value);
-		Create an IndexEntry for key if one does not exist yet.
-		Insert value into the IndexEntry corresponding to key.
-		If autosave is enabled, save().
-
-	void Index :: remove(const std::string &key, unsigned int value);
-		Remove value from the IndexEntry corresponding to key.  Do not
-		remove the IndexEntry, even if it is empty.
-		If autosave is enabled, save().
-
-
-
 Filter:
 	Filtering is used to generate a subset of songs displayed by the UI to
 	that users can choose from.  The inverted index is generated at startup

core/index.cpp

@@ -70,23 +70,23 @@ Index :: Index(const std::string &filepath, bool autosave)
 	: Database(filepath, autosave)
 {}
 
-void Index :: insert(const std::string &key, unsigned int val)
+void Index :: insert(const std::string &key, unsigned int value)
 {
 	IndexEntry *it = find(key);
 	if (it == NULL)
 		it = Database :: insert(IndexEntry(key));
 
-	it->insert(val);
+	it->insert(value);
 	autosave();
 }
 
-void Index :: remove(const std::string &key, unsigned int val)
+void Index :: remove(const std::string &key, unsigned int value)
 {
 	IndexEntry *it = find(key);
 
 	if (it == NULL)
 		return;
 
-	it->remove(val);
+	it->remove(value);
 	autosave();
 }

include/core/index.h

@@ -101,27 +101,35 @@ public:
 
 
 /**
- * A special Database for index access.
+ * An Index is a special Database for mapping std::strings to a std::set of
+ * integer  identifiers.
  */
 class Index : public Database<IndexEntry> {
 public:
 	/**
-	 * Index constructor.
+	 * Index constructor.  This simply passes the filepath and autosave
+	 * parameters to the Database constructor.
+	 *
 	 * @param  filepath  Where to store the file on disk.
 	 * @param  autosave  True if changes should automatically be saved.
 	 */
 	Index(const std::string &, bool);
 
 	/**
-	 * Add a new (key, value) pair to the index.
-	 * @param  key  String to store in the index.
+	 * Check if we already have an IndexEntry for key, and create one if
+	 * we don't.  Insert value into the found or created IndexEntry and
+	 * call autosave() to save the Index.
+	 *
+	 * @param  key    String to store in the index.
 	 * @param  value  Integer value associated with the key.
 	 */
 	void insert(const std::string &, unsigned int);
 
 	/**
-	 * Remove a (key, value) pair from the index.
-	 * @param  key  Key associated with the value to be removed.
+	 * Remove value from the IndexEntry corresponding to key.  The
+	 * IndexEntry will not be removed even if it has 0 values left.
+	 *
+	 * @param  key    Key associated with the value to be removed.
 	 * @param  value  Value to remove from the index.
 	 */
 	void remove(const std::string &, unsigned int);