From c3dc601f720ec9181f302fb6882ad577edc4cd23 Mon Sep 17 00:00:00 2001
From: Anna Schumaker <Anna@OcarinaProject.net>
Date: Sun, 2 Nov 2014 09:29:13 -0500
Subject: [PATCH] DatabaseEntry:  Write more detailed documentation

I transfer everything from my DESIGN file into doxygen, and then remove
the section from DESIGN.

Signed-off-by: Anna Schumaker <Anna@OcarinaProject.net>
---
 DESIGN                  | 37 -------------------------------------
 include/core/database.h | 35 ++++++++++++++++++-----------------
 2 files changed, 18 insertions(+), 54 deletions(-)

diff --git a/DESIGN b/DESIGN
index 669bf643..ac69dbbe 100644
--- a/DESIGN
+++ b/DESIGN
@@ -66,43 +66,6 @@ Callbacks:
 
 
 
-Database Entry:
-	The database entry class is a base class used for storing data inside
-	a database (below).  The valid flag and id counter will be managed by
-	the database itself, and should be initialized to false and 0.
-
-- DatabaseEntry:
-	class DatabaseEntry {
-	public:
-		unsigned int id;
-
-		DatabaseEntry();
-		virtual void ~DatabaseEntry() = 0;
-		virtual const std::string primary_key() const = 0;
-
-		virtual void write(File &) = 0;
-		virtual void read(File &) = 0;
-	};
-
-- API:
-	DatabaseEntry :: DatabaseEntry():
-		Set id = 0.
-
-	const std::string DatabaseEntry :: primary_key() const;
-		This function should return a unique string representing this
-		DatabaseEntry instance, which will be used to prevent
-		duplicates in a database.  This string is not expected to
-		change once a DatabaseEntry has been initialized.
-
-	void DatabaseEntry :: write(File &);
-		This function is called to write a specific DatabaseEntry to
-		file.
-
-	void DatabaseEntry :: read(File &);
-		This function is called to read a DatabaseEntry from a file.
-
-
-
 Database:
 	Databases are a generic store for information used by Ocarina.  Users
 	need to inherit from a DatabaseEntry class (above) to properly use a
diff --git a/include/core/database.h b/include/core/database.h
index fc1d2338..a59079c0 100644
--- a/include/core/database.h
+++ b/include/core/database.h
@@ -12,37 +12,38 @@
 
 
 /**
- * Class representing a single item in a Database.
+ * The DatabaseEntry class is the base class for storing
+ * generic data inside a Database.
  */
 class DatabaseEntry {
 public:
-	/** The index of this item */
-	unsigned int id;
+	unsigned int id;  /**< The location of this item in the Database */
+
+	DatabaseEntry();		/** Initialize id to 0. */
+	virtual ~DatabaseEntry() = 0;	/**< Virtual destructor */
 
 	/**
-	 * 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.
+	 * The primary key of a DatabaseEntry is a unique string representing
+	 * a single DatabaseEntry instance.  This is used for preventing
+	 * duplicate entries in a Database.  The primary key is not expected
+	 * to change once a DatabaseEntry has been initialized.
+	 *
+	 * @return A unique string identifying a DatabaseEntry instance.
 	 */
 	virtual const std::string primary_key() const = 0;
 
 	/**
-	 * Called to write a DatabaseItem to disk.
+	 * This function is called by the Database to write a specific
+	 * DatabaseEntry instance to disk.
+	 *
 	 * @param  file  File to use when writing data.
 	 */
 	virtual void write(File &) = 0;
 
 	/**
-	 * Called to read a DatabaseItem from disk.
+	 * This function is called by the Database to read a single
+	 * DatabaseEntry instance from disk.
+	 *
 	 * @param  file  File to use when reading data.
 	 */
 	virtual void read(File &) = 0;