IndexEntry: Write more detailed documentation

In addition to documentation updates, I also solve a few warnings that
Doxygen gives me.

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

core/filter.cpp

@@ -105,7 +105,7 @@ static void find_intersection(std::string &text, std::set<unsigned int> &res)
 	IndexEntry *it = filter_index.find(text);
 
 	if (it)
-		do_set_intersection(res, it->values, tmp);
+		do_set_intersection(res, it->_values, tmp);
 	res.swap(tmp);
 }
 
@@ -124,7 +124,7 @@ void filter :: search(const std::string &text, std::set<unsigned int> &res)
 	found = filter_index.find(*it);
 	if (!found)
 		return;
-	res = found->values;
+	res = found->_values;
 
 	for (it++; it != parsed.end(); it++)
 		find_intersection(*it, res);

core/index.cpp

@@ -6,40 +6,40 @@
 
 
 IndexEntry :: IndexEntry() {}
-IndexEntry :: IndexEntry(const std::string &k)
+IndexEntry :: IndexEntry(const std::string &key)
-	    : key(k)
+	    : _key(key)
 {}
 
 const std::string IndexEntry :: primary_key() const
 {
-	return key;
+	return _key;
 }
 
-void IndexEntry :: insert(unsigned int val)
+void IndexEntry :: insert(unsigned int value)
 {
-	values.insert(val);
+	_values.insert(value);
 }
 
-void IndexEntry :: remove(unsigned int val)
+void IndexEntry :: remove(unsigned int value)
 {
-	values.erase(val);
+	_values.erase(value);
 }
 
-void IndexEntry :: write(File &f)
+void IndexEntry :: write(File &file)
 {
 	std::set<unsigned int>::iterator it;
-	f << key << std::endl << values.size() << " ";
+	file << _key << std::endl << _values.size() << " ";
-	for (it = values.begin(); it != values.end(); it++)
+	for (it = _values.begin(); it != _values.end(); it++)
-		f << *it << " ";
+		file << *it << " ";
 }
 
-void IndexEntry :: read(File &f)
+void IndexEntry :: read(File &file)
 {
 	unsigned int num, val;
 
-	f >> key >> num;
+	file >> _key >> num;
 	for (unsigned int i = 0; i < num; i++) {
-		f >> val;
+		file >> val;
 		insert(val);
 	}
 }

core/playlist.cpp

@@ -24,7 +24,7 @@ public:
 		while (size() > 0)
 			del((unsigned)0);
 
-		for (it = ent->values.begin(); it != ent->values.end(); it++)
+		for (it = ent->_values.begin(); it != ent->_values.end(); it++)
 			add(tagdb :: lookup(*it));
 	}
 
@@ -46,7 +46,7 @@ void playlist :: init()
 	if (!ent)
 		return;
 
-	for (it = ent->values.begin(); it != ent->values.end(); it++)
+	for (it = ent->_values.begin(); it != ent->_values.end(); it++)
 		library :: get_queue()->del(tagdb :: lookup(*it));
 }
 
@@ -58,8 +58,8 @@ bool playlist :: has(Track *track, const std::string &name)
 	if (ent == NULL)
 		return false;
 
-	it = ent->values.find(track->index());
+	it = ent->_values.find(track->index());
-	return it != ent->values.end();
+	return it != ent->_values.end();
 }
 
 void playlist :: add(Track *track, const std::string &name)

include/core/index.h

@@ -12,52 +12,57 @@
 
 
 /**
- * Class for storing index information in a Database.
+ * The IndexEntry class is used to associate a specific key with a set of
+ * integer identifiers.  This lets us use a Database as an inverted index.
  */
 class IndexEntry : public DatabaseEntry {
 public:
-	std::string key;
+	std::string		_key;    /**< The term stored by this IndexEntry. */
-	std::set<unsigned int> values;
+	std::set<unsigned int>	_values; /**< Integers representing strings that
+					      contain this term. */
+
+	IndexEntry(); /**< Create an empty IndexEntry. */
 
 	/**
-	 * Default IndexEntry constructor.
+	 * Create an IndexEntry with a specific key.
-	 */
+	 *
-	IndexEntry();
-
-	/**
-	 * IndexEntry constructor.
 	 * @param  key  The key associated with this IndexEntry.
 	 */
 	IndexEntry(const std::string &);
 
 
 	/**
-	 * Access this IndexEntry's key.
+	 * Access the key stored by this IndexEntry.
-	 * @return This IndexEntry's key.
+	 *
+	 * @return IndexEntry::_key.
 	 */
 	const std::string primary_key() const;
 
 	/**
-	 * Add a new value to this entry.
+	 * Add a new value to this IndexEntry.
+	 *
 	 * @param  value  The new value to add.
 	 */
 	void insert(unsigned int);
 
 	/**
-	 * Remove a value from this entry.
+	 * Remove a value from this IndexEntry.
+	 *
 	 * @param  value  The value to remove.
 	 */
 	void remove(unsigned int);
 
 
 	/**
-	 * Write an IndexEntry to file
+	 * Write an IndexEntry to file.
+	 *
 	 * @param  file  The file to use when writing data.
 	 */
 	void write(File &);
 
 	/**
-	 * Read an IndexEntry from file
+	 * Read an IndexEntry from file.
+	 *
 	 * @param  file  The file read from.
 	 */
 	void read(File &);

lib/colmgr.cpp

@@ -57,7 +57,7 @@ static void remove_banned_tracks()
 	if (!ent)
 		return;
 
-	for (it = ent->values.begin(); it != ent->values.end(); it++)
+	for (it = ent->_values.begin(); it != ent->_values.end(); it++)
 		library :: get_queue()->del(tagdb :: lookup(*it));
 }
 

tests/core/index.cpp

@@ -44,12 +44,12 @@ static void test_single_item()
 
 	test_not_equal(it, IDX_NULL);
 	test_equal(index.size(), (unsigned)1);
-	test_equal(it->values.size(), (size_t)1);
+	test_equal(it->_values.size(), (size_t)1);
-	test_equal(*(it->values.begin()), (unsigned)0);
+	test_equal(*(it->_values.begin()), (unsigned)0);
 
 	index.remove("a", 0);
 	test_equal(index.size(), (unsigned)1);
-	test_equal(it->values.size(), (size_t)0);
+	test_equal(it->_values.size(), (size_t)0);
 }
 
 static void test_insertion(struct TestArgs *args)
@@ -80,7 +80,7 @@ static void test_insertion(struct TestArgs *args)
 			check_equal(it, IDX_NULL);
 		else {
 			check_not_equal(it, IDX_NULL);
-			check_equal(it->values.size(), (size_t)args->n);
+			check_equal(it->_values.size(), (size_t)args->n);
 		}
 	}
 	test :: success();
@@ -102,7 +102,7 @@ static void test_removal(struct TestArgs *args)
 			check_equal(it, IDX_NULL);
 		else {
 			check_not_equal(it, IDX_NULL);
-			check_equal(it->values.size(), (size_t)0);
+			check_equal(it->_values.size(), (size_t)0);
 		}
 	}
 	test :: success();
@@ -135,7 +135,7 @@ static void test_saving(struct TestArgs *args)
 		} else {
 			check_not_equal(it1, IDX_NULL);
 			check_not_equal(it2, IDX_NULL);
-			check_equal(it1->values.size(), it2->values.size());
+			check_equal(it1->_values.size(), it2->_values.size());
 		}
 	}
 	test :: success();

tests/core/playlist.cpp

@@ -27,10 +27,10 @@ static void test_init()
 	playlist :: init();
 
 	ent = playlist :: get_tracks("Banned");
-	test_equal(ent->values.size(), (size_t)4);
+	test_equal(ent->_values.size(), (size_t)4);
 	test_equal(library :: get_queue()->size(), (unsigned)20);
 	ent = playlist :: get_tracks("Favorites");
-	test_equal(ent->values.size(), (size_t)8);
+	test_equal(ent->_values.size(), (size_t)8);
 	ent = playlist :: get_tracks("No Such Playlist");
 	test_equal(ent, IDX_NULL);
 }
@@ -54,14 +54,14 @@ static void test_add()
 
 	playlist :: add(tagdb :: lookup(5), "Banned");
 	ent = playlist :: get_tracks("Banned");
-	test_equal(ent->values.size(), (size_t)5);
+	test_equal(ent->_values.size(), (size_t)5);
 	test_equal(q->size(), (unsigned)8);
 	test_equal(l->size(), (unsigned)19);
 
 	playlist :: add(tagdb :: lookup(16), "Favorites");
 	playlist :: add(tagdb :: lookup(5), "Favorites");
 	ent = playlist :: get_tracks("Favorites");
-	test_equal(ent->values.size(), (size_t)9);
+	test_equal(ent->_values.size(), (size_t)9);
 	test_equal(q->size(), (unsigned)9);
 
 	playlist :: add(tagdb :: lookup(6), "No Playlist");
@@ -76,13 +76,13 @@ static void test_delete()
 
 	playlist :: del(tagdb :: lookup(5), "Banned");
 	ent = playlist :: get_tracks("Banned");
-	test_equal(ent->values.size(), (size_t)4);
+	test_equal(ent->_values.size(), (size_t)4);
 	test_equal(q->size(), (unsigned)9);
 	test_equal(l->size(), (unsigned)20);
 
 	playlist :: del(tagdb :: lookup(5), "Favorites");
 	ent = playlist :: get_tracks("Favorites");
-	test_equal(ent->values.size(), (size_t)8);
+	test_equal(ent->_values.size(), (size_t)8);
 	test_equal(q->size(), (unsigned)8);
 
 	playlist :: del(tagdb :: lookup(6), "No Playlist");