idle: Add more detailed documentation

Also remove the idle queue section from the DESIGN file.

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

DESIGN

@@ -66,70 +66,6 @@ Callbacks:
 
 
 
-Idle queue:
-	The idle queue is used to schedule function calls that run at a later
-	time.
-
-	A single queue instance needs to be able to run functions that take
-	different types of arguments.  This is done by creating an IdleBase
-	base class that the templated IdleTask class inherits from.
-
-- IdleBase:
-	class IdleBase {
-	private:
-		schedule();
-
-	public:
-		IdleBase();
-		~IdleBase();
-		virtual void run() = 0;
-	};
-
-- IdleTask:
-	template <class T>
-	class IdleTask : IdleBase {
-	private:
-		void (*func)(T &);
-		T &data;
-
-	public:
-		IdleTask(void (*)(T &), T);
-		void run();
-	};
-
-- Queue:
-	queue<IdleBase *> idle_queue;
-	float queued = 0.0
-	float serviced = 0.0
-
-- API:
-	void IdleBase :: schedule();
-		Add the idle task to the idle queue.  This should be called
-		by the IdleTask constructor.
-		queued++;
-
-	template <class T>
-	static inline void idle :: schedule(void (*)(T &), T);
-		Create a new IdleTask to run the function later.
-
-	bool idle :: run_task();
-		If there are tasks on the queue:
-			run the next task
-			scheduled++
-		If there are still tasks on the queue:
-			return true
-		else:
-			queued = 0
-			scheduled = 0
-			return false
-
-	float idle :: get_progress();
-		Return (serviced / queued) to the caller.  If there are no
-		tasks, return 1.0 to indicate that the queue is finished (and
-		to avoid a divide-by-zero error).
-
-
-
 Tag Database:
 	The tag database is actually several databases that describe every
 	track added by the user.  I do not expect the artist_db, album_db,

include/core/idle.h

@@ -6,88 +6,90 @@
 #define OCARINA_CORE_IDLE_H
 
 /**
- * Namespace for controlling idle tasks.
+ * The idle queue is used to schedule function calls to run at a
+ * later time.  It is expected that a higher layer can determine
+ * when the application is idle and call idle::run_task() accordingly.
+ *
+ * The idle layer keeps a count of the number of tasks added to the queue
+ * since the last time the queue was empty.  Whenever a task is scheduled,
+ * the "queued" count is incremented by 1.  When tasks are run, the "serviced"
+ * count is incremented by 1.  These counters are reset to 0 once the queue
+ * is empty.
  */
 namespace idle
 {
 
 	/**
-	 * Base class for creating new IdleTasks.
+	 * Base class used by the templated IdleTask class.  This lets
+	 * us create an idle queue storing IdleBase pointers to get
+	 * around potential templating issues.
 	 */
 	class IdleBase {
 	protected:
 		/**
-		 * Add the IdleBase to the idle queue.
+		 * Adds the IdleBase to the idle queue and increments
+		 * the "queued" counter by 1.
 		 */
 		void schedule();
 
 	public:
-		/**
-		 * Constructor for the IdleBase class.
-		 */
-		IdleBase();
-
-		/**
-		 * IdleBase destructor.
-		 */
-		virtual ~IdleBase();
-
-		/**
-		 * Run the idle task.
-		 */
-		virtual void run() = 0;
+		IdleBase();		/**< IdleBase constructor. */
+		virtual ~IdleBase();	/**< IdleBase destructor. */
+		virtual void run() = 0;	/**< Run the idle task. */
 	};
 
 
 	/**
-	 * Generic IdleTask class.
+	 * Generic IdleTask class.  This class is templated to allow
+	 * for scheduling functions that take different types of data
+	 * parameters.
 	 */
 	template <class T>
 	class IdleTask : public IdleBase {
 	private:
-		void (*func)(T &);
-		T data;
+		void (*_func)(T &);	/**< Function to call when run. */
+		T _data;		/**< Data to pass to the function. */
 
 	public:
 		/**
 		 * IdleTask constructor.
+		 *
 		 * @param  func  Function to call when running this task.
 		 * @param  data  Data to pass to the function.
 		 */
 		IdleTask(void (*)(T &), T);
 
-		/**
-		 * IdleTask destructor.
-		 */
-		~IdleTask();
-
-		/**
-		 * Run the IdleTask.
-		 */
-		void run();
+		~IdleTask();	/**< IdleTask destructor. */
+		void run();	/**< Call func(), passing data as the argument. */
 	};
 
 
 	/**
-	 * Create a new IdleTask and add it to the queue.
+	 * Creates a new IdleTask and adds it to the queue.
+	 *
 	 * @param  func  Function to call when running the new task.
 	 * @param  data  Data to pass to the function.
 	 */
 	template <class T>
-	static inline void schedule(void (*func)(T &), T param)
+	static inline void schedule(void (*func)(T &), T data)
 	{
-		new IdleTask<T>(func, param);
+		new IdleTask<T>(func, data);
 	}
 
 	/**
-	 * Run the next task on the idle queue.
-	 * @return True if there are still tracks on the queue, false otherwise.
+	 * Run the next task on the idle queue and increment the "serviced"
+	 * counter.  If this was the last task then the "queued" and
+	 * "serviced" values are reset to 0.
+	 *
+	 * @return True if there are still tasks on the queue, false otherwise.
 	 */
 	bool run_task();
 
 	/**
-	 * Call to find the progress of the idle queue.
-	 * @return A fraction representing the idle queue progress.
+	 * Use the values of the queued and serviced counters to find the
+	 * overall process of the idle queue (serviced / queued).
+	 *
+	 * @return The percentage of IdleTasks that have been run.
 	 */
 	float get_progress();
 

include/core/idle.hpp

@@ -9,8 +9,8 @@
 #define OCARINA_IDLE_HPP
 
 template <class T>
-idle :: IdleTask<T> :: IdleTask(void (*fn)(T &), T param)
-		     : func(fn), data(param)
+idle :: IdleTask<T> :: IdleTask(void (*func)(T &), T data)
+		     : _func(func), _data(data)
 {
 	IdleBase :: schedule();
 }
@@ -23,7 +23,7 @@ idle :: IdleTask<T> :: ~IdleTask()
 template <class T>
 void idle :: IdleTask<T> :: run()
 {
-	func(data);
+	_func(_data);
 }
 
 #endif /* OCARINA_IDLE_HPP */