deck: Update doxygen documentation

Also remove the deck section of the DESIGN document.

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

DESIGN

@@ -66,136 +66,6 @@ Callbacks:
 
 
 
-Deck:
-	The deck is used to hold temporary queues created by the user.  This
-	layer is also in charge of maintaining a "recently played" queue of
-	tracks.
-
-	The deck will be saved to the file "deck".  When upgrading from file
-	version V0 to V1, use the saved random flag and sort order to set up
-	the library_q.
-
-- TempQueue:
-	class TempQueue : public Queue {
-	public:
-		TempQueue(bool);
-
-		void set_flag(queue_flag);
-		void unset_flag(queue_flag);
-
-		unsigned int add(Track *);
-		void del(Track *);
-		void del(unsigned int);
-
-		void sort(sort_t, bool);
-	};
-
-- Deck:
-	list<TempQueue> deck;
-
-	V0:
-		File << library_q.random << library_q.sort_order().size();
-		File << lib12order()[N].field << lib12order()[N].ascending;
-		File << deck.size() << endl;
-		File << deck[0] << endl;
-		File << deck[N] << endl;
-
-	V1:
-		File << deck.size() << endl;
-		File << deck[0] << endl;
-		File << deck[1] << endl;
-
-- RecentQueue:
-	class RecentQueue : public Queue {
-	public:
-		RecentQueue();
-		unsigned int add(Track *);
-	};
-
-- TempQueue API:
-	TempQueue :: TempQueue(bool random);
-		Initialize a new TempQueue with the flag Q_ENABLED set.
-		If random is True then also set the Q_RANDOM flag.
-
-	void TempQueue :: set_flag(queue_flag flag);
-	void TempQueue :: unset_flag(queue_flag flag);
-	unsigned int TempQueue :: add(Track *track);
-	void TempQueue :: del(Track *track);
-	void TempQueue :: del(unsigned int index);
-	void TempQueue :: sort(sort_t field, bool ascending);
-		These functions are all wrappers around the basic Queue
-		functions of the same name.  First, call the corresponding
-		Queue :: <whatever>() function to make the correct Queue
-		modification.  Then, call deck :: write() to save changes to
-		disk.
-
-- RecentQueue API:
-	RecentQueue :: RecentQueue();
-		Initialize a Queue with the flags Q_ENABLED, Q_REPEAT, and
-		Q_NO_SORT set.
-
-	unsigned int RecentQueue :: add(Track *track);
-		The RecentQueue is designed to be a uniqueue queue that displays
-		the most recent tracks first.
-
-		del(track);
-		_cur = 0;
-		return _add_at(track, 0);
-
-- API
-	void deck :: init();
-		Read the deck file from disk and restore the queues.
-
-	void deck :: write(File &);
-		Read or write the playqueue file.  This will be called
-		from the audio layer to store state.
-
-	Queue *deck :: create(bool random);
-		Adds a new queue to the end of the deck and return a pointer
-		to it.  Save the deck to disk.
-
-	void deck :: destroy(Queue *queue);
-		Remove the requested queue from the deck and trigger the
-		on_pq_removed() callback.  Save the deck to disk.
-
-	void deck :: move(Queue *queue, unsigned int pos);
-		Move the queue to the new location in the deck.  Save the deck
-		to disk.
-
-	unsigned int deck :: index(Queue *queue);
-		Return the index of the queue in the deck or deck.size() if
-		the queue is not currently in the deck.
-
-	Queue *deck :: get(unsigned int index);
-		Return the queue at the requested index, or NULL if no queue
-		is found.
-
-	Track *deck :: next();
-		Find the first enabled queue on the deck and return the track
-		given by queue->next().
-
-		If the queue is empty after calling next(), call destroy() to
-		remove it from the list.
-
-		If there are no enabled queues, return a track from the library
-		queue.  If the library queue is empty, return NULL.
-
-		If the result is non-NULL, add the found track to the recent
-		queue.
-
-		Save the deck before returning.
-
-	Track *deck :: prev();
-		Return the track given by recent_queue->next().  If the recent
-		queue is empty, return NULL.
-
-	list<Queue> &deck :: get_queues();
-		Return the list of queues to the caller.
-
-	Queue *deck :: get_queue();
-		Return the RecentQueue to the caller.
-
-
 Audio Driver:
 	The audio driver creates a way to fake audio playback for testing.  This
 	will allow for more accurate tests, since I will know in advance what

core/deck.cpp

@@ -153,7 +153,7 @@ void deck :: destroy(Queue *queue)
 	}
 }
 
-void deck :: move(Queue *queue, unsigned int new_pos)
+void deck :: move(Queue *queue, unsigned int index)
 {
 	unsigned int old_pos = deck :: index(queue);
 	std::list<TempQueue>::iterator it_old = queue_deck.begin();
@@ -163,11 +163,11 @@ void deck :: move(Queue *queue, unsigned int new_pos)
 		if (i < old_pos)
 			it_old++;
 
-		if (i < new_pos)
+		if (i < index)
 			it_new++;
 	}
 
-	if (new_pos > old_pos)
+	if (index > old_pos)
 		it_new++;
 
 	queue_deck.splice(it_new, queue_deck, it_old);

include/core/deck.h

@@ -9,6 +9,10 @@
 #include <list>
 
 
+/**
+ * A TempQueue is a wrapper around the Queue class that
+ * allows us to save the list of queues when necessary.
+ */
 class TempQueue : public Queue
 {
 public:
@@ -25,8 +29,17 @@ public:
 	void sort(sort_t, bool);
 };
 
+
 /**
- * Namespace for manipulating Queue deck.
+ * The deck is used to hold temporary queues created by the user.  This
+ * code is also in charge of maintaining a "recently played" queue of
+ * songs that have just played.
+ *
+ * When saving to disk:
+ * 	... << deck.size() << endl;
+ * 	... << deck[0] << endl;
+ * 	...
+ * 	... << deck[N] <<< endl;
  */
 namespace deck
 {
@@ -58,7 +71,7 @@ namespace deck
 	void destroy(Queue *);
 
 	/**
-	 * Move the queue to a new location.
+	 * Move the queue to a new location in the deck.
 	 *
 	 * @param  queue  The queue to be moved.
 	 * @param  index  The new index of the queue.