From 9a5549a264d353e3287960144c62c52ffd98c08a Mon Sep 17 00:00:00 2001
From: Anna Schumaker <Anna@OcarinaProject.net>
Date: Fri, 17 Oct 2014 17:15:02 -0400
Subject: [PATCH] database:  Add doxygen documentation

Signed-off-by: Anna Schumaker <Anna@OcarinaProject.net>
---
 core/database.cpp         |   3 +-
 include/core/database.h   | 100 +++++++++++++++++++++++++++++++++++++-
 include/core/database.hpp |   3 +-
 3 files changed, 102 insertions(+), 4 deletions(-)

diff --git a/core/database.cpp b/core/database.cpp
index 0e7c2d17..c70f8082 100644
--- a/core/database.cpp
+++ b/core/database.cpp
@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2013 (c) Anna Schumaker.
  */
 #include <core/database.h>
diff --git a/include/core/database.h b/include/core/database.h
index 9a5d703b..fc1d2338 100644
--- a/include/core/database.h
+++ b/include/core/database.h
@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2013 (c) Anna Schumaker.
  */
 #ifndef OCARINA_CORE_DATABASE_H
@@ -10,19 +11,47 @@
 #include <vector>
 
 
+/**
+ * Class representing a single item in a Database.
+ */
 class DatabaseEntry {
 public:
+	/** The index of this item */
 	unsigned int id;
 
+	/**
+	 * Constructor
+	 */
 	DatabaseEntry();
+
+	/**
+	 * Destructor
+	 */
 	virtual ~DatabaseEntry() = 0;
+
+	/**
+	 * Used to find the primary key of a database item.
+	 * @return A uniqueue string identifying a single item in the database.
+	 */
 	virtual const std::string primary_key() const = 0;
+
+	/**
+	 * Called to write a DatabaseItem to disk.
+	 * @param  file  File to use when writing data.
+	 */
 	virtual void write(File &) = 0;
+
+	/**
+	 * Called to read a DatabaseItem from disk.
+	 * @param  file  File to use when reading data.
+	 */
 	virtual void read(File &) = 0;
 };
 
 
-
+/**
+ * Our custom database class.
+ */
 template <class T>
 class Database {
 private:
@@ -33,25 +62,92 @@ private:
 	File _file;
 
 public:
+	/** Iterator access for our backing std::vector */
 	typedef typename std::vector<T *>::iterator iterator;
+	/** Const iterator access for our backing std::vector */
 	typedef typename std::vector<T *>::const_iterator const_iterator;
 
+	/**
+	 * Database constructor.
+	 * @param  filepath  File on disk that will be written to.
+	 * @param  autosave  True if database should be saved on every modification.
+	 */
 	Database(std::string, bool);
+
+	/**
+	 * Database destructor.
+	 */
 	~Database();
+
+	/**
+	 * Called to write the database to disk.
+	 */
 	void save();
+
+	/**
+	 * Called to save the database after modifications.
+	 */
 	void autosave();
+
+	/**
+	 * Called to load the database from disk.
+	 */
 	void load();
 
+
+	/**
+	 * Add a new item to the database.
+	 * @param  item  The new item to be added.
+	 * @return A pointer to the item in the database.
+	 */
 	T *insert(const T &);
+
+	/**
+	 * Remove an item from the database.
+	 * @param  index  The index of the item that should be removed.
+	 */
 	void remove(unsigned int);
+
+	/**
+	 * Find the size of the database.
+	 * @return The number of valid items in the database.
+	 */
 	unsigned int size();
+
+	/**
+	 * Find the actual size of the backing vector.
+	 * @return The number valid and invalid items in the database.
+	 */
 	unsigned int actual_size();
 
+
+	/**
+	 * Returns an iterator pointing to the first entry in the database.
+	 */
 	iterator begin();
+
+	/**
+	 * Returns an iterator pointing past the end of the database.
+	 */
 	iterator end();
+
+	/**
+	 * Returns an iterator pointing to the next valid item in the database.
+	 */
 	iterator next(iterator &);
 
+	/**
+	 * Returns the database item at index n.
+	 * @param  n  The database index to access.
+	 * @return A valid DatabaseItem or NULL.
+	 */
 	T *at(unsigned int);
+
+	/**
+	 * Find a DatabaseItem with a specific primary key.
+	 * @param  key  The key to search for.
+	 * @return A valid DatabaseItem or NULL.
+	 */
 	T *find(const std::string &);
 };
 
diff --git a/include/core/database.hpp b/include/core/database.hpp
index 0ae77a93..2a7d7d53 100644
--- a/include/core/database.hpp
+++ b/include/core/database.hpp
@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2013 (c) Anna Schumaker.
  *
  * DO NOT INCLUDE THIS FILE DIRECTLY.  THIS IS A TEMPLATE DEFINITION FILE